一个本地小型 MCP（模型上下文协议）服务器，让 Codex 将编码工作委托给 OpenCode。它使用官方 MCP Python SDK、stdio 传输，以及一个异步 OpenCode 子进程。
opencode_executeopencode_execute(
task: str,
working_directory: str,
model: str | None = None,
reasoning_effort: str | None = None,
timeout: int = 1800,
)在不使用 shell 的情况下运行此命令：
opencode run --format json --dir <working_directory> --auto [--model <model>] [--variant <reasoning_effort>] <task>reasoning_effort 映射到 OpenCode 中提供商特定的 --variant 选项。常见值包括 minimal、low、medium、high 和 max，但可用的 variant 由所选提供商和模型决定。MCP 服务器有意接受任意非空值，而不是强制使用提供商特定的枚举。
示例：
opencode_execute(
task="Implement uncertainty propagation and run the unit tests.",
working_directory="C:\\path\\to\\NuSR",
model="pinche_10/gpt-5.6-sol",
reasoning_effort="high",
timeout=1800,
)它返回包含以下内容的结构化输出：
成功与否、是否超时、退出代码和耗时；
OpenCode 会话 ID 和最终助手摘要；
已完成的 OpenCode 工具调用及错误；
有上限的 stdout/stderr 捕获结果；
最终的 git status --short、git diff --stat，以及有上限的 unified diff。
这些 Git 字段是运行后的快照。它们可能包含调用之前就已存在的更改。未跟踪文件的文本内容会以新文件补丁的形式呈现；未跟踪的二进制文件则会按路径和大小报告。
opencode_check确定已配置的 OpenCode 可执行文件，然后运行 opencode --version，且不修改环境。
Related MCP server: BoundedRelay
要求：Python 3.11+、Git（用于 diff 报告，可选）以及 OpenCode。
git clone https://github.com/TAO-MINGYU/codex_to_opencode.git
cd codex_to_opencode
uv venv --python 3.11 .venv
uv pip install --python .venv\Scripts\python.exe -e ".[dev]"OpenCode 必须单独安装并完成身份验证。请先验证：
opencode --version
opencode auth list在 Windows 上，OpenCode 桌面应用和 OpenCode CLI 是两个独立的入口点。调用 OpenCode.exe --version 只会打开 GUI 而不打印任何内容，不算是可用的 CLI。需要时请安装官方 CLI：
npm install -g opencode-ai如果 opencode 不在 PATH 中，请将 OPENCODE_MCP_COMMAND 设置为其可执行文件的绝对路径。在 Windows 的 npm 安装中，优先使用 node_modules\opencode-ai\bin\opencode.exe 下的原生二进制；服务器也会自动检测并跳过 opencode.cmd 包装器。
通过 Codex CLI 添加服务器，从而避免手动编辑配置：
codex mcp add opencode --env OPENCODE_MCP_COMMAND=C:\path\to\opencode.exe -- C:\path\to\opencode-mcp\.venv\Scripts\python.exe -m opencode_mcp.server当 OpenCode 已在 PATH 中时，省略 --env 选项：
codex mcp add opencode -- C:\path\to\opencode-mcp\.venv\Scripts\python.exe -m opencode_mcp.server然后验证注册：
codex mcp list更改 MCP 配置后重启 Codex。服务器只将协议消息写入 stdout，并将日志发送到 stderr，这正是 stdio MCP 服务器的要求。
环境变量 | 默认值 | 含义 |
|
| 可执行文件名或绝对路径 |
|
| 在可执行文件之后插入的 JSON 数组（用于包装器/测试） |
|
| 添加 OpenCode 的 |
|
| 分别保留的 stdout/stderr 尾部字节数 |
|
| 写入 stderr 的服务器日志级别 |
将自动批准设为 false 会让 OpenCode 拒绝无法交互式请求的权限：
$env:OPENCODE_MCP_AUTO_APPROVE = "false"运行自动化测试：
.venv\Scripts\python.exe -m pytest --cov=opencode_mcp --cov-fail-under=80
.venv\Scripts\python.exe -m ruff check .
.venv\Scripts\python.exe -m ruff format --check .在 MCP Inspector 下运行服务器：
uv run --python 3.11 --with-editable ".[dev]" mcp dev src\opencode_mcp\server.pyMCP 工具的超时时间应略长于传给 opencode_execute 的 timeout；否则 Codex 可能会在服务器终止 OpenCode 并返回诊断信息之前取消 MCP 请求。
opencode_execute 是一个可写、可能具有破坏性的工具。它授予 OpenCode 与本 MCP 服务器相同的文件系统和进程权限。其实现：
绝不会为 OpenCode 任务调用 shell；
要求提供已存在的绝对工作目录路径；
限制捕获的输出，以保护 Codex 上下文；
在超时或 MCP 取消时终止 OpenCode 进程树；
在委托运行期间禁用 OpenCode 自动更新；
将该 MCP 工具标记为不可幂等且可能具有破坏性。
在委托不受信任的任务或仓库时，请使用受限的 OS 账户或沙箱。
Resolve the configured OpenCode executable and report its version.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| error | Yes | |
| command | Yes | |
| version | Yes | |
| available | Yes | |
| resolved_executable | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds behavioral detail beyond those annotations by stating the tool resolves a configured executable, which implies reading configuration and locating a binary. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence states the key action and outcome, with no filler or redundant detail. Every word earns its space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no parameters, a complete annotation set, and an output schema, so the description only needs to convey the high-level purpose and behavior. It does so completely for this simple check operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the baseline is 4. The description does not need to explain any parameters, and the schema fully covers them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb-resource pair: 'Resolve the configured OpenCode executable and report its version.' It clearly identifies both the action and the subject, and the title reinforces the purpose. It is also easily distinguishable from the sibling tool opencode_execute, which implies running commands rather than checking the installation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a clear context: this is a verification or preflight check of the local OpenCode installation, distinct from execution. While it does not explicitly cite when-or-when-not to use it relative to opencode_execute, the 'check' framing and resolved-executable behavior provide clear usage context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delegate one repository coding task to OpenCode.
OpenCode runs non-interactively in the supplied directory, may read and modify files, execute terminal commands, run tests, and use Git. The result contains OpenCode's final text, observed tool calls, diagnostics, and the final Git working-tree diff. The Git diff is a post-run snapshot and can include changes that existed before this call.
| Name | Required | Description | Default |
|---|---|---|---|
| task | Yes | Complete coding task and acceptance criteria for OpenCode. | |
| model | No | Optional OpenCode model in provider/model form; omit for its configured default. | |
| timeout | No | Maximum execution time in seconds (default 1800). | |
| reasoning_effort | No | Optional provider-specific reasoning effort passed to OpenCode as --variant, for example minimal, low, medium, high, or max. | |
| working_directory | Yes | Absolute path to the existing project directory OpenCode may modify. |
| Name | Required | Description |
|---|---|---|
| model | Yes | |
| errors | Yes | |
| stderr | Yes | |
| stdout | Yes | |
| success | Yes | |
| summary | Yes | |
| git_diff | Yes | |
| exit_code | Yes | |
| timed_out | Yes | |
| git_status | Yes | |
| session_id | Yes | |
| git_diff_stat | Yes | |
| elapsed_seconds | Yes | |
| output_truncated | Yes | |
| reasoning_effort | Yes | |
| tool_invocations | Yes | |
| working_directory | Yes | |
| git_diff_truncated | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavior over the annotations (destructiveHint=true, readOnlyHint=false) by disclosing non-interactive execution, possible file modifications, CLI/Git actions, and execution of tests. It also warns that the returned Git diff is a post-run snapshot and may include pre-existing changes. This is useful, though it does not enumerate every destructive action or limitation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is focused: one purpose-driven opening sentence followed by a terse but information-dense paragraph about behavior and result shape. Every sentence earns its place, including the important Git-diff caveat. The length is appropriate for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a complete input schema and an output schema present, the description covers the main operational ambiguity: non-interactive execution, mutation of files, and the non-isolated nature of the Git diff. It is mostly complete, but it leaves the distinction versus opencode_check unstated, and it does not describe interaction between the timeout/model parameters and the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameter descriptions in the schema already carry the meaning for task, working_directory, model, timeout, and reasoning_effort. The tool description does not add extra parameter syntax, examples, or semantic clarifications beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description immediately states a specific operation: delegating one repository coding task to OpenCode, and enumerates what the tool can do (read/modify files, run commands, tests, Git). It is clear, but it does not explicitly contrast with the sibling tool opencode_check, so it stops short of full differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The first sentence implies the usage: delegate a coding task to OpenCode. The description also clarifies that it runs non-interactively in a repository, which helps the agent set expectations. However, there is no explicit 'when not to use' or comparison with the sibling opencode_check; usage guidance is present but largely implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0opencode_checkopencode_executeScored across 2 tools
The two tools have clearly distinct roles: opencode_execute delegates a coding task, while opencode_check resolves the executable and reports its version. There is no realistic confusion between performing an action and checking the installation.
Both tools use the same opencode_ prefix followed by a concise imperative verb, maintaining a consistent snake_case pattern. Though the prefix is a product name, the convention is uniform and predictable.
Two tools is at the low end of typical server scope and feels thin for a coding integration. However, the narrow focus on delegating a single task plus a health check is reasonable enough to be borderline appropriate.
The server covers its core purpose: opencode_execute handles task delegation, and opencode_check verifies the underlying executable. Obvious lifecycle tools such as cancellation or querying current task status are absent, but they fall outside the stated minimal purpose.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Source-checked CLI guides and model-aware planning for Claude Code, Codex, and Grok Build.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
