Claude Code MCP Enhanced

Instructions

Implementation Reference

• src/server.ts:395-793 (handler)

  Primary MCP tool call handler implementing dispatch for 'claude_code' (main tool), 'health', and 'convert_task_markdown'. The 'claude_code' logic (lines 576-792) validates inputs, prepares prompts with boomerang/task orchestration, applies Roo modes if enabled, executes Claude CLI via spawnAsync with retries and heartbeats, processes output, and handles errors/timeouts.
  this.server.setRequestHandler(CallToolRequestSchema, async (args, call): Promise<ServerResult> => { // Generate a unique request ID const requestId = `req_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`; this.activeRequests.add(requestId); debugLog(`[Debug] Handling CallToolRequest: ${requestId}`, args); // Correctly access toolName from args.params.name (may include namespace) const fullToolName = args.params.name; // Extract the local tool name (remove namespace if present) const toolName = fullToolName.includes(':') ? fullToolName.split(':')[1] : fullToolName; debugLog(`[Debug] Tool request: ${fullToolName}, Local tool name: ${toolName}`); // Handle health check tool if (toolName === 'health') { // Check if Claude CLI is accessible let claudeCliStatus = 'unknown'; try { const { stdout } = await spawnAsync('/bin/bash', [this.claudeCliPath, '--version'], { timeout: 5000 }); claudeCliStatus = 'available'; } catch (error) { claudeCliStatus = 'unavailable'; } // Collect and return system information const healthInfo = { status: 'ok', version: this.packageVersion, claudeCli: { path: this.claudeCliPath, status: claudeCliStatus }, config: { debugMode, heartbeatIntervalMs, executionTimeoutMs, useRooModes, maxRetries, retryDelayMs }, system: { platform: os.platform(), release: os.release(), arch: os.arch(), cpus: os.cpus().length, memory: { total: Math.round(os.totalmem() / (1024 * 1024)) + 'MB', free: Math.round(os.freemem() / (1024 * 1024)) + 'MB' }, uptime: Math.round(os.uptime() / 60) + ' minutes' }, timestamp: new Date().toISOString() }; // Health check request completed, remove from tracking this.activeRequests.delete(requestId); debugLog(`[Debug] Health check request ${requestId} completed`); return { content: [{ type: 'text', text: JSON.stringify(healthInfo, null, 2) }] }; } // Handle convert_task_markdown tool if (toolName === 'convert_task_markdown') { const toolArguments = args.params.arguments; // Extract markdownPath (required) let markdownPath: string; if ( toolArguments && typeof toolArguments === 'object' && 'markdownPath' in toolArguments && typeof toolArguments.markdownPath === 'string' ) { markdownPath = toolArguments.markdownPath; } else { throw new McpError(ErrorCode.InvalidParams, 'Missing or invalid required parameter: markdownPath for convert_task_markdown tool'); } // Extract outputPath (optional) let outputPath: string | undefined; if (toolArguments.outputPath && typeof toolArguments.outputPath === 'string') { outputPath = toolArguments.outputPath; } debugLog(`[Debug] Converting markdown task file: ${markdownPath}`); let stderr = ''; try { // Prepare command to run task_converter.py const pythonPath = 'python3'; const converterPath = pathResolve(__dirname, '../docs/task_converter.py'); // Use --json-output flag to get JSON to stdout const args = ['--json-output', markdownPath]; const result = await spawnAsync(pythonPath, [converterPath, ...args], { cwd: homedir(), timeout: 30000 // 30 seconds timeout }); const stdout = result.stdout; stderr = result.stderr; // Extract progress messages and actual errors const stderrLines = stderr.split('\n'); const progressMessages = stderrLines.filter(line => line.includes('[Progress]')); const errorMessages = stderrLines.filter(line => !line.includes('[Progress]') && line.trim()); // Log progress messages progressMessages.forEach(msg => { console.error(msg); // Send to client debugLog(msg); }); if (errorMessages.length > 0) { stderr = errorMessages.join('\n'); debugLog(`[Debug] Task converter stderr: ${stderr}`); } // Check if there was an error from the converter if (stderr && stderr.includes('Markdown format validation failed')) { // Return validation error as a structured response const validationError = { status: 'error', error: 'Markdown format validation failed', details: stderr, helpUrl: 'https://github.com/grahama1970/claude-code-mcp/blob/main/README.md#markdown-task-file-format' }; this.activeRequests.delete(requestId); return { content: [{ type: 'text', text: JSON.stringify(validationError, null, 2) }] }; } // Parse the JSON output const tasks = JSON.parse(stdout); // If outputPath is provided, also save to file if (outputPath) { await fs.writeFile(outputPath, JSON.stringify(tasks, null, 2)); debugLog(`[Debug] Saved converted tasks to: ${outputPath}`); } // Return the converted tasks const response = { status: 'success', tasksCount: tasks.length, outputPath: outputPath || 'none', tasks: tasks }; this.activeRequests.delete(requestId); return { content: [{ type: 'text', text: JSON.stringify(response, null, 2) }] }; } catch (error) { this.activeRequests.delete(requestId); const errorMessage = error instanceof Error ? error.message : String(error); // Check if this is a JSON parsing error (indicating validation failure) if (errorMessage.includes('JSON') && stderr) { const validationError = { status: 'error', error: 'Task conversion failed', details: stderr || errorMessage, helpUrl: 'https://github.com/grahama1970/claude-code-mcp/blob/main/README.md#markdown-task-file-format' }; return { content: [{ type: 'text', text: JSON.stringify(validationError, null, 2) }] }; } throw new McpError(ErrorCode.InternalError, `Failed to convert markdown tasks: ${errorMessage}`); } } // Handle tools - we support 'health', 'claude_code', and 'convert_task_markdown' if (toolName !== 'claude_code' && toolName !== 'health' && toolName !== 'convert_task_markdown') { // ErrorCode.ToolNotFound should be ErrorCode.MethodNotFound as per SDK for tools throw new McpError(ErrorCode.MethodNotFound, `Tool ${toolName} not found`); } // Robustly access arguments from args.params.arguments const toolArguments = args.params.arguments; let prompt: string; let parentTaskId: string | undefined; let returnMode: 'summary' | 'full' = 'full'; let taskDescription: string | undefined; let mode: string | undefined; // Validate and extract prompt (required) if ( toolArguments && typeof toolArguments === 'object' && 'prompt' in toolArguments && typeof toolArguments.prompt === 'string' ) { prompt = toolArguments.prompt; } else { throw new McpError(ErrorCode.InvalidParams, 'Missing or invalid required parameter: prompt (must be an object with a string "prompt" property) for claude_code tool'); } // Extract optional parameters for task orchestration if (toolArguments.parentTaskId && typeof toolArguments.parentTaskId === 'string') { parentTaskId = toolArguments.parentTaskId; debugLog(`[Debug] Task has parent ID: ${parentTaskId}`); } if (toolArguments.returnMode && (toolArguments.returnMode === 'summary' || toolArguments.returnMode === 'full')) { returnMode = toolArguments.returnMode; debugLog(`[Debug] Task return mode: ${returnMode}`); } if (toolArguments.taskDescription && typeof toolArguments.taskDescription === 'string') { taskDescription = toolArguments.taskDescription; debugLog(`[Debug] Task description: ${taskDescription}`); } // Check for Roo mode if (useRooModes && toolArguments.mode && typeof toolArguments.mode === 'string') { mode = toolArguments.mode; debugLog(`[Debug] Using Roo mode: ${mode}`); } // Determine the working directory let effectiveCwd = homedir(); // Default CWD is user's home directory // Check if workFolder is provided in the tool arguments if (toolArguments.workFolder && typeof toolArguments.workFolder === 'string') { const resolvedCwd = pathResolve(toolArguments.workFolder); debugLog(`[Debug] Specified workFolder: ${toolArguments.workFolder}, Resolved to: ${resolvedCwd}`); // Check if the resolved path exists if (existsSync(resolvedCwd)) { effectiveCwd = resolvedCwd; debugLog(`[Debug] Using workFolder as CWD: ${effectiveCwd}`); } else { debugLog(`[Warning] Specified workFolder does not exist: ${resolvedCwd}. Using default: ${effectiveCwd}`); } } else { debugLog(`[Debug] No workFolder provided, using default CWD: ${effectiveCwd}`); } // For tasks with a parent, add boomerang context to the prompt if (parentTaskId) { // Prepend task context to prompt const taskContext = ` # Boomerang Task ${taskDescription ? `## Task Description\n${taskDescription}\n\n` : ''} ## Parent Task ID ${parentTaskId} ## Return Instructions You are part of a larger workflow. After completing your task, you should ${returnMode === 'summary' ? 'provide a BRIEF SUMMARY of the results' : 'return your FULL RESULTS'}. ${returnMode === 'summary' ? 'IMPORTANT: Keep your response concise and focused on key findings/changes only!' : ''} --- `; prompt = taskContext + prompt; debugLog(`[Debug] Prepended boomerang task context to prompt`); } try { debugLog(`[Debug] Attempting to execute Claude CLI with prompt: "${prompt}" in CWD: "${effectiveCwd}"`); let claudeProcessArgs = [this.claudeCliPath, '--dangerously-skip-permissions']; // Handle Roo mode selection if enabled and specified if (useRooModes && mode) { // Load room modes configuration const roomodes = loadRooModes(); if (roomodes && roomodes.customModes) { // Find the matching mode const selectedMode = roomodes.customModes.find((m: any) => m.slug === mode); if (selectedMode) { debugLog(`[Debug] Found Roo mode configuration for: ${mode}`); // Add the mode parameter to the Claude CLI command claudeProcessArgs.push('--role', selectedMode.roleDefinition); // If the mode has a specific model, use it if (selectedMode.apiConfiguration && selectedMode.apiConfiguration.modelId) { claudeProcessArgs.push('--model', selectedMode.apiConfiguration.modelId); } } else { debugLog(`[Warning] Specified Roo mode not found: ${mode}`); } } else { debugLog(`[Warning] Roo modes configuration not found or invalid`); } } // Add the prompt claudeProcessArgs.push('-p', prompt); debugLog(`[Debug] Invoking /bin/bash with args: ${claudeProcessArgs.join(' ')}`); // Use retry for robust execution const { stdout, stderr } = await retry( async (bail: (err: Error) => void, attemptNumber: number) => { try { if (attemptNumber > 1) { debugLog(`[Retry] Attempt ${attemptNumber}/${maxRetries + 1} for Claude CLI execution`); } return await spawnAsync( '/bin/bash', // Explicitly use /bin/bash as the command claudeProcessArgs, // Pass the script path as the first argument to bash { timeout: executionTimeoutMs, cwd: effectiveCwd } ); } catch (err: any) { // Log the error debugLog(`[Retry] Error during attempt ${attemptNumber}/${maxRetries + 1}: ${err.message}`); // Determine if we should retry based on the error const isNetworkError = err.message.includes('ECONNRESET') || err.message.includes('ETIMEDOUT') || err.message.includes('ECONNREFUSED'); const isTransientError = isNetworkError || err.message.includes('429') || // Rate limit err.message.includes('500'); // Server error // If it's not a transient error, bail immediately if (!isTransientError) { debugLog(`[Retry] Non-retryable error: ${err.message}. Bailing out.`); bail(err); return { stdout: '', stderr: '' }; // This never happens due to bail } // Otherwise, throw to trigger retry throw err; } }, { retries: maxRetries, minTimeout: retryDelayMs, onRetry: (err: Error, attempt: number) => { console.error(`[Progress] Retry attempt ${attempt}/${maxRetries} due to: ${err.message}`); } } ); debugLog('[Debug] Claude CLI stdout:', stdout.trim()); if (stderr) { debugLog('[Debug] Claude CLI stderr:', stderr.trim()); } // Process the output let processedOutput = stdout; // For tasks with a parent, add a boomerang marker to help identify responses if (parentTaskId) { // Add a boomerang marker with task info const boomerangInfo = { parentTaskId, returnMode, taskDescription: taskDescription || 'Unknown task', completed: new Date().toISOString() }; // Add a hidden JSON marker that can be detected by the parent task // Format is a special comment that won't interfere with normal content const boomerangMarker = `\n\n<!-- BOOMERANG_RESULT ${JSON.stringify(boomerangInfo)} -->`; processedOutput += boomerangMarker; debugLog(`[Debug] Added boomerang marker to output for parent task: ${parentTaskId}`); } // Request completed successfully, remove from tracking this.activeRequests.delete(requestId); debugLog(`[Debug] Request ${requestId} completed successfully`); // Return processed output return { content: [{ type: 'text', text: processedOutput }] }; } catch (error: any) { debugLog('[Error] Error executing Claude CLI:', error); let errorMessage = error.message || 'Unknown error'; // Attempt to include stderr and stdout from the error object if spawnAsync attached them if (error.stderr) { errorMessage += `\nStderr: ${error.stderr}`; } if (error.stdout) { errorMessage += `\nStdout: ${error.stdout}`; } // Request failed, remove from tracking this.activeRequests.delete(requestId); debugLog(`[Debug] Request ${requestId} failed: ${errorMessage}`); if (error.signal === 'SIGTERM' || (error.message && error.message.includes('ETIMEDOUT')) || (error.code === 'ETIMEDOUT')) { // Reverting to InternalError due to lint issues, but with a specific timeout message. throw new McpError(ErrorCode.InternalError, `Claude CLI command timed out after ${executionTimeoutMs / 1000}s. Details: ${errorMessage}`); } // ErrorCode.ToolCallFailed should be ErrorCode.InternalError or a more specific execution error if available throw new McpError(ErrorCode.InternalError, `Claude CLI execution failed: ${errorMessage}`); } }); }
• src/server.ts:359-389 (schema)

  JSON Schema defining the input parameters for the 'claude_code' tool, including required 'prompt' and optional fields for workFolder, task orchestration (parentTaskId, returnMode, taskDescription), and Roo mode.
  inputSchema: { type: 'object', properties: { prompt: { type: 'string', description: 'The detailed natural language prompt for Claude to execute.', }, workFolder: { type: 'string', description: 'Mandatory when using file operations or referencing any file. The working directory for the Claude CLI execution.', }, parentTaskId: { type: 'string', description: 'Optional ID of the parent task that created this task (for task orchestration/boomerang).', }, returnMode: { type: 'string', enum: ['summary', 'full'], description: 'How results should be returned: summary (concise) or full (detailed). Defaults to full.', }, taskDescription: { type: 'string', description: 'Short description of the task for better organization and tracking in orchestrated workflows.', }, mode: { type: 'string', description: 'When MCP_USE_ROOMODES=true, specifies the mode from .roomodes to use (e.g., "boomerang-mode", "coder", "designer", etc.).', }, }, required: ['prompt'], },
• src/server.ts:317-390 (registration)

  Registration of the 'claude_code' tool in the MCP server's listTools response, specifying name, detailed description, and input schema.
  { name: 'claude_code', description: `Claude Code Agent: Your versatile multi-modal assistant for code, file, Git, and terminal operations via Claude CLI. Use \`workFolder\` for contextual execution. • File ops: Create, read, (fuzzy) edit, move, copy, delete, list files, analyze/ocr images, file content analysis └─ e.g., "Create /tmp/log.txt with 'system boot'", "Edit main.py to replace 'debug_mode = True' with 'debug_mode = False'", "List files in /src", "Move a specific section somewhere else" • Code: Generate / analyse / refactor / fix └─ e.g. "Generate Python to parse CSV→JSON", "Find bugs in my_script.py" • Git: Stage ▸ commit ▸ push ▸ tag (any workflow) └─ "Commit '/workspace/src/main.java' with 'feat: user auth' to develop." • Terminal: Run any CLI cmd or open URLs └─ "npm run build", "Open https://developer.mozilla.org" • Web search + summarise content on-the-fly • Multi-step workflows (Version bumps, changelog updates, release tagging, etc.) • GitHub integration Create PRs, check CI status • Confused or stuck on an issue? Ask Claude Code for a second opinion, it might surprise you! • Task Orchestration with "Boomerang" pattern └─ Break down complex tasks into subtasks for Claude Code to execute separately └─ Pass parent task ID and get results back for complex workflows └─ Specify return mode (summary or full) for tailored responses **Prompt tips** 1. Be concise, explicit & step-by-step for complex tasks. No need for niceties, this is a tool to get things done. 2. For multi-line text, write it to a temporary file in the project root, use that file, then delete it. 3. If you get a timeout, split the task into smaller steps. 4. **Seeking a second opinion/analysis**: If you're stuck or want advice, you can ask \`claude_code\` to analyze a problem and suggest solutions. Clearly state in your prompt that you are looking for analysis only and no actual file modifications should be made. 5. If workFolder is set to the project path, there is no need to repeat that path in the prompt and you can use relative paths for files. 6. Claude Code is really good at complex multi-step file operations and refactorings and faster than your native edit features. 7. Combine file operations, README updates, and Git commands in a sequence. 8. **Task Orchestration**: For complex workflows, use \`parentTaskId\` to create subtasks and \`returnMode: "summary"\` to get concise results back. 9. Claude can do much more, just ask it! `, inputSchema: { type: 'object', properties: { prompt: { type: 'string', description: 'The detailed natural language prompt for Claude to execute.', }, workFolder: { type: 'string', description: 'Mandatory when using file operations or referencing any file. The working directory for the Claude CLI execution.', }, parentTaskId: { type: 'string', description: 'Optional ID of the parent task that created this task (for task orchestration/boomerang).', }, returnMode: { type: 'string', enum: ['summary', 'full'], description: 'How results should be returned: summary (concise) or full (detailed). Defaults to full.', }, taskDescription: { type: 'string', description: 'Short description of the task for better organization and tracking in orchestrated workflows.', }, mode: { type: 'string', description: 'When MCP_USE_ROOMODES=true, specifies the mode from .roomodes to use (e.g., "boomerang-mode", "coder", "designer", etc.).', }, }, required: ['prompt'], }, }
• src/server.ts:153-213 (helper)

  Core helper function for asynchronous command execution used by claude_code handler. Includes progress heartbeats to prevent MCP client timeouts, configurable timeout, CWD support, and full stdout/stderr capture.
  async function spawnAsync(command: string, args: string[], options?: { timeout?: number, cwd?: string }): Promise<{ stdout: string; stderr: string }> { return new Promise((resolve, reject) => { debugLog(`[Spawn] Running command: ${command} ${args.join(' ')}`); const process = spawn(command, args, { shell: false, // Reverted to false timeout: options?.timeout, cwd: options?.cwd, stdio: ['ignore', 'pipe', 'pipe'] }); let stdout = ''; let stderr = ''; let executionStartTime = Date.now(); let heartbeatCounter = 0; // Set up progress reporter to prevent client timeouts // Send a heartbeat message at the configured interval const progressReporter = setInterval(() => { heartbeatCounter++; const elapsedSeconds = Math.floor((Date.now() - executionStartTime) / 1000); const heartbeatMessage = `[Progress] Claude Code execution in progress: ${elapsedSeconds}s elapsed (heartbeat #${heartbeatCounter})`; // Log heartbeat to stderr which will be seen by the client console.error(heartbeatMessage); debugLog(heartbeatMessage); }, heartbeatIntervalMs); process.stdout.on('data', (data) => { stdout += data.toString(); }); process.stderr.on('data', (data) => { stderr += data.toString(); debugLog(`[Spawn Stderr Chunk] ${data.toString()}`); }); process.on('error', (error: NodeJS.ErrnoException) => { clearInterval(progressReporter); // Clean up the interval debugLog(`[Spawn Error Event] Full error object:`, error); let errorMessage = `Spawn error: ${error.message}`; if (error.path) { errorMessage += ` | Path: ${error.path}`; } if (error.syscall) { errorMessage += ` | Syscall: ${error.syscall}`; } errorMessage += `\nStderr: ${stderr.trim()}`; reject(new Error(errorMessage)); }); process.on('close', (code) => { clearInterval(progressReporter); // Clean up the interval const executionTimeMs = Date.now() - executionStartTime; debugLog(`[Spawn Close] Exit code: ${code}, Execution time: ${executionTimeMs}ms`); debugLog(`[Spawn Stderr Full] ${stderr.trim()}`); debugLog(`[Spawn Stdout Full] ${stdout.trim()}`); if (code === 0) { resolve({ stdout, stderr }); } else { reject(new Error(`Command failed with exit code ${code}\nStderr: ${stderr.trim()}\nStdout: ${stdout.trim()}`)); } }); }); }
• src/server.ts:65-72 (schema)

  TypeScript interface mirroring the claude_code tool arguments for internal type safety.
  interface ClaudeCodeArgs { prompt: string; workFolder?: string; parentTaskId?: string; returnMode?: 'summary' | 'full'; taskDescription?: string; mode?: string; // Roo mode to use (matches slug in .roomodes) }