Skip to content

Commit 2e2a22c

Browse files
committed
docs: document restored MCP server tools
1 parent 7bb8f4e commit 2e2a22c

4 files changed

Lines changed: 36 additions & 20 deletions

File tree

‎AGENTS.md‎

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -25,18 +25,19 @@ Configure after clone: `git config core.hooksPath hooks/`
2525

2626
## Architecture
2727

28-
Claude Code plugin — no MCP server. Core modules:
28+
Claude Code plugin with a bundled MCP server (`.mcp.json` → `dist/index.js`, built from `src/index.ts` with `bun run build`; commit the bundle, CI checks it is current). Core modules:
2929

30-
| File | Role |
31-
| ------------- | ----------------------------------------------------------------------------------------- |
32-
| `config.ts` | Resolve `opencode` binary path, env-based defaults, bool/int helpers |
33-
| `models.ts` | Model listing (cached 5 min), loose-name → provider/model resolution, aggregator priority |
34-
| `opencode.ts` | Spawn `opencode run --format json`, fold JSON event stream into `EventCollector` |
35-
| `delegate.ts` | Build args, git-diff changed-files detection, format outcome |
36-
| `tasks.ts` | In-memory async task store (UUID keys, max 100 finished), prune oldest |
30+
| File | Role |
31+
| ------------- | --------------------------------------------------------------------------------------------------------------------------- |
32+
| `index.ts` | MCP server (stdio): `delegate`, `delegate_async`, `task_result`, `task_list`, `task_cancel`, `list_models`, `list_sessions` |
33+
| `config.ts` | Resolve `opencode` binary path, env-based defaults, bool/int helpers |
34+
| `models.ts` | Model listing (cached 5 min), loose-name → provider/model resolution, aggregator priority |
35+
| `opencode.ts` | Spawn `opencode run --format json`, fold JSON event stream into `EventCollector` |
36+
| `delegate.ts` | Build args, git-diff changed-files detection, format outcome |
37+
| `tasks.ts` | In-memory async task store (UUID keys, max 100 finished), prune oldest |
3738

3839
Tests mirror this structure: `test/models.test.ts` (resolution logic), `test/opencode.test.ts`
39-
(EventCollector + buildArgs). Fixtures are JSONL captured from real `opencode run` sessions.
40+
(EventCollector + buildArgs), `test/mcp-server.test.ts` (spawns the server, checks `tools/list`). Fixtures are JSONL captured from real `opencode run` sessions.
4041

4142
## Gotchas
4243

