ai-cli-mcp 2.10.0 → 2.12.0

package/dist/app/cli.js

@@ -0,0 +1,304 @@
+import { runMcpServer } from './mcp.js';
+import { CliProcessService } from '../cli-process-service.js';
+import { getCliDoctorStatus } from '../cli-utils.js';
+import { getModelsPayload } from '../model-catalog.js';
+export const CLI_HELP_TEXT = `Usage: ai-cli <command> [options]
+
+Commands:
+  run       Start an AI CLI process in the background
+  wait      Wait for one or more pids
+  ps        List tracked processes
+  result    Get the current result for a pid
+  kill      Terminate a tracked pid
+  cleanup   Remove completed and failed tracked processes
+  doctor    Check supported AI CLI binaries
+  models    List supported models and aliases
+  mcp       Start the MCP server
+  help      Show this help message
+`;
+export const RUN_HELP_TEXT = `Usage: ai-cli run --cwd <path> [options]
+
+Start an AI CLI process in the background.
+
+Options:
+  --cwd <path>                 Working directory
+  --prompt <text>              Prompt text
+  --prompt-file <path>         Path to a prompt file
+  --model <model>              Model name or alias (e.g. sonnet, claude-ultra, gpt-5.2-codex, codex-ultra, gemini-2.5-pro, gemini-ultra)
+  --session-id <id>            Resume a previous session
+  --reasoning-effort <level>   Reasoning level for Claude/Codex
+  --help, -h                   Show this help message
+
+Compatibility aliases:
+  --workFolder, --work-folder
+  --prompt_file
+  --session_id
+  --reasoning_effort
+`;
+export const WAIT_HELP_TEXT = `Usage: ai-cli wait <pid...> [options]
+
+Wait for one or more tracked processes to finish.
+
+Options:
+  --timeout <seconds>          Maximum wait time in seconds
+  --help, -h                   Show this help message
+`;
+export const RESULT_HELP_TEXT = `Usage: ai-cli result <pid> [options]
+
+Get the current result for a tracked process.
+
+Options:
+  --verbose                    Include verbose parsed output
+  --help, -h                   Show this help message
+`;
+export const KILL_HELP_TEXT = `Usage: ai-cli kill <pid>
+
+Terminate a tracked process.
+
+Options:
+  --help, -h                   Show this help message
+`;
+export const CLEANUP_HELP_TEXT = `Usage: ai-cli cleanup
+
+Remove completed and failed tracked processes.
+
+Options:
+  --help, -h                   Show this help message
+`;
+export const PS_HELP_TEXT = `Usage: ai-cli ps
+
+List tracked processes.
+
+Options:
+  --help, -h                   Show this help message
+`;
+export const MODELS_HELP_TEXT = `Usage: ai-cli models
+
+List supported models and aliases.
+
+Options:
+  --help, -h                   Show this help message
+`;
+export const DOCTOR_HELP_TEXT = `Usage: ai-cli doctor
+
+Check whether supported AI CLI binaries are available.
+
+Options:
+  --help, -h                   Show this help message
+`;
+export const MCP_HELP_TEXT = `Usage: ai-cli mcp
+
+Start the MCP server.
+`;
+let cliProcessService = null;
+function getCliProcessService() {
+    if (!cliProcessService) {
+        cliProcessService = new CliProcessService();
+    }
+    return cliProcessService;
+}
+const defaultDeps = {
+    stdout: (text) => process.stdout.write(text),
+    stderr: (text) => process.stderr.write(text),
+    startMcpServer: () => runMcpServer(),
+    runProcess: (options) => getCliProcessService().startProcess(options),
+    listProcesses: () => getCliProcessService().listProcesses(),
+    getProcessResult: (pid, verbose) => getCliProcessService().getProcessResult(pid, verbose),
+    waitForProcesses: (pids, timeoutSeconds) => getCliProcessService().waitForProcesses(pids, timeoutSeconds),
+    killProcess: (pid) => getCliProcessService().killProcess(pid),
+    cleanupProcesses: () => getCliProcessService().cleanupProcesses(),
+    getDoctorStatus: () => getCliDoctorStatus(),
+};
+function parseArgs(argv) {
+    const positionals = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '-h') {
+            flags.h = '';
+            continue;
+        }
+        if (!arg.startsWith('--')) {
+            positionals.push(arg);
+            continue;
+        }
+        const eqIdx = arg.indexOf('=');
+        if (eqIdx !== -1) {
+            flags[arg.slice(2, eqIdx)] = arg.slice(eqIdx + 1);
+            continue;
+        }
+        const next = argv[i + 1];
+        if (next !== undefined && !next.startsWith('--')) {
+            flags[arg.slice(2)] = next;
+            i++;
+        }
+        else {
+            flags[arg.slice(2)] = '';
+        }
+    }
+    return { positionals, flags };
+}
+function getFirstFlag(flags, names) {
+    for (const name of names) {
+        if (name in flags) {
+            return flags[name];
+        }
+    }
+    return undefined;
+}
+function parsePositivePid(value) {
+    const pid = Number(value);
+    if (!Number.isInteger(pid) || pid <= 0) {
+        return null;
+    }
+    return pid;
+}
+function writeJson(stdout, value) {
+    stdout(`${JSON.stringify(value, null, 2)}\n`);
+}
+function hasHelpFlag(flags) {
+    return 'help' in flags || 'h' in flags;
+}
+export async function runCli(argv, deps = {}) {
+    const { stdout, stderr, startMcpServer, runProcess, listProcesses, getProcessResult, waitForProcesses, killProcess, cleanupProcesses, getDoctorStatus, } = { ...defaultDeps, ...deps };
+    const [command] = argv;
+    if (!command || command === 'help' || command === '--help' || command === '-h') {
+        stdout(CLI_HELP_TEXT);
+        return 0;
+    }
+    if (command === 'mcp') {
+        const { flags } = parseArgs(argv.slice(1));
+        if (hasHelpFlag(flags)) {
+            stdout(MCP_HELP_TEXT);
+            return 0;
+        }
+        await startMcpServer();
+        return 0;
+    }
+    if (command === 'run') {
+        const { flags } = parseArgs(argv.slice(1));
+        if (hasHelpFlag(flags)) {
+            stdout(RUN_HELP_TEXT);
+            return 0;
+        }
+        const cwd = getFirstFlag(flags, ['cwd', 'workFolder', 'work-folder']);
+        if (!cwd) {
+            stderr('Missing required option: --cwd\n');
+            stdout(CLI_HELP_TEXT);
+            return 1;
+        }
+        const prompt = getFirstFlag(flags, ['prompt']);
+        const promptFile = getFirstFlag(flags, ['prompt-file', 'prompt_file']);
+        if (!prompt && !promptFile) {
+            stderr('Missing required option: --prompt or --prompt-file\n');
+            stdout(CLI_HELP_TEXT);
+            return 1;
+        }
+        const result = await runProcess({
+            cwd,
+            prompt: prompt || undefined,
+            prompt_file: promptFile || undefined,
+            model: getFirstFlag(flags, ['model']) || undefined,
+            session_id: getFirstFlag(flags, ['session-id', 'session_id']) || undefined,
+            reasoning_effort: getFirstFlag(flags, ['reasoning-effort', 'reasoning_effort']) || undefined,
+        });
+        writeJson(stdout, result);
+        return 0;
+    }
+    if (command === 'ps') {
+        const { flags } = parseArgs(argv.slice(1));
+        if (hasHelpFlag(flags)) {
+            stdout(PS_HELP_TEXT);
+            return 0;
+        }
+        writeJson(stdout, await listProcesses());
+        return 0;
+    }
+    if (command === 'result') {
+        const { positionals, flags } = parseArgs(argv.slice(1));
+        if (hasHelpFlag(flags)) {
+            stdout(RESULT_HELP_TEXT);
+            return 0;
+        }
+        const pid = parsePositivePid(positionals[0]);
+        if (pid === null) {
+            stderr('Missing required pid argument\n');
+            stdout(CLI_HELP_TEXT);
+            return 1;
+        }
+        writeJson(stdout, await getProcessResult(pid, 'verbose' in flags));
+        return 0;
+    }
+    if (command === 'wait') {
+        const { positionals, flags } = parseArgs(argv.slice(1));
+        if (hasHelpFlag(flags)) {
+            stdout(WAIT_HELP_TEXT);
+            return 0;
+        }
+        const pids = positionals.map((value) => parsePositivePid(value));
+        if (pids.length === 0) {
+            stderr('Missing required pid arguments\n');
+            stdout(CLI_HELP_TEXT);
+            return 1;
+        }
+        if (pids.some((pid) => pid === null)) {
+            stderr('All pid arguments must be positive integers\n');
+            stdout(CLI_HELP_TEXT);
+            return 1;
+        }
+        const timeoutRaw = getFirstFlag(flags, ['timeout']);
+        const timeout = timeoutRaw ? Number(timeoutRaw) : undefined;
+        if (timeout !== undefined && (!Number.isFinite(timeout) || timeout <= 0)) {
+            stderr('Invalid --timeout value\n');
+            stdout(CLI_HELP_TEXT);
+            return 1;
+        }
+        writeJson(stdout, await waitForProcesses(pids, timeout));
+        return 0;
+    }
+    if (command === 'kill') {
+        const { positionals, flags } = parseArgs(argv.slice(1));
+        if (hasHelpFlag(flags)) {
+            stdout(KILL_HELP_TEXT);
+            return 0;
+        }
+        const pid = parsePositivePid(positionals[0]);
+        if (pid === null) {
+            stderr('Missing required pid argument\n');
+            stdout(CLI_HELP_TEXT);
+            return 1;
+        }
+        writeJson(stdout, await killProcess(pid));
+        return 0;
+    }
+    if (command === 'cleanup') {
+        const { flags } = parseArgs(argv.slice(1));
+        if (hasHelpFlag(flags)) {
+            stdout(CLEANUP_HELP_TEXT);
+            return 0;
+        }
+        writeJson(stdout, await cleanupProcesses());
+        return 0;
+    }
+    if (command === 'models') {
+        const { flags } = parseArgs(argv.slice(1));
+        if (hasHelpFlag(flags)) {
+            stdout(MODELS_HELP_TEXT);
+            return 0;
+        }
+        writeJson(stdout, getModelsPayload());
+        return 0;
+    }
+    if (command === 'doctor') {
+        const { flags } = parseArgs(argv.slice(1));
+        if (hasHelpFlag(flags)) {
+            stdout(DOCTOR_HELP_TEXT);
+            return 0;
+        }
+        writeJson(stdout, getDoctorStatus());
+        return 0;
+    }
+    stderr(`Unknown subcommand: ${command}\n`);
+    stdout(CLI_HELP_TEXT);
+    return 1;
+}

