Claude Code Multi-Process MCP Server

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview This is a **FastMCP-based multi-process execution server** for Claude Code CLI that enables parallel task processing through asynchronous subprocess management. It provides a modern framework alternative to the original async MCP server implementation. ## Architecture **Type**: FastMCP Server using decorators and stdio transport **Language**: Python 3.6+ (FastMCP + standard library) **Core Pattern**: Decorator-based tool registration with filesystem task persistence ## Key Components - **`main.py`** - Single-file server implementation with FastMCP decorators - **TaskManager class** - Handles process lifecycle and cleanup - **Task storage** - Filesystem-based in `/tmp/cc_process_tasks/` - **Process management** - SIGCHLD handler for automatic zombie process reaping - **Logging** - Comprehensive logging to `/tmp/cc_process_mcp.log` ## MCP Tools (via FastMCP Decorators) 1. **`execute_cc_task`** - Synchronous Claude Code execution 2. **`start_cc_task_async`** - Async task start, returns task ID 3. **`check_task_status`** - Status and result retrieval 4. **`list_active_tasks`** - List all running processes 5. **`cleanup_task`** - Manual task and resource cleanup ## Development Commands **Installation and Setup:** ```bash # Create virtual environment (required on macOS) python3 -m venv venv source venv/bin/activate # Install dependencies pip install -r requirements.txt # Make main script executable chmod +x main.py # Test server directly (use virtual environment python) ./venv/bin/python3 main.py # Monitor logs tail -f /tmp/cc_process_mcp.log # Check task storage ls -la /tmp/cc_process_tasks/ # Deactivate virtual environment when done deactivate ``` **Configuration:** ```bash # Add to ~/.claude/settings.json # Use virtual environment python path: /path/to/project/venv/bin/python3 # Use absolute path for args: /path/to/project/main.py ``` ## Technical Implementation ### FastMCP Integration - Uses `@server.tool` decorators for tool registration - Automatic JSON-RPC handling via FastMCP framework - Clean separation of concerns with TaskManager class - Type hints and proper parameter validation ### Process Management Pattern ```python # Async process creation proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE) task_manager.active_processes[task_id] = proc # Signal-based cleanup def cleanup_handler(signum, frame): for task_id, proc in list(task_manager.active_processes.items()): if proc.poll() is not None: del task_manager.active_processes[task_id] ``` ### Task Persistence - JSON-based result storage per task - Task isolation with individual directories - Status tracking: running → completed/failed/timeout - Atomic file operations for result consistency ## Code Organization **Main Components:** - FastMCP server initialization (top level) - TaskManager class with signal handlers - Tool implementations using decorators - Filesystem I/O operations with error handling **Naming Conventions:** - Clear function names: `execute_cc_task`, `start_cc_task_async` - Consistent variable naming: `task_id`, `proc`, `result_data` - Directory naming: `TASK_STORAGE_DIR`, `LOG_FILE` **Error Handling Pattern:** ```python try: # operation except subprocess.TimeoutExpired: # timeout handling except Exception as e: logger.error(f"Error: {e}") # fallback response ``` ## Design Differences from Original This implementation differs from the reference project in several key ways: 1. **Framework Choice**: Uses FastMCP decorators vs raw JSON-RPC implementation 2. **Variable Naming**: `task_manager` vs `task_dir`, `active_processes` vs process tracking 3. **Storage Paths**: `/tmp/cc_process_tasks/` vs `/tmp/claude_code_tasks/` 4. **Tool Names**: `execute_cc_task` vs `claude_code_execute` 5. **Class Structure**: TaskManager class vs global functions 6. **Log Format**: Structured logging with timestamps and levels ## Key Features **Process Safety:** - SIGCHLD automatic cleanup - Graceful process termination - Zombie process prevention - Resource cleanup on task completion **Task Management:** - UUID-based task identification - Filesystem persistence across restarts - Status tracking and result caching - Manual cleanup capabilities **Monitoring and Debugging:** - Comprehensive logging system - Process lifecycle tracking - Task status inspection - Error reporting and recovery ## Configuration Requirements **Claude Code MCP Settings:** ```json { "mcpServers": { "cc-multi-process": { "command": "/absolute/path/to/project/venv/bin/python3", "args": ["/absolute/path/to/project/main.py"], "description": "Claude Code Multi-Process MCP Server - Provides parallel task execution capabilities" } } } ``` **System Requirements:** - Unix-like OS (for signal handling) - Python 3.6+ with FastMCP - Virtual environment (required on modern macOS) - Claude Code CLI accessible via PATH - Write permissions to `/tmp/` directory ## Common Issues and Solutions **Server Registration:** - Verify virtual environment Python path in configuration - Check absolute paths for both command and args - Ensure virtual environment exists and contains FastMCP - Restart Claude Code after config changes - Test server manually: `./venv/bin/python3 main.py` **Process Management:** - Use `list_active_tasks()` to monitor running processes - Check `/tmp/cc_process_mcp.log` for debugging information - Use `cleanup_task()` for manual resource cleanup - Monitor system resources with `ps aux | grep claude` **Task Execution:** - Verify Claude Code CLI installation - Check working directory permissions - Monitor task status with `check_task_status()` - Review task results in `/tmp/cc_process_tasks/`