Codex MCP Server

Instructions

Implementation Reference

• src/tools/batch-codex.tool.ts:45-176 (handler)

  The core handler function that parses arguments, sorts tasks by priority, executes each atomic task using executeCodex (sequentially, parallel TODO), handles errors based on stopOnError flag, provides progress updates, collects results, and returns a formatted summary report with success/failure stats.
  execute: async (args, onProgress) => { const { tasks, model, sandbox, parallel, stopOnError, timeout, workingDir, search, oss, enableFeatures, disableFeatures, } = args; const taskList = tasks as Array<{ task: string; target?: string; priority: string; }>; if (!taskList || taskList.length === 0) { throw new Error('No tasks provided for batch execution'); } const results: Array<{ task: string; status: 'success' | 'failed' | 'skipped'; output?: string; error?: string; }> = []; let failedCount = 0; let successCount = 0; // Sort tasks by priority const sortedTasks = [...taskList].sort((a, b) => { const priorityOrder = { high: 0, normal: 1, low: 2 }; return ( priorityOrder[a.priority as keyof typeof priorityOrder] - priorityOrder[b.priority as keyof typeof priorityOrder] ); }); if (onProgress) { onProgress(`🚀 Starting batch execution of ${sortedTasks.length} tasks...`); } // Execute tasks sequentially // TODO: Implement parallel execution when parallel flag is true for (let i = 0; i < sortedTasks.length; i++) { const task = sortedTasks[i]; const taskPrompt = task.target ? `${task.task} in ${task.target}` : task.task; if (onProgress) { onProgress(`\n[${i + 1}/${sortedTasks.length}] Executing: ${taskPrompt}`); } // Skip remaining tasks if stopOnError is true and we have failures if (stopOnError && failedCount > 0) { results.push({ task: taskPrompt, status: 'skipped', error: 'Skipped due to previous failure', }); continue; } try { const result = await executeCodex( taskPrompt, { model: model as string, sandboxMode: sandbox as any, timeout: timeout as number, workingDir: workingDir as string, search: search as boolean, oss: oss as boolean, enableFeatures: enableFeatures as string[], disableFeatures: disableFeatures as string[], }, undefined // No progress for individual tasks to keep output clean ); results.push({ task: taskPrompt, status: 'success', output: result.substring(0, 500), // Truncate for summary }); successCount++; if (onProgress) { onProgress(`✅ Completed: ${task.task}`); } } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); results.push({ task: taskPrompt, status: 'failed', error: errorMessage, }); failedCount++; if (onProgress) { onProgress(`❌ Failed: ${task.task} - ${errorMessage}`); } } } // Generate summary report let report = `\n📊 **Batch Execution Summary**\n`; report += `\n- Total tasks: ${sortedTasks.length}`; report += `\n- Successful: ${successCount} ✅`; report += `\n- Failed: ${failedCount} ❌`; report += `\n- Skipped: ${sortedTasks.length - successCount - failedCount} ⏭️`; report += `\n\n**Task Results:**\n`; for (const result of results) { const icon = result.status === 'success' ? '✅' : result.status === 'failed' ? '❌' : '⏭️'; report += `\n${icon} **${result.task}**`; if (result.status === 'success' && result.output) { report += `\n Output: ${result.output.substring(0, 100)}...`; } else if (result.error) { report += `\n Error: ${result.error}`; } } // If all tasks failed, throw an error if (failedCount === sortedTasks.length) { throw new Error(`All ${failedCount} tasks failed. See report above for details.`); } return report; },
• src/tools/batch-codex.tool.ts:13-34 (schema)

  Zod schema defining the input arguments for the batch-codex tool, including tasks array (each with task, target?, priority), model, sandbox mode, parallel execution flag, etc. Used as zodSchema in the tool definition.
  const batchCodexArgsSchema = z.object({ tasks: z.array(batchTaskSchema).min(1).describe('Array of atomic tasks to delegate to Codex'), model: z .string() .optional() .describe(`Model to use: ${Object.values(MODELS).join(', ')}`), sandbox: z .string() .default(SANDBOX_MODES.WORKSPACE_WRITE) .describe(`Sandbox mode: ${Object.values(SANDBOX_MODES).join(', ')}`), parallel: z.boolean().default(false).describe('Execute tasks in parallel (experimental)'), stopOnError: z.boolean().default(true).describe('Stop execution if any task fails'), timeout: z.number().optional().describe('Maximum execution time per task in milliseconds'), workingDir: z.string().optional().describe('Working directory for execution'), search: z .boolean() .optional() .describe('Enable web search for all tasks (activates web_search_request feature)'), oss: z.boolean().optional().describe('Use local Ollama server'), enableFeatures: z.array(z.string()).optional().describe('Enable feature flags'), disableFeatures: z.array(z.string()).optional().describe('Disable feature flags'), });
• src/tools/index.ts:2-21 (registration)

  Imports the batchCodexTool from batch-codex.tool.ts (noted as .js likely due to build config) and registers it by pushing to the toolRegistry array, making it available for MCP tool protocol.
  import { toolRegistry } from './registry.js'; import { askCodexTool } from './ask-codex.tool.js'; import { batchCodexTool } from './batch-codex.tool.js'; // import { reviewCodexTool } from './review-codex.tool.js'; import { pingTool, helpTool, versionTool } from './simple-tools.js'; import { brainstormTool } from './brainstorm.tool.js'; import { fetchChunkTool } from './fetch-chunk.tool.js'; import { timeoutTestTool } from './timeout-test.tool.js'; toolRegistry.push( askCodexTool, batchCodexTool, // reviewCodexTool, pingTool, helpTool, versionTool, brainstormTool, fetchChunkTool, timeoutTestTool );
• src/tools/batch-codex.tool.ts:7-11 (schema)

  Sub-schema for individual batch tasks, used within the main tasks array schema. Defines task description, optional target, and priority.
  const batchTaskSchema = z.object({ task: z.string().describe('Atomic task description'), target: z.string().optional().describe('Target files/directories (use @ syntax)'), priority: z.enum(['high', 'normal', 'low']).default('normal').describe('Task priority'), });