package/dist/app/mcp.js

@@ -0,0 +1,362 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from '@modelcontextprotocol/sdk/types.js';
+import { spawn } from 'node:child_process';
+import { debugLog, findClaudeCli, findCodexCli, findGeminiCli } from '../cli-utils.js';
+import { getModelParameterDescription, getSupportedModelsDescription } from '../model-catalog.js';
+import { ProcessService } from '../process-service.js';
+// Server version - update this when releasing new versions
+const SERVER_VERSION = "2.2.0";
+// Track if this is the first tool use for version printing
+let isFirstToolUse = true;
+// Capture server startup time when the module loads
+const serverStartupTime = new Date().toISOString();
+// Ensure spawnAsync is defined correctly *before* the class
+export async function spawnAsync(command, args, options) {
+    return new Promise((resolve, reject) => {
+        debugLog(`[Spawn] Running command: ${command} ${args.join(' ')}`);
+        const process = spawn(command, args, {
+            shell: false,
+            timeout: options?.timeout,
+            cwd: options?.cwd,
+            stdio: ['ignore', 'pipe', 'pipe']
+        });
+        let stdout = '';
+        let stderr = '';
+        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) => {
+            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) => {
+            debugLog(`[Spawn Close] Exit code: ${code}`);
+            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()}`));
+            }
+        });
+    });
+}
+export class ClaudeCodeServer {
+    server;
+    claudeCliPath;
+    codexCliPath;
+    geminiCliPath;
+    processService;
+    sigintHandler;
+    packageVersion;
+    constructor() {
+        this.claudeCliPath = findClaudeCli();
+        this.codexCliPath = findCodexCli();
+        this.geminiCliPath = findGeminiCli();
+        console.error(`[Setup] Using Claude CLI command/path: ${this.claudeCliPath}`);
+        console.error(`[Setup] Using Codex CLI command/path: ${this.codexCliPath}`);
+        console.error(`[Setup] Using Gemini CLI command/path: ${this.geminiCliPath}`);
+        this.packageVersion = SERVER_VERSION;
+        this.processService = new ProcessService({
+            cliPaths: {
+                claude: this.claudeCliPath,
+                codex: this.codexCliPath,
+                gemini: this.geminiCliPath,
+            },
+        });
+        this.server = new Server({
+            name: 'ai_cli_mcp',
+            version: SERVER_VERSION,
+        }, {
+            capabilities: {
+                tools: {},
+            },
+        });
+        this.setupToolHandlers();
+        this.server.onerror = (error) => console.error('[Error]', error);
+        this.sigintHandler = async () => {
+            await this.server.close();
+            process.exit(0);
+        };
+        process.on('SIGINT', this.sigintHandler);
+    }
+    setupToolHandlers() {
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+            tools: [
+                {
+                    name: 'run',
+                    description: `AI Agent Runner: Starts a Claude, Codex, or Gemini CLI process in the background and returns a PID immediately. Use list_processes and get_result to monitor progress.
+
+• File ops: Create, read, (fuzzy) edit, move, copy, delete, list files, analyze/ocr images, file content analysis
+• Code: Generate / analyse / refactor / fix
+• Git: Stage ▸ commit ▸ push ▸ tag (any workflow)
+• Terminal: Run any CLI cmd or open URLs
+• Web search + summarise content on-the-fly
+• Multi-step workflows & GitHub integration
+
+**IMPORTANT**: This tool now returns immediately with a PID. Use other tools to check status and get results.
+
+**Supported models**:
+${getSupportedModelsDescription()}
+
+**Prompt input**: You must provide EITHER prompt (string) OR prompt_file (file path), but not both.
+
+**Prompt tips**
+1. Be concise, explicit & step-by-step for complex tasks.
+2. Check process status with list_processes
+3. Get results with get_result using the returned PID
+4. Kill long-running processes with kill_process if needed
+
+        `,
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            prompt: {
+                                type: 'string',
+                                description: 'The detailed natural language prompt for the agent to execute. Either this or prompt_file is required.',
+                            },
+                            prompt_file: {
+                                type: 'string',
+                                description: 'Path to a file containing the prompt. Either this or prompt is required. Must be an absolute path or relative to workFolder.',
+                            },
+                            workFolder: {
+                                type: 'string',
+                                description: 'The working directory for the agent execution. Must be an absolute path.',
+                            },
+                            model: {
+                                type: 'string',
+                                description: getModelParameterDescription(),
+                            },
+                            reasoning_effort: {
+                                type: 'string',
+                                description: 'Reasoning control for Claude and Codex. Claude uses --effort with "low", "medium", "high". Codex uses model_reasoning_effort with "low", "medium", "high", "xhigh".',
+                            },
+                            session_id: {
+                                type: 'string',
+                                description: 'Optional session ID to resume a previous session. Supported for: haiku, sonnet, opus, gemini-2.5-pro, gemini-2.5-flash, gemini-3.1-pro-preview, gemini-3-pro-preview, gemini-3-flash-preview.',
+                            },
+                        },
+                        required: ['workFolder'],
+                    },
+                },
+                {
+                    name: 'list_processes',
+                    description: 'List all running and completed AI agent processes. Returns a simple list with PID, agent type, and status for each process.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {},
+                    },
+                },
+                {
+                    name: 'get_result',
+                    description: 'Get the current output and status of an AI agent process by PID. Returns the output from the agent including session_id (if applicable), along with process metadata.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            pid: {
+                                type: 'number',
+                                description: 'The process ID returned by run tool.',
+                            },
+                            verbose: {
+                                type: 'boolean',
+                                description: 'Optional: If true, returns detailed execution information including tool usage history. Defaults to false.',
+                            }
+                        },
+                        required: ['pid'],
+                    },
+                },
+                {
+                    name: 'wait',
+                    description: 'Wait for multiple AI agent processes to complete and return their results. Blocks until all specified PIDs finish or timeout occurs.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            pids: {
+                                type: 'array',
+                                items: { type: 'number' },
+                                description: 'List of process IDs to wait for (returned by the run tool).',
+                            },
+                            timeout: {
+                                type: 'number',
+                                description: 'Optional: Maximum time to wait in seconds. Defaults to 180 (3 minutes).',
+                            },
+                        },
+                        required: ['pids'],
+                    },
+                },
+                {
+                    name: 'kill_process',
+                    description: 'Terminate a running AI agent process by PID.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            pid: {
+                                type: 'number',
+                                description: 'The process ID to terminate.',
+                            },
+                        },
+                        required: ['pid'],
+                    },
+                },
+                {
+                    name: 'cleanup_processes',
+                    description: 'Remove all completed and failed processes from the process list to free up memory.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {},
+                    },
+                }
+            ],
+        }));
+        this.server.setRequestHandler(CallToolRequestSchema, async (args) => {
+            debugLog('[Debug] Handling CallToolRequest:', args);
+            const toolName = args.params.name;
+            const toolArguments = args.params.arguments || {};
+            switch (toolName) {
+                case 'run':
+                    return this.handleRun(toolArguments);
+                case 'list_processes':
+                    return this.handleListProcesses();
+                case 'get_result':
+                    return this.handleGetResult(toolArguments);
+                case 'wait':
+                    return this.handleWait(toolArguments);
+                case 'kill_process':
+                    return this.handleKillProcess(toolArguments);
+                case 'cleanup_processes':
+                    return this.handleCleanupProcesses();
+                default:
+                    throw new McpError(ErrorCode.MethodNotFound, `Tool ${toolName} not found`);
+            }
+        });
+    }
+    async handleRun(toolArguments) {
+        if (isFirstToolUse) {
+            console.error(`ai_cli_mcp v${SERVER_VERSION} started at ${serverStartupTime}`);
+            isFirstToolUse = false;
+        }
+        try {
+            const result = this.processService.startProcess({
+                prompt: toolArguments.prompt,
+                prompt_file: toolArguments.prompt_file,
+                workFolder: toolArguments.workFolder,
+                model: toolArguments.model,
+                session_id: toolArguments.session_id,
+                reasoning_effort: toolArguments.reasoning_effort,
+            });
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify(result, null, 2)
+                    }]
+            };
+        }
+        catch (error) {
+            const code = /Failed to start/.test(error.message) ? ErrorCode.InternalError : ErrorCode.InvalidParams;
+            throw new McpError(code, error.message);
+        }
+    }
+    async handleListProcesses() {
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(this.processService.listProcesses(), null, 2)
+                }]
+        };
+    }
+    async handleGetResult(toolArguments) {
+        if (!toolArguments.pid || typeof toolArguments.pid !== 'number') {
+            throw new McpError(ErrorCode.InvalidParams, 'Missing or invalid required parameter: pid');
+        }
+        const pid = toolArguments.pid;
+        const verbose = !!toolArguments.verbose;
+        try {
+            const response = this.processService.getProcessResult(pid, verbose);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify(response, null, 2)
+                    }]
+            };
+        }
+        catch (error) {
+            const code = /not found/.test(error.message) ? ErrorCode.InvalidParams : ErrorCode.InternalError;
+            throw new McpError(code, error.message);
+        }
+    }
+    async handleWait(toolArguments) {
+        if (!toolArguments.pids || !Array.isArray(toolArguments.pids) || toolArguments.pids.length === 0) {
+            throw new McpError(ErrorCode.InvalidParams, 'Missing or invalid required parameter: pids (must be a non-empty array of numbers)');
+        }
+        try {
+            const results = await this.processService.waitForProcesses(toolArguments.pids, typeof toolArguments.timeout === 'number' ? toolArguments.timeout : 180);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify(results, null, 2)
+                    }]
+            };
+        }
+        catch (error) {
+            const code = /not found/.test(error.message) ? ErrorCode.InvalidParams : ErrorCode.InternalError;
+            throw new McpError(code, error.message);
+        }
+    }
+    async handleKillProcess(toolArguments) {
+        if (!toolArguments.pid || typeof toolArguments.pid !== 'number') {
+            throw new McpError(ErrorCode.InvalidParams, 'Missing or invalid required parameter: pid');
+        }
+        const pid = toolArguments.pid;
+        try {
+            const response = this.processService.killProcess(pid);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify(response, null, 2)
+                    }]
+            };
+        }
+        catch (error) {
+            const code = /not found/.test(error.message) ? ErrorCode.InvalidParams : ErrorCode.InternalError;
+            const message = code === ErrorCode.InternalError
+                ? `Failed to terminate process: ${error.message}`
+                : error.message;
+            throw new McpError(code, message);
+        }
+    }
+    async handleCleanupProcesses() {
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(this.processService.cleanupProcesses(), null, 2)
+                }]
+        };
+    }
+    async run() {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+        console.error('AI CLI MCP server running on stdio');
+    }
+    async cleanup() {
+        if (this.sigintHandler) {
+            process.removeListener('SIGINT', this.sigintHandler);
+        }
+        await this.server.close();
+    }
+}
+export async function runMcpServer() {
+    const server = new ClaudeCodeServer();
+    await server.run();
+}

package/dist/bin/ai-cli-mcp.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { runMcpServer } from '../app/mcp.js';
+runMcpServer().catch((error) => {
+    process.stderr.write(`${error.message}\n`);
+    process.exit(1);
+});

package/dist/bin/ai-cli.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { runCli } from '../app/cli.js';
+runCli(process.argv.slice(2))
+    .then((exitCode) => {
+    process.exit(exitCode);
+})
+    .catch((error) => {
+    process.stderr.write(`${error.message}\n`);
+    process.exit(1);
+});