claude-opencode-mcp 1.0.0

package/docs/configuration.md

@@ -0,0 +1,184 @@
+# Configuration
+
+The bridge reads JSON configuration from three layers, later layers overriding
+earlier ones:
+
+1. **Global**: `~/.config/claude-opencode-mcp/config.json`
+   (`XDG_CONFIG_HOME` is honoured)
+2. **Project**: `<workspace>/.claude-opencode/config.json`
+3. **Explicit**: the file named by `CLAUDE_OPENCODE_CONFIG`
+
+Layers are deep-merged, then defaults are applied once. Unknown keys are
+ignored; wrong types produce a `CONFIG_INVALID` error that names the file and
+the offending fields.
+
+## Full reference
+
+```json
+{
+  "opencode": {
+    "url": null,
+    "autoStart": true,
+    "hostname": "127.0.0.1",
+    "port": 0,
+    "startupTimeout": 30000,
+    "binary": null,
+    "username": null,
+    "password": null,
+    "logLevel": null,
+    "maxServers": 4
+  },
+  "workspace": {
+    "allowedRoots": [],
+    "defaultCwd": null
+  },
+  "defaults": {
+    "agent": "deepseek-researcher",
+    "provider": "deepseek",
+    "model": null
+  },
+  "timeouts": {
+    "execution": 600000
+  },
+  "security": {
+    "protectEnvFiles": true,
+    "denyGitPush": true,
+    "denyGitCommit": true,
+    "externalDirectory": "deny",
+    "extraProtectedPatterns": []
+  },
+  "limits": {
+    "summaryChars": 6000,
+    "sessionChars": 20000,
+    "diffChars": 60000
+  },
+  "agents": {
+    "deepseek-coder": {
+      "model": "deepseek/deepseek-v4-pro",
+      "temperature": 0.1
+    }
+  }
+}
+```
+
+### `opencode`
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `url` | `null` | Connect to an existing OpenCode server instead of starting one. |
+| `autoStart` | `true` | Start a headless OpenCode server lazily on first use. |
+| `hostname` | `127.0.0.1` | Bind address for the started server. |
+| `port` | `0` | Port for the started server; `0` picks a free port. |
+| `startupTimeout` | `30000` | Milliseconds to wait for "server listening". |
+| `binary` | `null` | Explicit path to the OpenCode executable. |
+| `username` / `password` | `null` | HTTP basic auth for the server. Falls back to `OPENCODE_SERVER_USERNAME` / `OPENCODE_SERVER_PASSWORD`. |
+| `logLevel` | `null` | `DEBUG`, `INFO`, `WARN` or `ERROR` passed to `opencode serve`. |
+| `maxServers` | `4` | Maximum number of lazily started servers kept alive (LRU eviction of idle servers). |
+
+> **Network exposure:** leave `hostname` at `127.0.0.1`. Binding the OpenCode
+> server to a routable address exposes its HTTP API to your network; if you
+> must, set `OPENCODE_SERVER_PASSWORD` and firewall the port. See
+> [security.md](security.md#network-exposure).
+
+### `workspace`
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `allowedRoots` | `[]` | When non-empty, every workspace must canonicalize inside one of these roots. |
+| `defaultCwd` | `null` | Last-resort workspace when no explicit `cwd`, `CLAUDE_PROJECT_DIR` or process directory is usable. |
+
+### `defaults`
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `agent` | `deepseek-researcher` | Agent used when a tool call omits `agent`. |
+| `provider` | `deepseek` | Provider used to interpret bare model ids. |
+| `model` | `null` | `provider/model` or bare model id; `null` uses the provider's default model from OpenCode. |
+
+### `timeouts`
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `execution` | `600000` | Default per-run timeout in milliseconds. Tools may override with `timeout`. |
+
+### `security`
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `protectEnvFiles` | `true` | Deny `read`/`edit` on `.env*`, keys, credentials and `.ssh/*` (examples stay readable). |
+| `denyGitPush` | `true` | Deny shell commands matching `git push*`. |
+| `denyGitCommit` | `true` | Deny shell commands matching `git commit*`. |
+| `externalDirectory` | `deny` | Policy for paths outside the workspace: `allow`, `ask` or `deny`. `ask` is discouraged in headless mode. |
+| `extraProtectedPatterns` | `[]` | Extra wildcard patterns to deny for read/edit, e.g. `secrets/*`. |
+
+### `limits`
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `summaryChars` | `6000` | Maximum characters of agent output returned from a run. |
+| `sessionChars` | `20000` | Maximum characters of the last summary returned by `get_session`. |
+| `diffChars` | `60000` | Maximum characters returned by `get_diff`. |
+
+### `agents`
+
+Per-agent overrides keyed by agent name:
+
+```json
+{
+  "agents": {
+    "deepseek-coder": {
+      "description": "Custom description",
+      "model": "deepseek/deepseek-v4-pro",
+      "temperature": 0.1,
+      "prompt": "Custom prompt text",
+      "profile": "code",
+      "enabled": true
+    }
+  }
+}
+```
+
+- `profile` selects the permission profile (`read`, `review`, `code`, `test`) —
+  use it when adding a custom agent that is not one of the four built-ins.
+- `enabled: false` removes an agent from `list_agents` and delegation.
+- Project-local markdown files in `.claude-opencode/agents/` take precedence
+  over built-in prompts; config `agents` overrides take precedence over both.
+
+## Connecting to an existing OpenCode server
+
+```json
+{
+  "opencode": {
+    "url": "http://127.0.0.1:4096",
+    "autoStart": false
+  }
+}
+```
+
+Start the server yourself:
+
+```bash
+opencode serve --port 4096
+```
+
+In external-server mode the bridge cannot inject agent definitions or
+permissions. It calls `GET /agent` and refuses to delegate when the four
+required agents are missing (`AGENT_NOT_FOUND`). Install them by copying the
+files from `agents/` into `.opencode/agents/` in the project, or run
+`claude-opencode init` and copy from `.claude-opencode/agents/`.
+
+Credentials in the URL (`http://user:pass@host:port`) or in `username`/`password`
+are sent as HTTP basic auth. Credentials from the environment are only used for
+auto-started servers, never for external URLs.
+
+## Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `OPENCODE_BIN` | Path to the OpenCode executable. |
+| `OPENCODE_SERVER_USERNAME` / `OPENCODE_SERVER_PASSWORD` | Basic auth for started or external servers. |
+| `OPENCODE_CONFIG_CONTENT` | Inherited inline OpenCode config; merged with the bridge's agent definitions. |
+| `CLAUDE_OPENCODE_CONFIG` | Extra config file with highest precedence. |
+| `CLAUDE_OPENCODE_STATE_DIR` | Where sessions and logs are stored. |
+| `CLAUDE_OPENCODE_LOG` | `debug`, `info`, `warn`, `error` or `silent`. |
+| `CLAUDE_PROJECT_DIR` | Set by Claude Code; used as the default workspace. |

package/docs/contributing.md

@@ -0,0 +1,71 @@
+# Contributing
+
+Thanks for helping improve claude-opencode-mcp.
+
+## Ground rules
+
+- Keep the bridge thin. If OpenCode can already do it, the bridge should call
+  OpenCode rather than reimplement it.
+- Never add an `ask` permission rule: the bridge is headless.
+- Never make the bridge write into a user's repository unless the user asks for
+  it (`init` writes only inside `.claude-opencode/`).
+- Do not hard-code provider specifics beyond defaults; providers must stay
+  configurable.
+- Validate against real documentation, not assumptions. Check OpenCode's
+  [server API](https://opencode.ai/docs/server/) and SDK, and this repository's
+  installed `@opencode-ai/sdk` types, before relying on an endpoint.
+
+## Workflow
+
+1. Fork and branch.
+2. `npm install`
+3. Make the change with tests.
+4. Run the full gate:
+
+   ```bash
+   npm run lint
+   npm run typecheck
+   npm test
+   npm run build
+   ```
+
+5. If your change touches the OpenCode integration, run the real E2E suite:
+
+   ```bash
+   CLAUDE_OPENCODE_E2E=1 npm run test:e2e
+   ```
+
+6. Open a pull request describing the problem, the change, and how you
+   verified it.
+
+## Commit style
+
+Conventional-ish and scoped, for example:
+
+```text
+fix(manager): restart OpenCode when the agent config changes
+feat(tools): add timeout override to send_message
+docs(security): document shell write caveat
+```
+
+## Reporting bugs
+
+Include:
+
+- the bridge version (`claude-opencode-mcp --version`),
+- OpenCode version (`opencode --version`),
+- the failing tool call and its JSON error (with `request_id`),
+- relevant `~/.local/state/claude-opencode-mcp/bridge.log` lines.
+
+Never paste API keys or auth files.
+
+## Security issues
+
+Please report privately rather than in a public issue, and avoid sharing live
+credentials. See [security.md](security.md) for the threat model and known
+limits.
+
+## License
+
+By contributing you agree your contributions are licensed under the MIT
+License.

package/docs/deepseek-setup.md

@@ -0,0 +1,84 @@
+# DeepSeek setup
+
+DeepSeek is the default provider, but the bridge is provider-agnostic: the
+provider is just `defaults.provider` in the configuration. Anything OpenCode
+can run works — DeepSeek is only the initial default.
+
+## Authenticate with OpenCode
+
+```bash
+opencode auth login
+# select DeepSeek, paste the API key
+```
+
+This stores the credential in OpenCode's auth store
+(`~/.local/share/opencode/auth.json` by default). The key is never copied into
+the bridge configuration or logs.
+
+## Or use an environment variable
+
+The DeepSeek provider reads `DEEPSEEK_API_KEY`:
+
+```bash
+export DEEPSEEK_API_KEY=sk-...
+```
+
+Export it before starting Claude Code so the spawned OpenCode server inherits
+it.
+
+## Pick a model
+
+```bash
+opencode models | grep deepseek
+# deepseek/deepseek-flash
+# deepseek/deepseek-v4-pro
+```
+
+The bridge resolves models in this order:
+
+1. the `model` argument of `delegate_task` / `create_session`,
+2. the agent's configured model (project agent file or `agents.<name>.model`),
+3. `defaults.model`,
+4. the provider's default model reported by OpenCode
+   (`GET /config/providers`).
+
+To pin one:
+
+```json
+{
+  "defaults": { "provider": "deepseek", "model": "deepseek/deepseek-v4-pro" }
+}
+```
+
+or per agent:
+
+```json
+{
+  "agents": {
+    "deepseek-researcher": { "model": "deepseek/deepseek-flash" },
+    "deepseek-coder": { "model": "deepseek/deepseek-v4-pro" }
+  }
+}
+```
+
+## Using another provider
+
+Set `defaults.provider` and, optionally, `defaults.model`:
+
+```json
+{
+  "defaults": { "provider": "anthropic", "model": "anthropic/claude-sonnet-4-5" }
+}
+```
+
+Agent names keep the `deepseek-` prefix because they describe the role, not the
+provider; rename them with project-local agent files if you prefer.
+
+## Troubleshooting DeepSeek
+
+| Error | Fix |
+| --- | --- |
+| `ProviderAuthError` | `opencode auth login` again, or export `DEEPSEEK_API_KEY`. |
+| `MODEL_NOT_AVAILABLE` | Set `defaults.model`; the provider has no default configured. |
+| Empty/garbled output | Lower `temperature` via an agent override; some models are more literal at `0`. |
+| Rate limits | They surface as `APIError` with `statusCode: 429` and `isRetryable: true`; retry with `send_message` on the same session. |

package/docs/development.md

@@ -0,0 +1,146 @@
+# Development
+
+## Setup
+
+```bash
+git clone <repo>
+cd claude-opencode-mcp
+npm install
+```
+
+`opencode-ai` is an optional dependency, so a local OpenCode binary is usually
+available for end-to-end tests without a global install.
+
+## Scripts
+
+| Command | What it does |
+| --- | --- |
+| `npm run build` | Compile TypeScript to `dist/` (emits the executable). |
+| `npm run typecheck` | `tsc --noEmit` over `src/` and `tests/`. |
+| `npm run lint` | Biome check (lint + format). |
+| `npm run lint:fix` | Biome check with safe fixes. |
+| `npm run format` | Biome format. |
+| `npm test` | Unit + integration tests (no OpenCode needed). |
+| `npm run test:watch` | Vitest in watch mode. |
+| `npm run test:e2e` | Build + real OpenCode/DeepSeek E2E tests (opt-in). |
+| `npm run dev` | Run the MCP server from source with tsx. |
+
+## Test layers
+
+```text
+tests/unit/          pure logic: workspace, config, policy, git, text, agents
+tests/integration/   MCP server + tools against a fake OpenCode HTTP server
+tests/e2e/           real OpenCode + DeepSeek (opt-in)
+```
+
+The integration suite (`tests/helpers/fake-opencode.ts`) implements the v1
+endpoints the bridge uses — health, agents, providers, sessions, messages,
+status, abort, diff, events — so the entire pipeline is exercised
+deterministically in about two seconds.
+
+### Running end-to-end tests
+
+Requirements: an OpenCode binary the bridge can find, and a provider
+authenticated (`opencode auth login`).
+
+```bash
+# checkpoints: workspace isolation, read-only agents, coder edits + diff,
+# session context, abort, stdio MCP server
+npm run test:e2e
+
+# full researcher → coder → reviewer → tester workflow on a generated demo project
+CLAUDE_OPENCODE_E2E_WORKFLOW=1 npm run test:e2e
+
+# override the model used
+CLAUDE_OPENCODE_E2E_MODEL=deepseek/deepseek-flash npm run test:e2e
+```
+
+These tests make real model calls and take tens of seconds to minutes.
+
+## Continuous integration
+
+`.github/workflows/ci.yml` runs on every push and pull request:
+
+- **test** job — Node 20/22/24 on Ubuntu plus Node 24 on macOS: `npm ci`,
+  `npm run lint`, `npm run typecheck`, `npm test`, `npm run build`, an
+  executable smoke test (`--version`, `--help`) and `npm pack --dry-run`.
+- **e2e** job — opt-in and **push-only** (fork PRs never see secrets). Set the
+  repository variable `CLAUDE_OPENCODE_E2E=1` and the secret
+  `OPENCODE_AUTH_JSON` (contents of a valid OpenCode `auth.json`) to run the
+  real DeepSeek checkpoints on Ubuntu.
+
+The `init` integration test adapts when no OpenCode binary is present, so
+`npm test` also passes in environments installed with `--omit=optional`.
+
+## Manual smoke test
+
+```bash
+npm run build
+node dist/index.js init          # in a scratch project
+node dist/index.js --version
+```
+
+Or drive the server with an MCP client:
+
+```bash
+claude mcp add opencode --scope local -- node "$PWD/dist/index.js"
+claude mcp list
+```
+
+## Code layout
+
+See [architecture.md](architecture.md). House rules:
+
+- Relative imports use `.js` extensions (NodeNext ESM).
+- Zod schemas validate every tool input and config layer.
+- All errors are `BridgeError` with a code from `src/errors.ts`.
+- Never write to stdout in the server process: stdout is the MCP transport.
+  Logging goes to stderr and the log file.
+- Tests use temporary directories and never touch the developer's repository.
+
+## Adding a tool
+
+1. Create `src/mcp/tools/<name>.ts` exporting `register<Name>(server, ctx)`.
+2. Define the zod input schema and annotations (`readOnlyHint`, etc.).
+3. Return `jsonResult(...)` on success and `errorResult(error, requestId)` on
+   failure.
+4. Register it in `src/mcp/server.ts`.
+5. Add unit/integration coverage; extend `docs/` and the README table.
+
+## Adding an agent
+
+Add a markdown file under `agents/` and a profile mapping in
+`src/security/policy.ts` if none fits. See
+[agent-configuration.md](agent-configuration.md).
+
+## Release checklist
+
+```bash
+npm run lint && npm run typecheck && npm test && npm run build
+npm run test:e2e                 # requires OpenCode + provider credentials
+CLAUDE_OPENCODE_E2E_WORKFLOW=1 npm run test:e2e
+npm pack --dry-run
+```
+
+Versioning follows [Semantic Versioning](https://semver.org). For a release:
+
+1. Update `CHANGELOG.md` (`Unreleased` → the new version) and bump
+   `package.json` (`npm version <major|minor|patch>` creates the commit and
+   tag).
+2. Verify the packed contents with `npm pack --dry-run` (dist, agents, docs,
+   README, LICENSE, CHANGELOG, SECURITY).
+3. Install and smoke-test the tarball in a scratch directory:
+
+   ```bash
+   npm pack
+   npm install -g ./claude-opencode-mcp-<version>.tgz
+   claude-opencode-mcp --version
+   cd /tmp && claude-opencode init
+   ```
+
+4. Publish: `npm publish --access public` (add `--provenance` when publishing
+   from a GitHub Actions OIDC workflow). Requires npm 2FA.
+5. Push the tag and create the GitHub release from the changelog entry.
+6. Post-release: remove local tarballs and confirm the
+   [CI](https://github.com/putuandy/claude-opencode-mcp/actions) badge is
+   green.

package/docs/installation.md

@@ -0,0 +1,88 @@
+# Installation
+
+## Requirements
+
+- Node.js 20 or newer
+- Claude Code (2.x)
+- OpenCode 1.18 or newer
+- A model provider authenticated in OpenCode (DeepSeek by default)
+
+## Install the bridge
+
+Globally:
+
+```bash
+npm install -g claude-opencode-mcp
+claude-opencode-mcp --version
+```
+
+Or use `npx` in the Claude Code configuration (no global install):
+
+```json
+{
+  "mcpServers": {
+    "opencode": {
+      "command": "npx",
+      "args": ["-y", "claude-opencode-mcp"],
+      "type": "stdio",
+      "timeout": 600000
+    }
+  }
+}
+```
+
+## Install OpenCode
+
+```bash
+npm install -g opencode-ai
+# or
+brew install sst/tap/opencode
+```
+
+Verify:
+
+```bash
+opencode --version
+```
+
+The bridge searches for the executable in this order:
+
+1. `opencode.binary` in the bridge config
+2. the `OPENCODE_BIN` environment variable
+3. `opencode` on `PATH`
+4. `<package>/node_modules/.bin/opencode` (the `opencode-ai` optional dependency)
+5. `~/.opencode/bin/opencode`, `~/.local/bin/opencode`,
+   `/opt/homebrew/bin/opencode`, `/usr/local/bin/opencode`
+
+## Authenticate a provider
+
+```bash
+opencode auth login
+```
+
+Choose DeepSeek and paste an API key. The bridge never stores provider
+credentials; they live in OpenCode's own auth store. See
+[deepseek-setup.md](deepseek-setup.md).
+
+## Validate the project (optional)
+
+```bash
+cd my-project
+claude-opencode init
+```
+
+The command:
+
+- detects the project, git repository, OpenCode, and the DeepSeek provider;
+- validates the workspace against the configured allowed roots;
+- creates `.claude-opencode/config.json` and copies the four agent prompts into
+  `.claude-opencode/agents/`;
+- optionally writes a `.mcp.json` entry with `--write-mcp`.
+
+It never modifies source code and is not required: the bridge works in any
+project directory with no initialization.
+
+## Next steps
+
+- [Claude Code setup](claude-code-setup.md)
+- [Configuration](configuration.md)

package/docs/opencode-setup.md

@@ -0,0 +1,97 @@
+# OpenCode setup
+
+The bridge treats OpenCode as the agent runtime: tools, sessions, permissions,
+LSP and provider execution all come from OpenCode. It does not reimplement any
+of that.
+
+## Install
+
+```bash
+npm install -g opencode-ai
+opencode --version
+```
+
+Other installation methods are listed on
+<https://opencode.ai/docs/>. The bridge also finds a locally installed
+`opencode` in `node_modules/.bin`, so adding `opencode-ai` to a project's
+dependencies works:
+
+```bash
+npm install -D opencode-ai
+```
+
+## How the bridge starts OpenCode
+
+For each workspace, on first use:
+
+1. It resolves the executable (see
+   [configuration.md](configuration.md#environment-variables)).
+2. It starts:
+
+   ```bash
+   opencode serve --hostname=127.0.0.1 --port=0 [--log-level=...]
+   ```
+
+   with the **workspace as the working directory**, and passes the agent
+   definitions and permissions through `OPENCODE_CONFIG_CONTENT`.
+
+3. It waits for `opencode server listening on <url>`, then polls
+   `GET /global/health` until healthy.
+4. The server stays alive for the rest of the session and is reused by every
+   call in that workspace.
+
+Servers are stopped on shutdown (SIGTERM, then SIGKILL after 5 seconds), and a
+crashed server is detected and restarted on the next call. `opencode.maxServers`
+(default 4) bounds how many idle servers are kept alive for multi-project use.
+
+## Permissions from this bridge
+
+The bridge injects four agents (`deepseek-researcher`, `deepseek-reviewer`,
+`deepseek-coder`, `deepseek-tester`) with explicit `permission` rules covering
+every permission key OpenCode supports: `read`, `edit`, `glob`, `grep`, `list`,
+`bash`, `task`, `external_directory`, `todowrite`, `webfetch`, `websearch`,
+`lsp`, `skill`, `question`, `doom_loop`.
+
+Nothing is set to `ask`: the bridge is headless, and an `ask` rule would block a
+run until a human answers. The bridge additionally watches OpenCode's event
+stream and rejects any permission request that still appears, so a run can never
+hang on approval.
+
+If you already run OpenCode with your own global configuration, agent rules from
+the bridge take precedence for these four agents only; everything else in your
+configuration is preserved because inline config is merged, not replaced.
+
+## Connecting to an existing server
+
+```json
+{
+  "opencode": { "url": "http://127.0.0.1:4096", "autoStart": false }
+}
+```
+
+The server must expose the v1 HTTP API (OpenCode 1.18+), and the four agents
+must exist in that server's configuration. `claude-opencode init` writes agent
+files under `.claude-opencode/agents/`; copy them to `.opencode/agents/` in the
+project, or add them to the server's global config, to make them available.
+
+## Authentication for the server itself
+
+If the OpenCode server is protected with HTTP basic auth, set
+`OPENCODE_SERVER_PASSWORD` (and optionally `OPENCODE_SERVER_USERNAME`) or the
+`opencode.username` / `opencode.password` config keys. The bridge sends the
+credentials on every request and passes them to servers it starts itself.
+
+## Multiple workspaces
+
+One server per workspace directory is intentional: project OpenCode
+configuration (`.opencode/`, `opencode.json`, project agents) is loaded
+naturally, and each server's working directory is exactly the delegated
+workspace. Idle servers are evicted LRU when `opencode.maxServers` is exceeded.
+
+## Headless caveats
+
+- The bridge disables `OPENCODE_CLIENT` when spawning the server, so it runs as
+  a plain headless server rather than inheriting desktop/TUI flags.
+- Interactive TUI features (share prompts, dialogs) are not used.
+- Streaming is not consumed from the model; the bridge polls session status and
+  emits MCP progress notifications to Claude Code while waiting.