Ein kleiner lokaler MCP-Server (Model Context Protocol), mit dem Codex Programmierarbeiten an OpenCode delegieren kann. Er nutzt das offizielle MCP-Python-SDK, den stdio-Transport und einen asynchronen OpenCode-Subprozess.
opencode_executeopencode_execute(
task: str,
working_directory: str,
model: str | None = None,
reasoning_effort: str | None = None,
timeout: int = 1800,
)Führt diesen Befehl ohne Shell aus:
opencode run --format json --dir <working_directory> --auto [--model <model>] [--variant <reasoning_effort>] <task>reasoning_effort wird auf die anbieterspezifische Option --variant von OpenCode abgebildet. Übliche Werte sind minimal, low, medium, high und max, aber die verfügbaren Varianten werden vom ausgewählten Anbieter und Modell bestimmt. Der MCP-Server akzeptiert bewusst jeden nicht‑leeren Wert, statt eine anbieterspezifische Aufzählung zu erzwingen.
Beispiel:
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,
)Er liefert eine strukturierte Ausgabe, die Folgendes enthält:
Erfolg, Timeout, Exit-Code und verstrichene Zeit;
OpenCode-Sitzungs-ID und finale Zusammenfassung des Assistenten;
abgeschlossene OpenCode-Toolaufrufe und Fehler;
begrenzte stdout/stderr-Erfassungen;
abschließend git status --short, git diff --stat und einen begrenzten Unified-Diff.
Die Git-Felder sind Momentaufnahmen nach der Ausführung. Sie können Änderungen enthalten, die bereits vor dem Aufruf vorhanden waren. Textinhalte nicht versionierter Dateien werden als Patches für neue Dateien dargestellt; binäre nicht versionierte Dateien werden mit Pfad und Größe gemeldet.
opencode_checkErmittelt die konfigurierte OpenCode-Programmdatei und führt opencode --version aus, ohne die Umgebung zu verändern.
Related MCP server: BoundedRelay
Voraussetzungen: Python 3.11+, Git (optional für Diff-Berichte) und 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 muss separat installiert und authentifiziert sein. Überprüfen Sie dies zuerst:
opencode --version
opencode auth listDie OpenCode-Desktopanwendung und die OpenCode-CLI sind unter Windows getrennte Einstiegspunkte. Ein Aufruf von OpenCode.exe --version, der die GUI öffnet und nichts ausgibt, ist keine brauchbare CLI. Installieren Sie bei Bedarf die offizielle CLI:
npm install -g opencode-aiWenn opencode nicht im PATH liegt, setzen Sie OPENCODE_MCP_COMMAND auf den absoluten Programmdateipfad. Bei npm-Installationen unter Windows bevorzugen Sie die native Datei unter node_modules\opencode-ai\bin\opencode.exe; der Server erkennt und umgeht den opencode.cmd-Wrapper außerdem automatisch.
Fügen Sie den Server über die Codex-CLI hinzu, um die Konfiguration nicht von Hand bearbeiten zu müssen:
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.serverWenn OpenCode bereits im PATH ist, lassen Sie die Option --env weg:
codex mcp add opencode -- C:\path\to\opencode-mcp\.venv\Scripts\python.exe -m opencode_mcp.serverÜberprüfen Sie anschließend die Registrierung:
codex mcp listStarten Sie Codex nach der Änderung der MCP-Konfiguration neu. Der Server schreibt Protokollmeldungen nur nach stdout und sendet Logs an stderr, wie es für stdio-MCP-Server erforderlich ist.
Umgebungsvariable | Standardwert | Bedeutung |
|
| Name der ausführbaren Datei oder absoluter Pfad |
|
| JSON-Array nach der ausführbaren Datei (nützlich für Wrapper/Tests) |
|
| Fügt das Berechtigungs‑Flag |
|
| Für stdout/stderr getrennt zurückbehaltene Endbytes |
|
| Auf stderr geschriebene Log‑Ebene des Servers |
Wird die automatische Genehmigung deaktiviert, weist OpenCode Berechtigungen ab, die es nicht interaktiv abfragen kann:
$env:OPENCODE_MCP_AUTO_APPROVE = "false"Führen Sie die automatisierten Tests aus:
.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 .Führen Sie den Server unter dem MCP Inspector aus:
uv run --python 3.11 --with-editable ".[dev]" mcp dev src\opencode_mcp\server.pyDer Timeout des MCP-Tools sollte etwas länger sein als der an opencode_execute übergebene timeout; andernfalls könnte Codex die MCP-Anfrage abbrechen, bevor der Server OpenCode beenden und Diagnoseinformationen zurückgeben kann.
opencode_execute ist bewusst ein schreibfähiges, potenziell destruktives Werkzeug. Es gewährt OpenCode dieselben Dateisystem- und Prozessrechte wie diesem MCP-Server. Die Implementierung:
ruft für einen OpenCode-Aufgaben keine Shell auf;
verlangt einen vorhandenen absoluten Arbeitsverzeichnis-Pfad;
begrenzt die erfasste Ausgabe, um den Codex-Kontext zu schützen;
zeigt den OpenCode-Prozessbaum beendet bei Timeout oder MCP-Abbruch;
deaktiviert die automatische OpenCode-Aktualisierung während delegierter Läufe;
markiert das MCP-Tool als nicht idempotent und potenziell destruktiv.
Verwenden Sie beim Delegieren nicht vertrauenswürdiger Aufgaben oder Repositorys ein eingeschränktes Betriebssystemkonto oder eine Sandbox.
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.
