OpenCode tools — standalone MCP server

OpenCode's file-editing and execution tools, extracted into an ordinary Node.js MCP server. No OpenCode installation or source checkout, Bun, chat UI, agent loop, model provider or API key is required. The MCP client does the reasoning; this server executes the selected operation.

Version 0.4.0 vendors the relevant tool leaves from OpenCode v1.18.29, commit 16747470f976aca3d362ad730bcd3fe82ecc2c9a (MIT). This is a maintained extraction with explicit adapters, not a claim that the entire OpenCode runtime runs unchanged. See provenance and adaptation notes.

MCP client → stdio / authenticated Streamable HTTP
           → bounded jobs, started immediately
           → Node worker → extracted tools → files / processes / HTTP

There is no opencode serve, OpenCode HTTP client, runtime download, SQLite session database, project plugin loading, model inference, sampling, task/agent delegation, or chat endpoint.

Tools

Tool	Operation
read	Read numbered text, paginated directories, images or PDFs
write	Create or intentionally replace a file
edit	OpenCode's exact/fuzzy string replacement and diff logic
apply_patch	Add, update, delete and move files using OpenCode's patch parser
glob	Find files by glob pattern
grep	Search file contents using ripgrep
bash	Execute a command, returning actual output and exit status
webfetch	Fetch HTTP(S); return text, Markdown, HTML or an image
todowrite	Update a small JSON task list, shared by clients of this server process

Tools retain their OpenCode input shapes where applicable. apply_patch takes patchText. Relative paths resolve inside the configured workspace. bash.timeout is milliseconds; webfetch.timeout is seconds, positive and at most 120. File reads have the original 2,000-line / 50 KiB output window; images/PDFs are limited to 5 MiB. Web response bodies are capped at 5 MiB while streaming.

Install and run

Requirements: Node.js 22+, npm, and ripgrep (rg) for glob/grep. POSIX command execution uses /bin/bash; Windows uses cmd.exe with best-effort process-tree cancellation. CI exercises Linux with Node 22 and 24.

Install ripgrep using your OS package manager (for example, sudo apt-get install ripgrep or brew install ripgrep). The server never downloads executables on startup. Set OPENCODE_MCP_RG to an absolute binary path if it is not on PATH.

git clone https://github.com/nmt3325/opencode-mcp-bridge.git
cd opencode-mcp-bridge
npm ci --ignore-scripts
npm run build

# Use a separate directory for the files you want to edit.
mkdir -p /tmp/toolbox-workspace
OPENCODE_MCP_ROOT=/tmp/toolbox-workspace node dist/index.js

The clone above is this server, not OpenCode. Git is not needed to run a built package. npm pack includes the compiled worker, tool implementations, descriptions, attribution and license; it does not include or fetch an OpenCode workspace.

stdio client configuration

{
  "mcpServers": {
    "opencode-tools": {
      "command": "node",
      "args": ["/opt/opencode-mcp-bridge/dist/index.js"],
      "env": {
        "OPENCODE_MCP_ROOT": "/srv/workspace",
        "OPENCODE_MCP_STATE_DIR": "/var/lib/opencode-mcp"
      }
    }
  }
}

Streamable HTTP

export OPENCODE_MCP_ROOT=/srv/workspace
export OPENCODE_MCP_TOKEN="$(node -e 'console.log(require("crypto").randomBytes(32).toString("hex"))')"
node dist/index.js --http
# /mcp on 127.0.0.1:8787; supply Authorization: Bearer <token>

x-mcp-token is also accepted. Tokens must be at least 24 characters and are compared in constant time. This token is the only gate in front of execution: a client that holds it can read, write and run commands immediately. Browser-Origin requests are rejected. /healthz contains no paths or tool data. Keep the default loopback binding or put the service behind authenticated TLS; never publish it as an unauthenticated command runner. Example configurations are in examples/.

Execution and jobs

There is no pre-execution approval step. Any caller that passes transport authentication can read, write, patch, run shell commands and fetch web resources inside the configured workspace, and the operation starts immediately. Treat the MCP token as equivalent to shell access under the OS account that runs this server.

Two limits are still enforced, without asking anyone:

• Paths are canonicalized and must stay inside OPENCODE_MCP_ROOT. Symlink escapes, the private state directory and the package directory are rejected.
• The external_directory, task and question capabilities are always denied, so no extracted tool can negotiate a way out of the workspace or reach a delegation path.

A tool call can return running. That is not completion and must never cause the caller to execute the operation again.

