Codex가 코딩 작업을 OpenCode에 위임할 수 있게 해주는 소규모 로컬 MCP(Model Context Protocol) 서버입니다. 이 서버는 공식 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,
)다음 명령을 셸 없이 실행합니다:
opencode run --format json --dir <working_directory> --auto [--model <model>] [--variant <reasoning_effort>] <task>reasoning_effort는 OpenCode의 공급자별 --variant 옵션에 매핑됩니다. 일반적인 값에는 minimal, low, medium, high, max가 포함되며, 사용 가능한 변형은 선택한 공급자와 모델에 따라 정의됩니다. 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 및 크기가 제한된 통합 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 listOpenCode 데스크톱 애플리케이션과 OpenCode CLI는 Windows에서 별개의 진입점입니다. Windows를 열고 아무것도 출력하지 않는 OpenCode.exe --version 호출은 사용 가능한 CLI가 아닙니다. 필요한 경우 공식 CLI를 설치하세요:
npm install -g opencode-aiopencode가 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.serverOpenCode가 이미 PATH에 있으면 --env 옵션을 생략하세요:
codex mcp add opencode -- C:\path\to\opencode-mcp\.venv\Scripts\python.exe -m opencode_mcp.server그런 다음 등록을 확인하세요:
codex mcp listMCP 구성을 변경한 후 Codex를 다시 시작하세요. 서버는 stdio MCP 서버에 요구되는 대로 프로토콜 메시지만 stdout으로 쓰고 로그는 stderr로 보냅니다.
환경 변수 | 기본값 | 의미 |
|
| 실행 파일 이름 또는 절대 경로 |
|
| 실행 파일 뒤에 삽입되는 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보다 약간 길어야 합니다. 그렇지 않으면 서버가 OpenCode를 종료하고 진단 정보를 반환하기 전에 Codex가 MCP 요청을 취소할 수 있습니다.
opencode_execute는 의도적으로 쓰기 가능하며 잠재적으로 파괴적인 도구입니다. 이 도구는 OpenCode에 이 MCP 서버와 동일한 파일 시스템 및 프로세스 권한을 부여합니다. 구현 내용은 다음과 같습니다:
OpenCode 작업에 셸을 절대 호출하지 않습니다;
기존의 절대 경로 작업 디렉터리를 요구합니다;
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.
