# Claude Desktop → OpenCode CLI Development Bridge MCP

A local [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that connects **Claude Desktop** (Planner / Architect) to **OpenCode CLI** (Coding Engineer / Executor) via standard input/output (`stdio`) transport.

## 1. Architecture

```text
                    USER
                      │
                 CLAUDE DESKTOP
                 PLANNER/ARCHITECT
                      │
                dynamic prompt
                      │
                 MCP SERVER
                    BRIDGE
                      │
           ┌──────────┴──────────┐
           ▼                     ▼
      IDE Launcher          OPENCODE CLI
   (VS Code / Antigravity)  CODING ENGINEER
                                 │
           ┌─────────────────────┼─────────────────────┐
           ▼                     ▼                     ▼
        Files                 Terminal               Tests
           │                     │                     │
           └─────────────────────┼─────────────────────┘
                                 │
                            LOCAL PROJECT
                                 │
                           REAL EXECUTION
                                 │
                       PASS / PARTIAL / FAIL
                                 │
                              MCP SERVER
                                 │
                            CLAUDE DESKTOP
                                 │
                       next engineering instruction
```

### Key Principles

- **Claude Desktop** is the **Planner/Architect**: Requirements analysis, architectural design, task decomposition, and reviewing execution feedback.
- **OpenCode CLI** is the **Coding Engineer**: Inspects the workspace, writes/edits code, executes commands, builds projects, runs automated tests, and fixes implementation errors.
- **MCP Server** is the **Bridge**: Handles environment verification, opens workspaces in VS Code or Antigravity IDE when requested, launches OpenCode CLI process as a local subprocess, parses output/session events, and returns execution feedback.

---

## 2. Requirements

- **Operating System**: Windows 10/11, macOS, or Linux
- **Python**: Version 3.10 or higher
- **OpenCode CLI**: Installed globally (`npm install -g opencode-ai` or similar)
- **Target IDE (Optional)**: VS Code (`code`) or Antigravity IDE (`antigravity-ide`)

---

## 3. Installation

### Step 1: Navigate to Project Directory
```powershell
cd "d:\AI tools\MCP's\Claude-Opencode"
```

### Step 2: Create & Activate Virtual Environment
```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
```

### Step 3: Install Package
```powershell
pip install -r requirements.txt
pip install -e .
```

---

## 4. Claude Desktop Configuration

Locate your Claude Desktop configuration file:
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

Add the `opencode` server configuration:

```json
{
  "mcpServers": {
    "opencode": {
      "command": "d:\\AI tools\\MCP's\\Claude-Opencode\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "antigravity_mcp.server"
      ],
      "env": {
        "PYTHONPATH": "src",
        "DEFAULT_IDE": "cli_direct",
        "OPENCODE_PATH": "C:\\Users\\LENOVO\\AppData\\Roaming\\npm\\opencode.cmd",
        "VSCODE_PATH": "C:\\Users\\LENOVO\\AppData\\Local\\Programs\\Microsoft VS Code\\bin\\code.cmd",
        "ANTIGRAVITY_PATH": "D:\\AI tools\\Antigravity\\Antigravity IDE\\bin\\antigravity-ide.cmd"
      }
    }
  }
}
```

### Path Overrides

If Claude Desktop does not inherit your full environment `PATH`, configure explicit executable paths:
- `OPENCODE_PATH`: Path to `opencode` / `opencode.cmd` / `opencode.exe`
- `VSCODE_PATH`: Path to `code.cmd` / `code.exe`
- `ANTIGRAVITY_PATH`: Path to `antigravity-ide.cmd`
- `DEFAULT_IDE`: Preferred execution environment (`cli_direct`, `vs_code`, `antigravity`)

---

## 5. Primary MCP Tools

| Tool Name | Parameters | Description |
|-----------|------------|-------------|
| `delegate_to_opencode` | `prompt: string`, `workspace_path: string`, `ide?: string` | **Primary Engineering Tool**. Forwards dynamic engineering instructions to OpenCode CLI in target workspace. Returns structured execution status (`STATUS: PASS / PARTIAL / FAIL`), file diffs, exit codes, and output. |
| `continue_opencode` | `interaction_id: string`, `prompt: string`, `workspace_path: string`, `ide?: string` | Continue an active OpenCode session using real OpenCode session ID (`interaction_id`). |
| `open_workspace_in_ide` | `workspace_path: string`, `ide?: string` | Open workspace directory in VS Code or Antigravity IDE. |
| `get_opencode_status` | *None* | Check OpenCode CLI installation, version, and IDE environment status. |

Backward compatibility aliases (`delegate_to_antigravity`, `ask_antigravity`, `continue_antigravity`, `open_antigravity_workspace`) are also provided and route directly to OpenCode CLI.

---

## 6. Testing

To run the complete test suite:

```powershell
$env:PYTHONPATH="src"; .venv\Scripts\python.exe -m pytest
```

To run with live OpenCode CLI LLM execution smoke tests:

```powershell
$env:PYTHONPATH="src"; $env:RUN_REAL_OPENCODE_SMOKE="1"; .venv\Scripts\python.exe -m pytest
```

# Claude-Opencode-mcp