• opencode_job_result: poll the same job_id (wait_seconds: 0–50).
• opencode_job_cancel: cancel and wait for process cleanup.
• opencode_job_list: inspect retained jobs.
• opencode_native_info: compatibility name; reports implementation: "vendored-tools", pre_execution_approval: false, the source pin and the tool catalog.

Jobs survive HTTP transport reconnects, not a server restart. Commands are never replayed automatically. Shell output uses a bounded preview and saved output file, with a 64 MiB capture ceiling that terminates excessive output. Search subprocess output has an 8 MiB ceiling and a 60-second timeout; refine broad searches if they exceed it. Saved output can be read only through the exact returned path, not by browsing private state directories. Disk outputs remain in the state directory for operator-managed retention; the in-memory job limits do not constitute a disk quota.

Configuration

Variable	Default / purpose
OPENCODE_MCP_ROOT	Required editable directory; DEFAULT_DIRECTORY remains an alias
OPENCODE_MCP_STATE_DIR	Private platform state directory, outside the workspace
OPENCODE_MCP_RG	rg; executable for search tools
OPENCODE_MCP_WAIT_SECONDS	45; initial bounded wait (0–50)
OPENCODE_MCP_JOB_TIMEOUT_SECONDS	600; job limit (5–3600)
OPENCODE_MCP_MAX_JOBS	64; retained jobs (8–256), additionally bounded to 32 MiB in memory
OPENCODE_MCP_MAX_CONCURRENT_JOBS	8; active jobs (1–32, no greater than max jobs)
OPENCODE_MCP_HOST, OPENCODE_MCP_PORT	127.0.0.1, 8787
OPENCODE_MCP_TOKEN	Required for HTTP; at least 24 characters, sent as Authorization: Bearer <token> or x-mcp-token

The package and private state must be outside the editable root; using the filesystem root is forbidden. File operations canonicalize paths and reject symlink escapes. Writes verify file contents/mode again immediately before the same-directory atomic replacement. A changed file causes a conflict instead of silently overwriting someone else's edit. A multi-file patch is not a transaction: all hunks are prevalidated, but an I/O failure/cancellation during application can leave partial changes; inspect files and progress before retrying.

This is not an OS sandbox, and nothing prompts before execution. A shell command started by an authenticated caller can access anything permitted to the OS account that runs this server, including outside the workspace. Untrusted commands require a container/VM, unprivileged account, restricted mounts and network policy. The worker gets a private HOME/XDG/TMP environment and does not inherit model keys, GitHub tokens, SSH agents, MCP tokens or Node/Bun injection flags from the parent. This reduces accidental exposure but does not isolate the executed process from the host filesystem or network.

Migration from 0.3

• Pre-execution approval is gone. OPENCODE_MCP_PERMISSIONS is rejected at startup, so delete it from service units and client configurations.
• opencode_permissions_pending and opencode_permission_reply no longer exist, and no job ever reports awaiting_permission. Clients that branched on that status only need opencode_job_result.
• Transport authentication is unchanged: HTTP still requires OPENCODE_MCP_TOKEN as Authorization: Bearer <token> or x-mcp-token, rejects browser Origins and binds to loopback by default; stdio is still authenticated by process ownership.
• Because nothing is gated interactively any more, the token, the workspace root and the OS account are the controls that matter.

Migration from 0.2

• Delete setup:native / typecheck:native from deployment steps. There is no upstream checkout to provision.
• Remove OPENCODE_MCP_RUNTIME_DIR, OPENCODE_MCP_BUN and --runtime-dir; they are rejected instead of selecting a fallback.
• LSP, formatter, provider/model and shell-backend switches are removed. No tool implicitly loads application configuration, plugins, AGENTS instructions, formatters or language servers.
• Existing TODO/session databases are not imported. Each worker owns a small private JSON task list; no chat history or OpenCode database is opened.
• Job control names and transport behavior are preserved. Shell permission patterns no longer exist; see the 0.3 migration notes above.

Verify and package

npm ci --ignore-scripts
npm test                    # builds and runs real filesystem/process/HTTP/stdio tests
npm run verify:vendor       # provenance hashes and source dependency boundary
npm run test:package        # npm pack → isolated production install → real MCP smoke

The package smoke test disables OpenCode, Bun and Git commands and executes tools using only the installed archive. CI does not install OpenCode or Bun. Tests cover actual edits/diffs, Unicode/BOM/CRLF, ambiguity, patch operations, write-conflict guards, root/symlink restrictions, cancellation/child cleanup, timeouts, bounded output, HTTP authentication, secret stripping and absence of model/plugin execution.

License

This project is MIT. Extracted OpenCode code retains its MIT license, pinned source paths and SHA-256 provenance in UPSTREAM.json.