Content
# opencode-mcp-bridge
A Model Context Protocol (MCP) server that lets any AI tool (Claude Code, Antigravity, VS Code, Cursor, Windsurf, JetBrains, Claude Desktop, etc.) delegate tasks to the [OpenCode CLI](https://github.com/sst/opencode) as a subagent — driven entirely through OpenCode's own `opencode serve` HTTP/SSE API, with async push events, task contracts, context tracking, checkpoints, and multi-session orchestration.
> Agent instructions live in [`AGENTS.md`](./AGENTS.md) — or just call the `opencode_guide` tool once this server is registered; it returns the same guide live from the running server's actual state.
## Architecture
The bridge talks to a single, long-lived `opencode serve` process over plain HTTP:
- **One shared process, unlimited sessions.** `server-manager.ts` spawns and singleton-manages `opencode serve` (state tracked in `~/.opencode-bridge/server.json`); every `opencode_start` call just creates a lightweight session on that one server instead of launching a new CLI process per task. No `node-pty` native binding, no per-task re-authentication.
- **One event stream, every session.** A single SSE connection to `/api/event` carries events for all sessions, tagged by `durable.aggregateID`; `http-bridge.ts` fans them out to the right local session (`session.next.step.started/ended/failed`, `session.next.tool.called`, `session.next.text.delta`, …) and derives status (`running` / `idle` / `waiting_input` / `error`) from them — no ANSI scraping, no idle-timer heuristics.
- **Self-healing.** OpenCode's HTTP API does not surface session-runner failures (e.g. a model resolution error) as API-visible errors or events — a failed session just sits at `running` forever, indistinguishable from working. The bridge tails OpenCode's own internal log (`~/.local/share/opencode/log/opencode.log`) to detect these failures immediately, and runs a stall watchdog (zero tokens generated N seconds after a prompt) as a second line of defense. Because a single such failure has been observed to wedge that server process's entire turn queue, detecting one triggers an automatic restart of `opencode serve` so subsequent sessions aren't collateral damage.
## Features
- ⚡ **Async Events**: Writes state transitions (`running`, `idle`, `waiting_input`, `error`, `stale`, `contract_violated`) to `~/.opencode-mcp-events.jsonl`.
- 🔀 **Multi-Session Orchestration**: Run up to 3 concurrent OpenCode sessions with dependency ordering (`opencode_batch`).
- 🗂️ **Context Bucket**: Tracks every file creation/modification reported by the session's event stream.
- 🛡️ **Task Contracts**: Enforce duration limits, path scope restrictions, file count caps, and forbidden commands.
- 📸 **Checkpoints & Recovery**: Auto-save state snapshots every 60s and retry failed sessions from any checkpoint.
- 🎯 **Pre-Flight Classifier**: Score incoming tasks to decide whether to delegate and recommend the best model.
- 🩺 **Failure visibility**: `opencode_health` exposes `last_error` — the real underlying exception from OpenCode's runner, not just a generic hang.
- 🖥️ **Server introspection**: `opencode_server_health` / `opencode_server_restart` expose and control the underlying `opencode serve` process itself, separate from any individual session.
- 📖 **Self-documenting**: `opencode_guide` returns a complete, live behavioral guide (model selection, workflow, gotchas) generated from the running server's actual state — works identically in any MCP host.
## Prerequisites
- [Node.js](https://nodejs.org) v18+
- [OpenCode CLI](https://github.com/sst/opencode) installed and authenticated (`opencode auth login`) — run `opencode --version` to confirm it's on PATH.
## Quick Start
1. **Clone and build:**
```bash
git clone https://github.com/Dheerax/opencode_mcp.git
cd opencode_mcp
npm install
npm run build
```
2. **Register as an MCP server:**
- **Claude Code:**
```bash
claude mcp add -s user opencode-mcp-bridge -- node /absolute/path/to/opencode_mcp/dist/index.js
```
- **Antigravity / VS Code / Cursor / Windsurf:**
Add to your MCP server configuration:
```json
{
"mcpServers": {
"opencode-mcp-bridge": {
"command": "node",
"args": ["/absolute/path/to/opencode_mcp/dist/index.js"]
}
}
}
```
3. **Run Setup:**
Invoke the `opencode_setup` tool once from your host agent to generate workspace integration instructions, then call `opencode_guide` to get the full usage guide.
## All tools
See [`AGENTS.md`](./AGENTS.md) for the complete tool reference table and workflow guide — or call the `opencode_guide` MCP tool directly, which returns the same content live.
## Troubleshooting
If a session's status stays `error` immediately and `opencode_health`'s `last_error` mentions `ModelUnavailableError` for a provider you expect to work (e.g. a `google/*` model), the provider's cached OAuth token has likely expired. Re-authenticate it directly:
```bash
opencode auth logout <provider>
opencode auth login <provider>
```
This is an OpenCode/provider-auth issue, not something the bridge can fix by itself — it can only detect it, report it via `last_error`, and recover the server process so it doesn't stay wedged for other sessions.
## License
[MIT](./LICENSE)
