opencode-router-mcp
# opencode-router-mcp
Cost-aware, multimodal OpenCode task router and sub-agent MCP server for Claude Code.
This is a Windows-first optional OpenCode execution channel for Claude Code, based on the intended refactoring of `AlaeddineMessadi/opencode-mcp`. Claude remains the primary agent and may work natively or use Claude subagents; this MCP only manages OpenCode after Claude has selected that path. It exposes only seven compact high-level tools: `opencode_delegate`, `opencode_status`, `opencode_review`, `opencode_revise`, `opencode_abort`, `opencode_models`, and `opencode_usage`.
## Run
Requires Node.js 20+ and an OpenCode installation on PATH. Start over stdio with `node src/server.mjs`. The repository includes `.mcp.json` for Claude Code; update its absolute paths if the project is moved.
Run `npm run models:refresh` after OpenCode Go is configured. Model IDs are read from `opencode models`; this project never guesses IDs from display names. The registry remains empty when OpenCode is unavailable. `npm run models:probe-vision` reports whether a real probe was possible; it never fabricates success.
The router defaults to `run` for cheap/balanced tasks and `session` for powerful tasks after Claude has already selected OpenCode. `mode: auto` only chooses one-shot versus persistent OpenCode execution; it never chooses Claude or a Claude subagent. It retries/fails over transient model errors within a tier, disables a provider after shared quota errors, and only upgrades capability when explicitly allowed. Provider remaining quota is always reported as `unknown`; local usage is estimated only.
## Security
Directories and attachments must be absolute and existing. System roots, secrets, credential files, unsupported MIME extensions, oversized files, and more than five attachments are rejected. OpenCode should be configured to listen on localhost only. No global unrestricted permissions, raw shell tool, session sharing, or secret-bearing configuration is provided.
## Development
`npm run build`, `npm test`, `npm run test:skill`, `npm run test:security`, `npm run test:failover`, `npm run test:smoke`, `npm run test:e2e`, and `npm run test:closed-loop` are the local verification commands. `npm run test:opencode-free` performs a real, read-only smoke test using a discovered model whose ID is explicitly marked `free`; it never selects an unmarked model. `npm run test:vision` reports `SKIPPED` when no verified image model exists. See `docs/` and `.claude/skills/opencode-use/` for routing guidance. No commits or pushes are performed automatically.
TDQS
Scored across 7 tools
Each tool has a clearly distinct purpose: delegate starts a task, status/review/revise/abort manage sessions, models lists models, and usage reports usage. No two tools overlap in function, making selection unambiguous.
All tools share the 'opencode_' prefix, creating a predictable pattern. However, the second part mixes verbs (delegate, revise, abort) with nouns (status, models, usage), which is a minor inconsistency but still readable and navigable.
With 7 tools, the server is well-scoped for its purpose of routing tasks to OpenCode and managing sessions. Each tool fills a necessary role without redundancy.
The tool surface covers the full session lifecycle: create (delegate), read (status, review), update (revise), and delete (abort). It also includes auxiliary queries (models, usage) that round out the domain without leaving obvious dead ends.