# Claude Code MCP - Agent Orchestration Platform

## Overview

A sophisticated **FastMCP Python server** that orchestrates multiple Claude Code agents across iTerm2 sessions, providing centralized management and inter-agent communication through task-based workflows.

## Architecture

**Agent Orchestration Platform** with:
- **iTerm2 Tab-Based Sessions**: No window complexity, pure tab management
- **Persistent Agent State**: Survives iTerm restarts with state recovery
- **Codebase-Linked Sessions**: Sessions tied to specific root filepaths
- **Maximum Security Isolation**: Process-level separation between agents
- **Task-Based Inter-Agent Communication**: ADDER+ workflow coordination
- **System Prompt Injection**: Automatic Agent_# naming and prompt prepending

## Core MCP Tools

| Tool | Purpose | Security Level |
|------|---------|----------------|
| `create_agent` | Creates new Claude Code agent instance | HIGH |
| `delete_agent` | Removes agent from system | HIGH |
| `create_session` | Creates session tied to root filepath | MEDIUM |
| `get_session_status` | Returns status of all agents in session | LOW |
| `delete_session` | Removes entire session and all agents | HIGH |
| `send_message_to_agent` | Sends message with ADDER+ prepending | MEDIUM |
| `clear_agent_conversation` | Closes current iTerm tab for agent | MEDIUM |
| `start_new_agent_conversation` | Opens new iTerm tab for agent | MEDIUM |

## ADDER+ Workflow Integration

Each agent operates with the comprehensive **ADDER+ (Advanced Development, Documentation & Error Resolution)** protocol, enabling:

- **Autonomous Task Management**: TODO.md-driven execution with real-time progress tracking
- **Advanced Programming Synthesis**: Design by Contract + defensive programming + type-driven development + property-based testing + functional programming patterns
- **Systematic Error Resolution**: Root Cause Analysis with automatic task generation
- **Inter-Agent Coordination**: Task-based communication through documentation files

## Security Model

- **Process Isolation**: Each Claude Code agent runs in separate process
- **Session Boundaries**: Agents cannot access other session codebases
- **State Encryption**: Persistent agent state encrypted at rest
- **Audit Logging**: All agent interactions logged for security analysis
- **Permission Model**: Role-based access control for agent operations

## Quick Start

```bash
# Install dependencies
uv sync

# Start the MCP server
python src/main.py
```

## Claude Desktop Configuration

To use this Agent Orchestration Platform with Claude Desktop, you need to configure it as an MCP server in Claude's configuration file.

### Configuration File Location

**macOS:**
```
~/Library/Application Support/Claude/claude_desktop_config.json
```

**Windows:**
```
%APPDATA%/Claude/claude_desktop_config.json
```

### Configuration Steps

1. **Open Configuration File**: Navigate to the configuration file location above. Create the file if it doesn't exist.

2. **Add Server Configuration**: Add the following configuration to your `claude_desktop_config.json`:

#### Option 1: Using UV (Recommended)
```json
{
  "mcpServers": {
    "claude-code-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/Claude_Code_MCP",
        "run",
        "python",
        "src/main.py"
      ],
      "env": {
        "PYTHONPATH": "/ABSOLUTE/PATH/TO/Claude_Code_MCP/src"
      }
    }
  }
}
```

#### Option 2: Using Python Directly
```json
{
  "mcpServers": {
    "claude-code-mcp": {
      "command": "python",
      "args": [
        "/ABSOLUTE/PATH/TO/Claude_Code_MCP/src/main.py"
      ],
      "env": {
        "PYTHONPATH": "/ABSOLUTE/PATH/TO/Claude_Code_MCP/src"
      }
    }
  }
}
```

#### Option 3: Using Virtual Environment
```json
{
  "mcpServers": {
    "claude-code-mcp": {
      "command": "/ABSOLUTE/PATH/TO/Claude_Code_MCP/.venv/bin/python",
      "args": [
        "/ABSOLUTE/PATH/TO/Claude_Code_MCP/src/main.py"
      ],
      "env": {
        "PYTHONPATH": "/ABSOLUTE/PATH/TO/Claude_Code_MCP/src"
      }
    }
  }
}
```