‎CLAUDE.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,17 +13,18 @@ Bun runs `.ts` directly. Nothing is compiled or bundled (`tsconfig` sets `noEmit
1313

1414
## What actually ships
1515

16-
The plugin's runtime behaviour lives in markdown, not in `src/`:
16+
The plugin's runtime behaviour lives in the markdown files below plus the bundled MCP server:
1717

1818
| Surface | File | Role |
1919
| --------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2020
| Skill | `skills/opencode-delegate/SKILL.md` | Model picking, brief template, review-after-return rules |
2121
| Agent | `agents/opencode-worker.md` | Thin forwarder: one `opencode run` (write: `build --auto`; read: `plan`), report |
2222
| Command | `commands/opencode.md` | `/opencode <model> -- <task>`: splits on `--`, spawns `opencode-worker` |
2323
| Hook | `scripts/route-to-opencode.sh`, `plugin-hooks/hooks.json` | PreToolUse `Agent\|Task`: rewrites only built-in subagent calls (general-purpose, claude, Explore, Plan, claude-code-guide, statusline-setup) to `opencode-worker` on Haiku (Explore/Plan/claude-code-guide forced read-only); custom, plugin, reviewer and SDD agents never routed; pass-through guards: `OPENCODE_DELEGATE_ROUTE=off`, missing opencode, `[no-opencode]`, no `jq` |
24+
| MCP | `.mcp.json`, `src/index.ts`, `dist/index.js` | `opencode` MCP server (stdio, `bun ${CLAUDE_PLUGIN_ROOT}/dist/index.js`) exposing `delegate`, `delegate_async`, `task_result`, `task_list`, `task_cancel`, `list_models`, `list_sessions` to the main thread |
2425
| Manifests | `.claude-plugin/plugin.json`, `marketplace.json` | Plugin identity; `plugin.json` carries homepage/repository shown by Claude Code |
2526

26-
`src/` is a library that no plugin surface imports since the MCP server was removed; only the tests exercise it. Its exports (`delegate`, `resolveModel`, `buildArgs`, `EventCollector`) are the reference for how `opencode run` must be invoked and how its JSON stream is parsed. Changing behaviour in `src/` does NOT change what the plugin does — the markdown files do. `opencode-worker` shells out to `opencode run` itself; keep its command consistent with `buildArgs`.
27+
`src/` backs the MCP server (`src/index.ts`). The installed plugin cache has no `node_modules`, so what runs is the committed bundle `dist/index.js`: changing `src/` changes plugin behaviour only after `bun run build`, and CI fails if `dist/` is stale. Its exports (`delegate`, `resolveModel`, `buildArgs`, `EventCollector`) are also the reference for how `opencode run` must be invoked and how its JSON stream is parsed; `opencode-worker` shells out to `opencode run` itself, so keep its command consistent with `buildArgs`.
2728

2829
- `plugin-hooks/` holds the plugin's Claude Code hooks (registered via the `hooks` field in `plugin.json`); `hooks/` holds this repo's git hooks. Never put `hooks.json` in `hooks/`. The routing script is tested by `test/route-hook.test.ts`.
2930

‎README.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,9 @@ claude ▸ reads git diff, runs tests, reports which model did what and a verdic
1717
| Agent | `agents/opencode-worker.md` | Thin forwarder (`tools: Bash`, `model: haiku`): one `opencode run` |
1818
| Command | `commands/opencode.md` | `/opencode <model> -- <task>`: splits on `--`, spawns `opencode-worker` |
1919
| Hook | `scripts/route-to-opencode.sh` | PreToolUse hook (`plugin-hooks/hooks.json`): reroutes built-in subagent calls to `opencode-worker` |
20+
| MCP | `.mcp.json`, `dist/index.js` | `opencode` MCP server (bundled from `src/index.ts`): `delegate` and friends as main-thread tools |
2021

21-
No MCP server, no build step, no `dist/`. Claude Desktop is not supported.
22+
The MCP server exposes seven tools: `delegate` (run and wait), `delegate_async` (background run, returns a task id), `task_result`, `task_list`, `task_cancel`, `list_models` and `list_sessions`. Claude can call `delegate` directly for implementation work without launching an agent. `dist/index.js` is a committed bundle (the installed plugin cache has no `node_modules`); rebuild it with `bun run build` after changing `src/`, CI fails if it is stale. Claude Desktop is not supported.
2223

2324
## How it works
2425

@@ -134,9 +135,9 @@ git config core.hooksPath hooks/ # pre-commit (staged lint/format), pre-push (
134135
135136
`.prettierignore` excludes local `.atl/`, `openspec/` and `odd/`. Tests are fixture-based and need no running services.
136137
137-
### Library (`src/`)
138+
### MCP server and library (`src/`)
138139
139-
`src/` is a TypeScript library (`delegate`, `resolveModel`, `buildArgs`, `EventCollector`) left from the removed MCP server. No plugin surface imports it; only the tests exercise it, and it is the reference for how `opencode run` is invoked and its JSON stream parsed. Changing it does not change plugin behaviour. Its provider preference (direct provider over an aggregator, `OPENCODE_DELEGATE_PREFERRED_PROVIDERS` first) applies only here, not to the worker. Variables read by `src/config.ts`:
140+
`src/index.ts` is the MCP server entry point (`bun run start`, bundled to `dist/index.js` by `bun run build`); it builds on the `delegate`, `resolveModel`, `buildArgs` and `EventCollector` modules, which also document how `opencode run` is invoked and its JSON stream parsed. Changing `src/` changes the MCP tools, so rebuild and commit `dist/`. The provider preference (direct provider over an aggregator, `OPENCODE_DELEGATE_PREFERRED_PROVIDERS` first) applies to the MCP server only, not to the worker. Variables read by `src/config.ts`:
140141
141142
| Variable | Default | Description |
142143
| --------------------------------------- | ------------------- | ----------------------------------------------------------------- |

‎skills/opencode-delegate/SKILL.md‎

Lines changed: 19 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,16 +5,29 @@ description: Delegate coding or analysis work to another model through OpenCode
55

66
# Delegating to OpenCode models
77

8-
Use the `opencode` slash command (`/opencode <model> -- <task>`) or the `opencode-worker` agent to delegate tasks to an OpenCode model. The delegated model has its own tools (read, edit, shell), so it can implement code, not just answer. **You stay the orchestrator**: you hand over the task, and you review what comes back.
8+
Use the `opencode` MCP tools, the `opencode` slash command (`/opencode <model> -- <task>`) or the `opencode-worker` agent to delegate tasks to an OpenCode model. The delegated model has its own tools (read, edit, shell), so it can implement code, not just answer. **You stay the orchestrator**: you hand over the task, and you review what comes back.
99

1010
## Mechanism
1111

12-
The `opencode-worker` agent is the only mechanism. It is a thin forwarder that runs `opencode run --format json` directly and reports the session id, the reply and the changed files. It does not review, fix or retry.
12+
The `opencode` MCP server runs `opencode run` in the project and returns the reply, session id, token usage and git changes. The `opencode-worker` agent is a thin forwarder that runs `opencode run --format json` directly and reports the same; it does not review, fix or retry.
1313

14-
| Method | When to use |
15-
| ----------------------------- | ------------------------------------------- |
16-
| `/opencode <model> -- <task>` | Simple delegation: spawns `opencode-worker` |
17-
| `opencode-worker` agent | Workflows, parallel fan-out, iteration |
14+
| Method | When to use |
15+
| ----------------------------- | ---------------------------------------------------------- |
16+
| `delegate` MCP tool | Implementation work: call it directly from the main thread |
17+
| `delegate_async` MCP tool | Long tasks or parallel runs; collect with `task_result` |
18+
| `/opencode <model> -- <task>` | Simple delegation: spawns `opencode-worker` |
19+
| `opencode-worker` agent | Workflows, parallel fan-out, iteration |
20+
21+
## Tools
22+
23+
| Tool | Use |
24+
| ------------------------------------------- | --------------------------------------------------------------------------- |
25+
| `list_models` (`filter?`) | Find the exact `provider/model` id. |
26+
| `delegate` | Run a task and wait for the result. |
27+
| `delegate_async` → `task_result` (`wait_s`) | Long tasks, or several models in parallel. Also `task_list`, `task_cancel`. |
28+
| `list_sessions` | Find a `session_id` to continue. |
29+
30+
In a plugin install the tools are named like `mcp__plugin_opencode-delegate_opencode__delegate`. With a manual install they are `mcp__opencode__delegate`. The `prompt` must be a self-contained brief (the model cannot see this conversation); pass `auto: false` for read-only work, `session_id` to continue.
1831

1932
## Modes
2033

0 commit comments

Comments
 (0)