@cpujia/codex-mcp-server 1.0.0 → 2.0.0

package/README.md

@@ -1,8 +1,11 @@
 # Codex MCP Server
 
+[![npm version](https://badge.fury.io/js/%40cpujia%2Fcodex-mcp-server.svg)](https://www.npmjs.com/package/@cpujia/codex-mcp-server)
+[![npm downloads](https://img.shields.io/npm/dm/@cpujia/codex-mcp-server.svg)](https://www.npmjs.com/package/@cpujia/codex-mcp-server)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/)
+[![GitHub stars](https://img.shields.io/github/stars/CPU-JIA/codex-mcp-server.svg)](https://github.com/CPU-JIA/codex-mcp-server/stargazers)
 
 MCP Server for integrating OpenAI Codex `/v1/responses` API with Claude Code. Enables Claude Code to leverage GPT-5.3-Codex's powerful code generation capabilities.
 

package/dist/codex-client.d.ts

@@ -1,15 +1,26 @@
+type ReasoningEffort = "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
 interface CodexClientConfig {
     baseURL: string;
     apiKey: string;
     model: string;
     timeout: number;
     maxTokens: number;
-    reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+    reasoningEffort?: ReasoningEffort;
+}
+interface JsonSchemaFormat {
+    name: string;
+    schema: Record<string, unknown>;
+}
+interface CodexRequestOptions {
+    instructions: string;
+    input: string;
+    jsonSchema?: JsonSchemaFormat;
+    reasoningEffort?: ReasoningEffort;
+    maxTokens?: number;
 }
 export declare class CodexClient {
     private config;
     constructor(config: CodexClientConfig);
-    generate(input: string): Promise<string>;
-    generateStream(input: string, onChunk: (text: string) => void): Promise<void>;
+    request(options: CodexRequestOptions): Promise<string>;
 }
-export {};
+export type { CodexClientConfig, CodexRequestOptions, JsonSchemaFormat, ReasoningEffort, };

package/dist/codex-client.js

@@ -3,23 +3,30 @@ export class CodexClient {
     constructor(config) {
         this.config = config;
     }
-    async generate(input) {
+    async request(options) {
         const controller = new AbortController();
         const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
         try {
+            const effort = options.reasoningEffort ?? this.config.reasoningEffort;
+            const maxTokens = options.maxTokens ?? this.config.maxTokens;
             const requestBody = {
                 model: this.config.model,
-                input: [
-                    {
-                        role: "user",
-                        content: input,
-                    },
-                ],
-                max_output_tokens: this.config.maxTokens,
+                instructions: options.instructions,
+                input: [{ role: "user", content: options.input }],
+                max_output_tokens: maxTokens,
+                store: false,
             };
-            if (this.config.reasoningEffort) {
-                requestBody.reasoning = {
-                    effort: this.config.reasoningEffort,
+            if (effort) {
+                requestBody.reasoning = { effort };
+            }
+            if (options.jsonSchema) {
+                requestBody.text = {
+                    format: {
+                        type: "json_schema",
+                        name: options.jsonSchema.name,
+                        strict: true,
+                        schema: options.jsonSchema.schema,
+                    },
                 };
             }
             const response = await fetch(`${this.config.baseURL}/responses`, {
@@ -40,7 +47,9 @@ export class CodexClient {
             if (data.status !== "completed") {
                 throw new Error(`Unexpected response status: ${data.status}`);
             }
-            const textContent = data.content.find((c) => c.type === "output_text");
+            const textContent = data.output
+                ?.flatMap((item) => item.content ?? [])
+                .find((c) => c.type === "output_text");
             if (!textContent?.text) {
                 throw new Error("No text content in response");
             }
@@ -57,83 +66,4 @@ export class CodexClient {
             throw new Error(`Unknown error: ${String(error)}`);
         }
     }
-    async generateStream(input, onChunk) {
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
-        try {
-            const requestBody = {
-                model: this.config.model,
-                input: [
-                    {
-                        role: "user",
-                        content: input,
-                    },
-                ],
-                max_output_tokens: this.config.maxTokens,
-                stream: true,
-            };
-            if (this.config.reasoningEffort) {
-                requestBody.reasoning = {
-                    effort: this.config.reasoningEffort,
-                };
-            }
-            const response = await fetch(`${this.config.baseURL}/responses`, {
-                method: "POST",
-                headers: {
-                    "Content-Type": "application/json",
-                    Authorization: `Bearer ${this.config.apiKey}`,
-                },
-                body: JSON.stringify(requestBody),
-                signal: controller.signal,
-            });
-            clearTimeout(timeoutId);
-            if (!response.ok) {
-                const errorText = await response.text();
-                throw new Error(`Codex API error (${response.status}): ${errorText}`);
-            }
-            if (!response.body) {
-                throw new Error("No response body");
-            }
-            const reader = response.body.getReader();
-            const decoder = new TextDecoder();
-            let buffer = "";
-            while (true) {
-                const { done, value } = await reader.read();
-                if (done)
-                    break;
-                buffer += decoder.decode(value, { stream: true });
-                const lines = buffer.split("\n");
-                buffer = lines.pop() || "";
-                for (const line of lines) {
-                    if (!line.trim() || line.startsWith(":"))
-                        continue;
-                    if (line.startsWith("data: ")) {
-                        const data = line.slice(6);
-                        if (data === "[DONE]") {
-                            return;
-                        }
-                        try {
-                            const parsed = JSON.parse(data);
-                            if (parsed.type === "response.output_text.delta") {
-                                onChunk(parsed.delta || "");
-                            }
-                        }
-                        catch (e) {
-                            console.error("Failed to parse SSE data:", e);
-                        }
-                    }
-                }
-            }
-        }
-        catch (error) {
-            clearTimeout(timeoutId);
-            if (error instanceof Error) {
-                if (error.name === "AbortError") {
-                    throw new Error(`Request timeout after ${this.config.timeout}ms`);
-                }
-                throw error;
-            }
-            throw new Error(`Unknown error: ${String(error)}`);
-        }
-    }
 }

package/dist/index.js

@@ -4,10 +4,12 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { CodexClient } from "./codex-client.js";
 import { tools } from "./tools.js";
+// --- 配置 ---
 const CODEX_API_BASE_URL = process.env.CODEX_API_BASE_URL;
 const CODEX_API_KEY = process.env.CODEX_API_KEY;
 const CODEX_MODEL = process.env.CODEX_MODEL || "gpt-5.3-codex";
-const CODEX_REASONING_EFFORT = process.env.CODEX_REASONING_EFFORT;
+const CODEX_REASONING_EFFORT = (process.env.CODEX_REASONING_EFFORT ||
+    "high");
 if (!CODEX_API_BASE_URL || !CODEX_API_KEY) {
     console.error("Error: CODEX_API_BASE_URL and CODEX_API_KEY must be set");
     process.exit(1);
@@ -16,18 +18,201 @@ const codexClient = new CodexClient({
     baseURL: CODEX_API_BASE_URL,
     apiKey: CODEX_API_KEY,
     model: CODEX_MODEL,
-    timeout: parseInt(process.env.CODEX_TIMEOUT || "60000"),
-    maxTokens: parseInt(process.env.CODEX_MAX_TOKENS || "4096"),
+    timeout: parseInt(process.env.CODEX_TIMEOUT || "120000"),
+    maxTokens: parseInt(process.env.CODEX_MAX_TOKENS || "16384"),
     reasoningEffort: CODEX_REASONING_EFFORT,
 });
-const server = new Server({
-    name: "codex-mcp-server",
-    version: "1.0.0",
-}, {
-    capabilities: {
-        tools: {},
+// --- JSON Schemas（强制结构化输出） ---
+const GENERATE_SCHEMA = {
+    name: "generate_result",
+    schema: {
+        type: "object",
+        properties: {
+            code: { type: "string", description: "Generated code" },
+            language: { type: "string", description: "Programming language" },
+            explanation: {
+                type: "string",
+                description: "Brief explanation of approach and key decisions",
+            },
+            dependencies: {
+                type: "array",
+                items: { type: "string" },
+                description: "Required packages or imports",
+            },
+        },
+        required: ["code", "language", "explanation", "dependencies"],
+        additionalProperties: false,
     },
-});
+};
+const REVIEW_SCHEMA = {
+    name: "review_result",
+    schema: {
+        type: "object",
+        properties: {
+            findings: {
+                type: "array",
+                items: {
+                    type: "object",
+                    properties: {
+                        severity: {
+                            type: "string",
+                            enum: ["critical", "high", "medium", "low", "info"],
+                        },
+                        category: {
+                            type: "string",
+                            enum: [
+                                "security",
+                                "performance",
+                                "best-practice",
+                                "bug",
+                                "maintainability",
+                            ],
+                        },
+                        location: {
+                            type: "string",
+                            description: "Line number or code section",
+                        },
+                        issue: {
+                            type: "string",
+                            description: "Description of the problem",
+                        },
+                        suggestion: {
+                            type: "string",
+                            description: "Concrete fix or improvement",
+                        },
+                    },
+                    required: ["severity", "category", "location", "issue", "suggestion"],
+                    additionalProperties: false,
+                },
+            },
+            summary: { type: "string", description: "Overall assessment" },
+            score: { type: "number", description: "Quality score 0-100" },
+        },
+        required: ["findings", "summary", "score"],
+        additionalProperties: false,
+    },
+};
+const TEST_SCHEMA = {
+    name: "test_result",
+    schema: {
+        type: "object",
+        properties: {
+            test_code: {
+                type: "string",
+                description: "Complete test file content",
+            },
+            language: { type: "string", description: "Programming language" },
+            framework: { type: "string", description: "Test framework used" },
+            test_cases: {
+                type: "array",
+                items: {
+                    type: "object",
+                    properties: {
+                        name: { type: "string", description: "Test name" },
+                        description: {
+                            type: "string",
+                            description: "What this test verifies",
+                        },
+                        type: {
+                            type: "string",
+                            enum: ["unit", "integration", "edge-case", "error-handling"],
+                        },
+                    },
+                    required: ["name", "description", "type"],
+                    additionalProperties: false,
+                },
+            },
+            coverage_notes: {
+                type: "string",
+                description: "What is covered and gaps remaining",
+            },
+        },
+        required: [
+            "test_code",
+            "language",
+            "framework",
+            "test_cases",
+            "coverage_notes",
+        ],
+        additionalProperties: false,
+    },
+};
+// --- Developer 指令（per-tool） ---
+const INSTRUCTIONS = {
+    generate: [
+        "You are a senior software engineer. Generate production-quality code.",
+        "",
+        "Rules:",
+        "- Write complete, runnable code — no placeholders, no TODOs",
+        "- Include necessary imports and type definitions",
+        "- Follow language-specific conventions and idioms",
+        "- If project context is provided, follow its conventions strictly",
+        "- Optimize for readability first, performance second",
+    ].join("\n"),
+    review: [
+        "You are a security-focused code reviewer. Provide independent, critical analysis.",
+        "",
+        "Rules:",
+        "- Reference exact locations in the code (line numbers or function names)",
+        "- Prioritize: critical > high > medium > low > info",
+        "- For each finding, provide a concrete, actionable fix",
+        "- Score fairly: 90+ excellent, 70-89 good, 50-69 needs work, <50 concerning",
+        "- Be honest — don't inflate scores. Empty findings array is fine for clean code",
+    ].join("\n"),
+    test: [
+        "You are a testing expert. Write comprehensive test suites that catch real bugs.",
+        "",
+        "Rules:",
+        "- Generate a complete, runnable test file",
+        "- Cover: happy path, edge cases, error handling, boundary conditions",
+        "- Use the specified framework's idioms and best practices",
+        "- Include descriptive test names explaining expected behavior",
+        "- Mock external dependencies appropriately",
+        "- Think about what would break in production and test that",
+    ].join("\n"),
+};
+// --- 输入构建 ---
+function buildInput(sections) {
+    const parts = [];
+    for (const [label, content] of Object.entries(sections)) {
+        if (content?.trim()) {
+            parts.push(`## ${label}\n${content.trim()}`);
+        }
+    }
+    return parts.join("\n\n");
+}
+// --- 安全 JSON 解析（带 fallback） ---
+function safeJsonParse(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        // API 可能不支持 text.format，返回了非 JSON
+        return null;
+    }
+}
+function formatGenerateOutput(parsed) {
+    let text = `\`\`\`${parsed.language}\n${parsed.code}\n\`\`\``;
+    text += `\n\n**Explanation:** ${parsed.explanation}`;
+    if (parsed.dependencies.length > 0) {
+        text += `\n\n**Dependencies:** ${parsed.dependencies.join(", ")}`;
+    }
+    return text;
+}
+function formatReviewOutput(parsed) {
+    const findings = parsed.findings
+        .map((f, i) => `${i + 1}. **[${f.severity.toUpperCase()}]** ${f.category} — \`${f.location}\`\n   Issue: ${f.issue}\n   Fix: ${f.suggestion}`)
+        .join("\n\n");
+    return `**Score: ${parsed.score}/100**\n\n${parsed.summary}\n\n---\n\n${findings || "No issues found."}`;
+}
+function formatTestOutput(parsed) {
+    const cases = parsed.test_cases
+        .map((tc) => `- [${tc.type}] **${tc.name}**: ${tc.description}`)
+        .join("\n");
+    return `\`\`\`${parsed.language}\n${parsed.test_code}\n\`\`\`\n\n**Framework:** ${parsed.framework}\n**Test Cases (${parsed.test_cases.length}):**\n${cases}\n\n**Coverage:** ${parsed.coverage_notes}`;
+}
+// --- MCP Server ---
+const server = new Server({ name: "codex-mcp-server", version: "2.0.0" }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => {
     return { tools };
 });
@@ -36,69 +221,88 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     try {
         switch (name) {
             case "codex_generate": {
-                const { prompt, language, context } = args;
-                const input = buildGenerateInput(prompt, language, context);
-                const result = await codexClient.generate(input);
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: result,
-                        },
-                    ],
-                };
-            }
-            case "codex_edit": {
-                const { code, instruction, language } = args;
-                const input = buildEditInput(code, instruction, language);
-                const result = await codexClient.generate(input);
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: result,
-                        },
-                    ],
-                };
+                const { prompt, language, project_context, files, conversation_context, } = args;
+                const input = buildInput({
+                    Task: prompt,
+                    Language: language,
+                    "Project Context": project_context,
+                    "Reference Files": files,
+                    "Conversation Context": conversation_context,
+                });
+                const raw = await codexClient.request({
+                    instructions: INSTRUCTIONS.generate,
+                    input,
+                    jsonSchema: GENERATE_SCHEMA,
+                });
+                const parsed = safeJsonParse(raw);
+                if (parsed && typeof parsed.code === "string") {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: formatGenerateOutput(parsed),
+                            },
+                        ],
+                    };
+                }
+                // Fallback：API 不支持结构化输出时直接返回原文
+                return { content: [{ type: "text", text: raw }] };
             }
-            case "codex_explain": {
-                const { code, language, focus } = args;
-                const input = buildExplainInput(code, language, focus);
-                const result = await codexClient.generate(input);
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: result,
-                        },
-                    ],
-                };
+            case "codex_review": {
+                const { code, language, focus, project_context, conversation_context } = args;
+                const input = buildInput({
+                    "Code to Review": `\`\`\`${language ?? ""}\n${code}\n\`\`\``,
+                    Language: language,
+                    "Focus Area": focus ?? "all",
+                    "Project Context": project_context,
+                    "Review Context": conversation_context,
+                });
+                const raw = await codexClient.request({
+                    instructions: INSTRUCTIONS.review,
+                    input,
+                    jsonSchema: REVIEW_SCHEMA,
+                    reasoningEffort: "high",
+                });
+                const parsed = safeJsonParse(raw);
+                if (parsed && Array.isArray(parsed.findings)) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: formatReviewOutput(parsed),
+                            },
+                        ],
+                    };
+                }
+                return { content: [{ type: "text", text: raw }] };
             }
-            case "codex_fix": {
-                const { code, error, language } = args;
-                const input = buildFixInput(code, error, language);
-                const result = await codexClient.generate(input);
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: result,
-                        },
-                    ],
-                };
-            }
-            case "codex_refactor": {
-                const { code, goal, language } = args;
-                const input = buildRefactorInput(code, goal, language);
-                const result = await codexClient.generate(input);
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: result,
-                        },
-                    ],
-                };
+            case "codex_test": {
+                const { code, language, framework, project_context, conversation_context, } = args;
+                const input = buildInput({
+                    "Code to Test": `\`\`\`${language ?? ""}\n${code}\n\`\`\``,
+                    Language: language,
+                    "Test Framework": framework,
+                    "Project Context": project_context,
+                    Context: conversation_context,
+                });
+                const raw = await codexClient.request({
+                    instructions: INSTRUCTIONS.test,
+                    input,
+                    jsonSchema: TEST_SCHEMA,
+                    reasoningEffort: "high",
+                });
+                const parsed = safeJsonParse(raw);
+                if (parsed && typeof parsed.test_code === "string") {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: formatTestOutput(parsed),
+                            },
+                        ],
+                    };
+                }
+                return { content: [{ type: "text", text: raw }] };
             }
             default:
                 throw new Error(`Unknown tool: ${name}`);
