Codex용 OpenCode MCP 서버

Codex가 코딩 작업을 OpenCode에 위임할 수 있게 해주는 소규모 로컬 MCP(Model Context Protocol) 서버입니다. 이 서버는 공식 MCP Python SDK, stdio 전송, 그리고 비동기 OpenCode 하위 프로세스를 사용합니다.

도구

opencode_execute

opencode_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: Claude Code Manager WAN

설치

요구 사항: 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

OpenCode 데스크톱 애플리케이션과 OpenCode CLI는 Windows에서 별개의 진입점입니다. Windows를 열고 아무것도 출력하지 않는 OpenCode.exe --version 호출은 사용 가능한 CLI가 아닙니다. 필요한 경우 공식 CLI를 설치하세요:

npm install -g opencode-ai

opencode가 PATH에 없으면 OPENCODE_MCP_COMMAND를 실행 파일의 절대 경로로 설정하세요. Windows의 npm 설치에서는 node_modules\opencode-ai\bin\opencode.exe 아래의 네이티브 바이너리를 권장합니다. 서버는 opencode.cmd 래퍼도 자동으로 감지하여 우회합니다.

Codex 연결

구성을 수동으로 편집하지 않도록 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를 다시 시작하세요. 서버는 stdio MCP 서버에 요구되는 대로 프로토콜 메시지만 stdout으로 쓰고 로그는 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.py

MCP 도구 타임아웃은 opencode_execute에 전달되는 timeout보다 약간 길어야 합니다. 그렇지 않으면 서버가 OpenCode를 종료하고 진단 정보를 반환하기 전에 Codex가 MCP 요청을 취소할 수 있습니다.

보안 모델

opencode_execute는 의도적으로 쓰기 가능하며 잠재적으로 파괴적인 도구입니다. 이 도구는 OpenCode에 이 MCP 서버와 동일한 파일 시스템 및 프로세스 권한을 부여합니다. 구현 내용은 다음과 같습니다:

• OpenCode 작업에 셸을 절대 호출하지 않습니다;

• 기존의 절대 경로 작업 디렉터리를 요구합니다;

• Codex 컨텍스트를 보호하기 위해 캡처된 출력 크기를 제한합니다;

• 타임아웃 또는 MCP 취소 시 OpenCode 프로세스 트리를 종료합니다;

• 위임된 실행 중 OpenCode 자동 업데이트를 비활성화합니다;

• MCP 도구를 비멱등하고 잠재적으로 파괴적인 것으로 표시합니다.

신뢰할 수 없는 작업이나 리포지토리를 위임할 때는 제한된 OS 계정이나 샌드박스를 사용하세요.