opencode-cli-mcp

# opencode-cli-mcp - Full Context

**Version:** 0.2.10
**FastMCP:** 3.4.4+
**Python:** 3.12+
**License:** MIT

---

## What It Does

Bridges [opencode](https://opencode.ai/) (the open source AI coding agent) into the MCP ecosystem. AI assistants (Claude, etc.) can use this server to delegate implementation tasks to opencode running on cheaper models - enabling tiered model economics.

---

## Architecture

```
┌──────────────┐    stdio     ┌──────────────────┐    httpx     ┌──────────────┐
│  MCP Clients │◄───────────►│  opencode-cli-mcp │◄───────────►│ opencode serve│
│  (Claude…)   │     MCP      │  (FastMCP 3.4.4) │   :4097     │  (opencode)   │
└──────────────┘              └──────────────────┘              └──────┬───────┘
                                                                       │ subprocess
                                                                  ┌────▼───────┐
                                                                  │ opencode   │
                                                                  │ agent run  │
                                                                  └────────────┘

┌────────────────┐   proxy   ┌──────────────────┐   httpx    ┌──────────────────┐
│ Vite/React SPA │──────────►│  Unified Backend  │──────────►│  opencode serve  │
│    :10950      │  /api/*   │  api.main:app     │   :4097   │                  │
└────────────────┘           │  :10951           │            └──────────────────┘
                             │  REST /api/*      │
                             │  + MCP /mcp       │
                             └───────────────────┘
```

The backend is a single ASGI app (`api.main:app`): REST routes under `/api/*`
plus the FastMCP Streamable HTTP endpoint mounted at `/mcp` (with its lifespan
wired) on the same port. One process serves the webapp and MCP clients.

## Repository Structure

```
opencode-cli-mcp/
├── api/
│   ├── main.py              # Unified ASGI app: REST /api/* + FastMCP /mcp
│   └── routes/
│       ├── capabilities.py  # GET /api/capabilities, /api/health, /api/v1/health
│       ├── fleet.py         # GET /api/fleet (port scanner)
│       ├── proxy.py         # opencode serve proxy routes
│       ├── settings.py      # GET/PUT /api/settings
│       ├── system.py        # GET /api/system, /api/llm/providers, /api/ollama/*
│       ├── logs.py          # GET /api/logs (+ export, DELETE)
│       └── tools.py         # GET /api/tools (from registry)
├── src/opencode_cli_mcp/
│   ├── server.py            # FastMCP 3.4 app + mcp_app/http_app
│   ├── client.py            # httpx client → opencode serve (shutil.which binary)
│   ├── depot.py             # Direct SQLite access to opencode.db (depot ops)
│   ├── job_store.py         # Async job tracking
│   ├── registry.py          # Shared tool definitions
│   └── tools/
│       ├── agent.py         # opencode_run_agent
│       ├── depot.py         # opencode_depot portmanteau
│       ├── runs.py          # Job status/polling
│       ├── sessions.py      # Session CRUD
│       └── status.py        # opencode health/config
├── tests/
│   ├── conftest.py
│   ├── test_depot.py        # Depot layer + tool tests
│   └── test_server.py       # Registration tests
├── web_sota/                # React dashboard
│   ├── src/
│   │   ├── App.tsx          # Router (15 pages)
│   │   ├── Layout.tsx       # Shell (+ experimental light-mode toggle)
│   │   ├── store.ts         # Zustand state
│   │   ├── services/api.ts  # HTTP client
│   │   └── pages/           # Dashboard, Sessions, Settings, etc.
│   ├── vite.config.ts       # :10950, proxy /api → :10951
│   └── package.json
├── start.ps1                # Fleet-standard startup
├── start.bat                # Double-click wrapper
├── justfile                 # just test / just lint / just check
├── glama.json               # MCP discovery
├── CLAUDE.md                # Agent instructions
├── llms.txt                 # This file (concise)
└── llms-full.txt            # This file (full context)
```

## MCP Tools (22 total: 7 primary + 15 legacy aliases)

Primary surface (portmanteaus + atomic):

| Tool | Description |
|------|-------------|
| `opencode_runs(action=...)` | start / status / list / cancel agent runs |
| `opencode_sessions(action=...)` | list / get / messages / send / diff / grep / export / **rename / delete** sessions (live `opencode serve` API - UI picks changes up immediately) |
| `opencode_depot(action=...)` | **eternal memory** - list/archive/unarchive/rename/delete/**search**/stats/**rag**/rag_index/rag_status/**code**/code_index/code_status over the opencode SQLite DB. search = wayback full-text (FTS5) across EVERY session since install; rag = semantic recall over indexed transcripts; code = when an agent touched a file (patch paths + edit inputs, by path or content) - all over LanceDB + fastembed (`uv sync --extra rag`), works offline. |
| `opencode_backups(action=...)` | **protect the memory** - db + config snapshots (SQLite online backup API, consistent while serve runs), rotation (10/kind), disk-space guard, guarded restore (refuses while serve runs unless force=True) |
| `opencode_system(action=...)` | status / providers / project / launch_ui / mcp_pulse / config_drift |
| `opencode_mcpb_install(...)` | install .mcpb bundles into opencode config (dry-run support) |
| `opencode_shutdown(confirm=...)` | graceful self-termination |

## Eternal Session Memory

opencode persists EVERY session and message since install in
`~/.local/share/opencode/opencode.db` (SQLite: session/message/part tables,
FTS5-indexed). No other agentic IDE has this - you cannot ask Claude/Cursor
"What were we discussing last December about X?", but with these tools you can:

1. `opencode_depot(action="search", query="<topic>")` - wayback find: full-text across ALL transcripts
2. `opencode_depot(action="rag", query="<describe it in your own words>")` - semantic recall (index once with rag_index)
3. `opencode_sessions(action="get"|"messages"|"export", session_id=...)` - read/render it
4. `opencode_depot(action="get"...)` - metadata (dates, cost, files)
5. `opencode_backups(action="create", kind="all")` - protect it (autobackup 24h, rotation, disk guard)

Full guide: docs/ETERNAL_MEMORY.md (also on the webapp Help page).

Legacy aliases (deprecated in 0.3.0): `opencode_run_agent`, `opencode_launch_ui`, `opencode_list_sessions`, `opencode_get_session`, `opencode_send_message`, `opencode_get_messages`, `opencode_session_diff`, `opencode_server_status`, `opencode_list_providers`, `opencode_get_project`, `opencode_get_config`, `opencode_get_health`, `opencode_get_run_status`, `opencode_list_runs`, `opencode_cancel_run`, `opencode_session_grep`, `opencode_export_session`, `opencode_config_drift`, `opencode_mcp_pulse`.

Prefab cards: `show_runs_app`, `show_sessions_app`, `show_status_app`.
Prompt: `agent_instructions`.

## API Routes

| Method | Path | Description |
|--------|------|-------------|
| GET | /api/health | Service health |
| GET | /api/v1/health | Canonical fleet health (probed by start.ps1 / CUA) |
| GET | /api/v1/diagnostics | CUA smoke-test contract: backend, system, tools, cua_status, errors |
| GET | /api/system | System stats (CPU, mem, GPU) |
| GET | /api/tools | Tool list from MCP registry |
| GET | /api/capabilities | Server capabilities |
| GET | /api/fleet | Fleet port scanner |
| GET | /api/opencode/status | opencode serve health (autostarts serve if down) |
| GET | /api/opencode/sessions | Session list |
| GET | /api/opencode/sessions/{id} | Session detail |
| GET | /api/opencode/sessions/{id}/diff | File diffs |
| PATCH | /api/opencode/sessions/{id} | Rename session (live serve API) |
| DELETE | /api/opencode/sessions/{id}?confirm=true | Delete session (live serve API) |
| GET | /api/backups/status | Backup paths, free space, counts, last autobackup |
| GET | /api/backups/list | Backup files (db + config) |
| POST | /api/backups/create?kind=db\|config\|all | Create a backup snapshot |
| POST | /api/backups/prune | Delete backups beyond retention |
| POST | /api/backups/restore | Restore db/config (confirm + force required) |
| DELETE | /api/backups/{name} | Delete one backup file |
| GET | /api/runs | Run list |
| GET | /api/runs/{id} | Run detail |
| GET | /api/settings | Get settings |
| PUT | /api/settings | Update settings |
| GET | /api/ollama/status | Ollama/LM Studio availability |
| GET | /api/llm/discover | LLM liveness probe (alias of /api/ollama/status) |
| GET | /api/ollama/models | Model lists |
| GET | /api/llm/models | Model lists (alias of /api/ollama/models) |
| GET | /api/llm/providers | Detection-driven provider list (+ models) |
| GET | /api/llm/onboarding | Fresh-install starter facts + recommended provider |
| GET | /api/skills | Fleet-standard skill listing (OpenCode custom tools) |
| POST | /api/chat | LLM chat (Ollama / LM Studio / cloud) |
| POST | /api/llm/chat | LLM chat (alias of /api/chat) |
| GET | /api/logs | Ring-buffer request logs |
| GET | /api/logs/export | Export logs |
| DELETE | /api/logs | Clear logs |
| POST | /api/shutdown | Graceful server shutdown |
| POST | /mcp | FastMCP Streamable HTTP endpoint (same port) |

## Startup

```powershell
.\start.ps1              # All services (zombie kill + install + launch)
.\start.bat              # Double-click wrapper
```

Run individually:
```powershell
uv run python -m api.main           # Unified backend :10951 (REST + MCP /mcp)
Set-Location web_sota; npm run dev  # Frontend :10950
opencode serve --port 4097          # opencode HTTP API (dedicated port; autostarted by proxy if down)
```

## Build/Test

```powershell
uv run pytest              # 158 tests
just test                  # same
just check                 # ruff check + format check
just type-check            # pyright src/ api/
just check                 # ruff check + format check
just certify               # all gates: ruff, pytest, pyright, tsc, biome
cd web_sota; npx tsc --noEmit  # frontend types
cd web_sota; npm run biome:ci   # frontend lint
```

## Ports

| Port | Service |
|------|---------|
| 10950 | Vite dev server (React) |
| 10951 | Unified backend (REST `/api/*` + MCP `/mcp`) |
| 4097 | opencode serve HTTP API (dedicated; desktop app owns 4096) |

## Dependencies

**Python:** fastmcp>=3.4.4, fastapi>=0.115, uvicorn>=0.34, httpx>=0.28, pydantic>=2.0, prefab-ui>=0.14, psutil>=6.0
**Node:** react 18, vite 5.4, tailwindcss 3.4, framer-motion, zustand, lucide-react, @tauri-apps/api
**Dev:** ruff, pyright, pytest, pytest-asyncio, pytest-cov, pre-commit, typescript

**Run via:** uv (Python), npm (frontend)

## Notes

- `opencode serve` autostarts on first tool call if down (binary resolved via `shutil.which` - npm `.cmd` shims work)
- The backend is one ASGI app: REST + FastMCP on a single port (10951)
- `opencode_depot` reads the opencode SQLite DB directly (`~/.local/share/opencode/opencode.db`, `OPENCODE_DB_PATH` override) - works offline, no serve needed
- `opencode_backups` snapshots the DB with the SQLite online backup API (consistent while serve runs) and zips the config dir; autobackup on startup + every `OPENCODE_CLI_MCP_BACKUP_INTERVAL_HOURS` (default 24, 0 off), rotation `OPENCODE_CLI_MCP_BACKUP_RETENTION` (10), disk guard `OPENCODE_CLI_MCP_BACKUP_MIN_FREE_MB` (500), dir `OPENCODE_CLI_MCP_BACKUP_DIR`
- Session rename/delete has TWO paths: live (`opencode_sessions` action=rename/delete via PATCH/DELETE /session/{id} on `opencode serve` - race-free, UI updates immediately) and offline (`opencode_depot` action=rename/delete direct SQLite). Prefer the live path while opencode is running - a direct-DB title write can be overwritten by the server's next session save.
- Frontend proxies `/api/*`, `/docs`, `/openapi.json`, `/redoc` to backend
- Experimental light-mode toggle in the topbar (CSS invert hack, `ocmcp-light-mode` key)
- Fleet port scanner in fleet.py probes all WEBAPP_PORTS.md entries
- Ollama/LM Studio/vLLM auto-detected for the local LLM settings