@@ -107,73 +311,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
         return {
-            content: [
-                {
-                    type: "text",
-                    text: `Error: ${errorMessage}`,
-                },
-            ],
+            content: [{ type: "text", text: `Error: ${errorMessage}` }],
             isError: true,
         };
     }
 });
-function buildGenerateInput(prompt, language, context) {
-    let input = "";
-    if (language) {
-        input += `Language: ${language}\n\n`;
-    }
-    if (context) {
-        input += `Context:\n${context}\n\n`;
-    }
-    input += `Task: ${prompt}\n\nGenerate the code:`;
-    return input;
-}
-function buildEditInput(code, instruction, language) {
-    let input = "";
-    if (language) {
-        input += `Language: ${language}\n\n`;
-    }
-    input += `Original code:\n\`\`\`\n${code}\n\`\`\`\n\n`;
-    input += `Instruction: ${instruction}\n\n`;
-    input += `Modified code:`;
-    return input;
-}
-function buildExplainInput(code, language, focus) {
-    let input = "";
-    if (language) {
-        input += `Language: ${language}\n\n`;
-    }
-    input += `Code:\n\`\`\`\n${code}\n\`\`\`\n\n`;
-    if (focus) {
-        input += `Focus on: ${focus}\n\n`;
-    }
-    input += `Explain this code:`;
-    return input;
-}
-function buildFixInput(code, error, language) {
-    let input = "";
-    if (language) {
-        input += `Language: ${language}\n\n`;
-    }
-    input += `Code with error:\n\`\`\`\n${code}\n\`\`\`\n\n`;
-    input += `Error message:\n${error}\n\n`;
-    input += `Fixed code:`;
-    return input;
-}
-function buildRefactorInput(code, goal, language) {
-    let input = "";
-    if (language) {
-        input += `Language: ${language}\n\n`;
-    }
-    input += `Original code:\n\`\`\`\n${code}\n\`\`\`\n\n`;
-    input += `Refactoring goal: ${goal}\n\n`;
-    input += `Refactored code:`;
-    return input;
-}
+// --- 启动 ---
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error("Codex MCP Server running on stdio");
+    console.error("Codex MCP Server v2.0.0 running on stdio");
 }
 main().catch((error) => {
     console.error("Fatal error:", error);

package/dist/tools.d.ts

@@ -2,7 +2,7 @@ export declare const tools: ({
     name: string;
     description: string;
     inputSchema: {
-        type: string;
+        type: "object";
         properties: {
             prompt: {
                 type: string;
@@ -12,41 +12,21 @@ export declare const tools: ({
                 type: string;
                 description: string;
             };
-            context: {
+            project_context: {
                 type: string;
                 description: string;
             };
-            code?: undefined;
-            instruction?: undefined;
-            focus?: undefined;
-            error?: undefined;
-            goal?: undefined;
-        };
-        required: string[];
-    };
-} | {
-    name: string;
-    description: string;
-    inputSchema: {
-        type: string;
-        properties: {
-            code: {
+            files: {
                 type: string;
                 description: string;
             };
-            instruction: {
-                type: string;
-                description: string;
-            };
-            language: {
+            conversation_context: {
                 type: string;
                 description: string;
             };
-            prompt?: undefined;
-            context?: undefined;
+            code?: undefined;
             focus?: undefined;
-            error?: undefined;
-            goal?: undefined;
+            framework?: undefined;
         };
         required: string[];
     };
@@ -54,7 +34,7 @@ export declare const tools: ({
     name: string;
     description: string;
     inputSchema: {
-        type: string;
+        type: "object";
         properties: {
             code: {
                 type: string;
@@ -65,14 +45,21 @@ export declare const tools: ({
                 description: string;
             };
             focus: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            project_context: {
+                type: string;
+                description: string;
+            };
+            conversation_context: {
                 type: string;
                 description: string;
             };
             prompt?: undefined;
-            context?: undefined;
-            instruction?: undefined;
-            error?: undefined;
-            goal?: undefined;
+            files?: undefined;
+            framework?: undefined;
         };
         required: string[];
     };
@@ -80,51 +67,31 @@ export declare const tools: ({
     name: string;
     description: string;
     inputSchema: {
-        type: string;
+        type: "object";
         properties: {
             code: {
                 type: string;
                 description: string;
             };
-            error: {
-                type: string;
-                description: string;
-            };
             language: {
                 type: string;
                 description: string;
             };
-            prompt?: undefined;
-            context?: undefined;
-            instruction?: undefined;
-            focus?: undefined;
-            goal?: undefined;
-        };
-        required: string[];
-    };
-} | {
-    name: string;
-    description: string;
-    inputSchema: {
-        type: string;
-        properties: {
-            code: {
+            framework: {
                 type: string;
                 description: string;
             };
-            goal: {
+            project_context: {
                 type: string;
                 description: string;
             };
-            language: {
+            conversation_context: {
                 type: string;
                 description: string;
             };
             prompt?: undefined;
-            context?: undefined;
-            instruction?: undefined;
+            files?: undefined;
             focus?: undefined;
-            error?: undefined;
         };
         required: string[];
     };

package/dist/tools.js

@@ -1,112 +1,130 @@
 export const tools = [
     {
         name: "codex_generate",
-        description: "Generate code based on a natural language prompt. Use this for creating new code from scratch, implementing features, or writing functions.",
+        description: [
+            "Generate code using Codex deep reasoning. Use for complex tasks where a second expert perspective adds value.",
+            "",
+            "Returns structured JSON: { code, language, explanation, dependencies }",
+            "",
+            "When to use:",
+            "- Complex algorithms, data structures, state machines",
+            "- Performance-critical code requiring deep optimization",
+            "- System design implementations (interpreters, compilers, protocols)",
+            "- When you want a different model's approach to a hard problem",
+            "",
+            "Do NOT use for simple code generation — handle that natively.",
+        ].join("\n"),
         inputSchema: {
             type: "object",
             properties: {
                 prompt: {
                     type: "string",
-                    description: "Natural language description of what code to generate",
+                    description: "What to generate. Be specific: requirements, constraints, expected behavior.",
                 },
                 language: {
                     type: "string",
-                    description: "Programming language (e.g., typescript, python, rust)",
+                    description: "Target language (e.g., typescript, python, rust, go).",
                 },
-                context: {
+                project_context: {
                     type: "string",
-                    description: "Additional context like existing code, dependencies, or requirements",
+                    description: "Project info: tech stack, conventions, architecture. Pass CLAUDE.md or relevant standards.",
                 },
-            },
-            required: ["prompt"],
-        },
-    },
-    {
-        name: "codex_edit",
-        description: "Edit existing code based on instructions. Use this for modifying, updating, or improving existing code.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                code: {
-                    type: "string",
-                    description: "The existing code to edit",
-                },
-                instruction: {
+                files: {
                     type: "string",
-                    description: "What changes to make to the code",
+                    description: "Related source files. Include types, interfaces, imports the generated code should reference.",
                 },
-                language: {
+                conversation_context: {
                     type: "string",
-                    description: "Programming language of the code",
+                    description: "Recent conversation summary: what was discussed, decided, or attempted.",
                 },
             },
-            required: ["code", "instruction"],
+            required: ["prompt"],
         },
     },
     {
-        name: "codex_explain",
-        description: "Explain how code works. Use this for understanding complex code, algorithms, or logic.",
+        name: "codex_review",
+        description: [
+            "Independent code review from a second AI. Analyzes security, performance, and best practices that the primary AI might miss.",
+            "",
+            "Returns structured JSON: { findings: [{ severity, category, location, issue, suggestion }], summary, score }",
+            "",
+            "When to use:",
+            "- Before committing security-sensitive code (auth, crypto, input validation)",
+            "- Performance-critical paths that need independent analysis",
+            "- When you want a second opinion on code quality",
+            "- PR review where an independent perspective matters",
+            "",
+            "Severity levels: critical, high, medium, low, info",
+            "Score range: 0-100 (90+ excellent, 70-89 good, 50-69 needs work, <50 concerning)",
+        ].join("\n"),
         inputSchema: {
             type: "object",
             properties: {
                 code: {
                     type: "string",
-                    description: "The code to explain",
+                    description: "Code to review.",
                 },
                 language: {
                     type: "string",
-                    description: "Programming language of the code",
+                    description: "Programming language of the code.",
                 },
                 focus: {
                     type: "string",
-                    description: "Specific aspect to focus on (e.g., 'performance', 'security', 'algorithm')",
+                    enum: ["security", "performance", "best-practices", "all"],
+                    description: "Review focus area. Default: all.",
+                },
+                project_context: {
+                    type: "string",
+                    description: "Project conventions, lint rules, architectural guidelines.",
+                },
+                conversation_context: {
+                    type: "string",
+                    description: "Why this review is needed: what changed, what concerns exist.",
                 },
             },
             required: ["code"],
         },
     },
     {
-        name: "codex_fix",
-        description: "Fix buggy code based on error messages. Use this for debugging and fixing runtime or compilation errors.",
+        name: "codex_test",
+        description: [
+            "Generate comprehensive test suites with deep reasoning for edge case coverage.",
+            "",
+            "Returns structured JSON: { test_code, language, framework, test_cases: [{ name, description, type }], coverage_notes }",
+            "",
+            "When to use:",
+            "- Complex business logic needing thorough edge case coverage",
+            "- Functions with many branches, error paths, or boundary conditions",
+            "- When test quality directly impacts reliability",
+            "- Integration tests requiring careful mock setup",
+            "",
+            "Test case types: unit, integration, edge-case, error-handling",
+        ].join("\n"),
         inputSchema: {
             type: "object",
             properties: {
                 code: {
                     type: "string",
-                    description: "The code with the bug",
-                },
-                error: {
-                    type: "string",
-                    description: "The error message or description of the bug",
+                    description: "Code to generate tests for.",
                 },
                 language: {
                     type: "string",
-                    description: "Programming language of the code",
+                    description: "Programming language (e.g., typescript, python).",
                 },
-            },
-            required: ["code", "error"],
-        },
-    },
-    {
-        name: "codex_refactor",
-        description: "Refactor code to improve quality, readability, or performance. Use this for code cleanup and optimization.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                code: {
+                framework: {
                     type: "string",
-                    description: "The code to refactor",
+                    description: "Test framework (e.g., jest, vitest, pytest, go test).",
                 },
-                goal: {
+                project_context: {
                     type: "string",
-                    description: "Refactoring goal (e.g., 'improve readability', 'optimize performance', 'reduce complexity')",
+                    description: "Project test conventions: existing patterns, mock strategies, test directory structure.",
                 },
-                language: {
+                conversation_context: {
                     type: "string",
-                    description: "Programming language of the code",
+                    description: "Context about the code: known issues, requirements, what needs coverage.",
                 },
             },
-            required: ["code", "goal"],
+            required: ["code"],
         },
     },
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cpujia/codex-mcp-server",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "MCP Server for OpenAI Codex /v1/responses API integration with Claude Code",
   "type": "module",
   "main": "dist/index.js",