MCP-REPL

Instructions

Implementation Reference

• src/core/mcp-tools.js:1-5 (registration)

  Registers the 'execute' tool by importing executionTools from executor-tool.js and spreading it into the allTools array used by the MCP server.
  import { executionTools } from '../tools/executor-tool.js'; export const allTools = [ ...executionTools ];
• src/index.js:28-33 (registration)

  Sets up the MCP server request handlers for listing tools (exposes 'execute') and calling tools by name.
  const tools = allTools; server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: tools };
• src/tools/executor-tool.js:670-696 (schema)

  Input schema defining parameters for the 'execute' tool: workingDirectory (required), code, commands, runtime, timeout.
  inputSchema: { type: "object", properties: { workingDirectory: { type: "string", description: "Path to working directory for execution." }, code: { type: "string", description: "Code to execute. Include timeouts for network/async operations to prevent hangs." }, commands: { type: ["string", "array"], description: "Bash commands (single or array for planned batch executions)" }, runtime: { type: "string", enum: ["nodejs", "deno", "bash", "go", "rust", "python", "c", "cpp", "auto"], description: "Execution runtime (default: auto-detect)" }, timeout: { type: "number", description: "Timeout in milliseconds (default: 240000)" } }, required: ["workingDirectory"] },
• src/tools/executor-tool.js:697-852 (handler)

  Main execution handler for the 'execute' tool. Validates inputs, suppresses console, executes code/commands via runtime-specific functions like executeWithRuntimeValidation, enhances results with error analysis, generates insights, and updates contexts.
  handler: withCrossToolAwareness(withConnectionManagement(async ({ code, commands, workingDirectory, runtime = "auto", timeout = 240000 }) => { const consoleRestore = suppressConsoleOutput(); const effectiveWorkingDirectory = workingDirectory; const query = code || commands || ''; try { // Validate required parameters if (!workingDirectory) { throw new ToolError( 'Working directory is required', 'MISSING_PARAMETER', 'execute', false, ['Provide absolute path to working directory', 'Check tool documentation'] ); } // Start execution tracking for all operations const execution = executionState.startExecution({ type: 'execute', code, commands, runtime, workingDirectory: effectiveWorkingDirectory, timeout }); let result; if (code) { let targetRuntime = runtime === "auto" ? "nodejs" : runtime; if (runtime === "auto") { const shellCommands = ['npm ', 'npx ', 'yarn ', 'pip ', 'python ', 'go ', 'rustc ', 'gcc ', 'g++ ', 'git ', 'mkdir ', 'rm ', 'ls ', 'cd ']; const isShellCommand = shellCommands.some(cmd => code.trim().startsWith(cmd)); if (isShellCommand) { targetRuntime = 'bash'; } } try { const executionStart = Date.now(); result = await executeWithRuntimeValidation(code, targetRuntime, { workingDirectory, timeout }); const executionDuration = Date.now() - executionStart; // Complete execution (duration-based logic for cross-tool sharing) executionState.completeExecution(execution.id, result); } catch (executionError) { if (targetRuntime === 'bash') { try { result = await executeWithRuntimeValidation(code, 'nodejs', { workingDirectory, timeout }); } catch (fallbackError) { result = { success: false, stdout: '', stderr: `Failed to execute as both bash and nodejs:\nBash error: ${executionError.message}\nNode.js error: ${fallbackError.message}`, executionTimeMs: 0 }; } } else { result = { success: false, stdout: '', stderr: `Execution failed: ${executionError.message}`, executionTimeMs: 0 }; } executionState.failExecution(execution.id, executionError); } result = enhanceExecutionResult(result, code, targetRuntime, workingDirectory); } else if (commands) { try { const executionStart = Date.now(); result = await executeWithRuntimeValidation(commands, 'bash', { workingDirectory, timeout }); const executionDuration = Date.now() - executionStart; // Complete execution executionState.completeExecution(execution.id, result); } catch (executionError) { result = { success: false, stdout: '', stderr: `Command execution failed: ${executionError.message}`, executionTimeMs: 0 }; executionState.failExecution(execution.id, executionError); } result = enhanceExecutionResult(result, commands, 'bash', workingDirectory); } else { result = { content: [{ type: "text", text: "No code or commands provided" }] }; } const insights = generateExecutionInsights(result, query, effectiveWorkingDirectory); // Format response with enhanced error information let responseContent = result; if (result._errorAnalysis && result._errorAnalysis.isSyntaxError) { // Simple error response responseContent = { ...result, content: [{ type: "text", text: result.error || result.stderr || 'Execution failed' }] }; } else if (!result.success) { // Simple error format responseContent = { ...result, content: [{ type: "text", text: result.error || result.stderr || 'Execution failed' }] }; } else if (!result.content) { // Format successful execution or basic error let outputText = ''; if (result.success) { outputText = result.stdout || 'Execution successful'; } else { outputText = result.error || result.stderr || 'Execution failed'; } responseContent = { ...result, content: [{ type: "text", text: outputText }] }; } const toolContext = createToolContext('execute', effectiveWorkingDirectory, query, { ...responseContent, duration: responseContent.executionTimeMs || 0, filesAccessed: responseContent.filesAccessed || [], patterns: responseContent.patterns || [], insights: insights }); await workingDirectoryContext.updateContext(effectiveWorkingDirectory, 'execute', toolContext); // Clean up old executions executionState.cleanup(); return responseContent; } catch (error) { const errorContext = createToolContext('execute', effectiveWorkingDirectory, query, { error: error.message, duration: 0 }); await workingDirectoryContext.updateContext(effectiveWorkingDirectory, 'execute', errorContext); return { content: [{ type: "text", text: `Execution error: ${error.message}` }], isError: true }; } finally { consoleRestore.restore(); } }, 'execute', {
• src/tools/executor-tool.js:253-325 (helper)

  Core helper function executeProcess that spawns child processes, handles timeouts, captures output, and manages errors for all executions.
  export async function executeProcess(command, args = [], options = {}) { const startTime = Date.now(); const { timeout = 240000, cwd, input, encoding = 'utf8' } = options; return new Promise((resolve) => { const child = spawn(command, args, { cwd, stdio: input ? 'pipe' : ['pipe', 'pipe', 'pipe'] }); let stdout = ''; let stderr = ''; let isResolved = false; const timeoutId = setTimeout(() => { if (!isResolved) { child.kill('SIGTERM'); isResolved = true; resolve(createTimeoutError(`${command} ${args.join(' ')}`, timeout, startTime)); } }, timeout); if (child.stdout) { child.stdout.on('data', (data) => { if (data && typeof data === 'object' && Buffer.isBuffer(data)) { stdout += data.toString(encoding); } else if (data && typeof data === 'string') { stdout += data; } }); } if (child.stderr) { child.stderr.on('data', (data) => { if (data && typeof data === 'object' && Buffer.isBuffer(data)) { stderr += data.toString(encoding); } else if (data && typeof data === 'string') { stderr += data; } }); } child.on('close', (code, signal) => { if (!isResolved) { clearTimeout(timeoutId); isResolved = true; if (code === 0) { resolve(createSuccessResponse({ stdout, stderr, code, signal }, startTime)); } else { resolve(createExecutionErrorResponse( stderr || `Process exited with code ${code}`, startTime, { stdout, stderr, code, signal } )); } } }); child.on('error', (error) => { if (!isResolved) { clearTimeout(timeoutId); isResolved = true; resolve(handleProcessError(error, `${command} ${args.join(' ')}`, startTime)); } }); if (input && child.stdin) { child.stdin.write(input); child.stdin.end(); } }); }