### Configuration Notes

- **Replace `/ABSOLUTE/PATH/TO/Claude_Code_MCP`** with the actual absolute path to your project directory
- **On Windows**, use backslashes in paths: `C:\\path\	o\\Claude_Code_MCP`
- **Server Name**: You can change `"claude-code-mcp"` to any name you prefer
- **Virtual Environment**: If using a virtual environment, adjust the Python path accordingly

### Advanced Configuration Options

#### With Custom Security Level
```json
{
  "mcpServers": {
    "claude-code-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/Claude_Code_MCP",
        "run",
        "python",
        "src/main.py",
        "--security-level",
        "HIGH",
        "--max-agents",
        "16",
        "--max-sessions",
        "8"
      ],
      "env": {
        "PYTHONPATH": "/ABSOLUTE/PATH/TO/Claude_Code_MCP/src"
      }
    }
  }
}
```

#### With Custom Log Directory
```json
{
  "mcpServers": {
    "claude-code-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/Claude_Code_MCP",
        "run",
        "python",
        "src/main.py",
        "--log-dir",
        "/ABSOLUTE/PATH/TO/Claude_Code_MCP/logs"
      ],
      "env": {
        "PYTHONPATH": "/ABSOLUTE/PATH/TO/Claude_Code_MCP/src"
      }
    }
  }
}
```

### Verification Steps

1. **Save Configuration**: Save the `claude_desktop_config.json` file
2. **Restart Claude Desktop**: Completely quit and restart Claude Desktop
3. **Check MCP Status**: Look for MCP server indicators in the Claude Desktop interface:
   - Hammer icon (🔨) indicating available tools
   - Connector icon indicating MCP server connection
4. **Test Functionality**: Try using one of the agent orchestration tools

### Troubleshooting

#### Server Not Loading
- Verify all paths are absolute (not relative)
- Check that `uv` or `python` is in your system PATH
- Ensure the project directory exists and has correct permissions
- Review Claude Desktop logs at:
  - **macOS**: `~/Library/Logs/Claude/mcp*.log`
  - **Windows**: `%APPDATA%\Claude\logs\mcp*.log`

#### Manual Testing
Test the server manually before configuring Claude Desktop:
```bash
# Navigate to project directory
cd /path/to/Claude_Code_MCP

# Test with UV
uv run python src/main.py --help

# Test with Python directly
python src/main.py --help
```

#### Common Issues
- **Permission Errors**: Ensure Claude Desktop has permission to execute the Python interpreter
- **Import Errors**: Verify `PYTHONPATH` is correctly set in the configuration
- **Port Conflicts**: If using HTTP transport, ensure the port (default 8000) is available

### Available MCP Tools

Once configured, Claude Desktop will have access to these agent orchestration tools:

- `create_agent` - Create new Claude Code agent instances
- `delete_agent` - Remove agents from the system
- `create_session` - Create sessions tied to specific codebases
- `get_session_status` - Get status of all agents in a session
- `delete_session` - Remove entire sessions and all agents
- `send_message_to_agent` - Send messages with ADDER+ protocol integration
- `clear_agent_conversation` - Close current iTerm tab for agent
- `start_new_agent_conversation` - Open new iTerm tab for agent

## Development Workflow

1. **Session Creation**: Link sessions to specific codebases
2. **Agent Spawning**: Create specialized agents with custom system prompts
3. **Task Coordination**: Agents communicate through TODO.md and task files
4. **Status Monitoring**: Real-time visibility into agent progress and health
5. **Session Management**: Persistent state with recovery capabilities

## Integration Points

- **FastMCP Framework**: High-performance MCP server implementation
- **iTerm2 Python API**: Advanced terminal session management
- **Claude Code**: AI agent process orchestration
- **Asyncio Architecture**: Event-driven concurrent agent management

This platform enables sophisticated AI development workflows with multiple specialized agents working collaboratively on complex codebases while maintaining strict security isolation and comprehensive audit trails.