codex-gemini-mcp-sample

codex-gemini-mcp-sample

간결한 TypeScript MCP 서버 예제입니다.

• MCP tool ask_codex: 로컬 codex CLI에 프롬프트 전달
• MCP tool ask_gemini: 로컬 gemini CLI에 프롬프트 전달
• MCP background tools: wait_for_job, check_job_status, kill_job, list_jobs
• stdio transport 기반으로 동작
• 현재 Phase C 1차 구현 완료 (background 실행 + job 상태 파일 추적)

MCP_REVERSE_ENGINEERING.md는 참고용이며, 이 샘플은 의도적으로 기능을 최소화했습니다.

Requirements

• Node.js 20+
• codex CLI 설치 (npm i -g @openai/codex)
• gemini CLI 설치 (npm i -g @google/gemini-cli)

Quick Start

npm install
npm run build
npm run start:codex
npm run start:gemini

개발 모드:

npm run dev:codex
npm run dev:gemini

Example .mcp.json

{
  "mcpServers": {
    "codex-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/codex-gemini-mcp/dist/mcp/codex-stdio-entry.js"]
    },
    "gemini-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/codex-gemini-mcp/dist/mcp/gemini-stdio-entry.js"]
    }
  }
}

Tool Schemas

ask_codex

• prompt (string, required)
• model (string, optional)
• timeout_ms (number, optional, default 600000)
  • long-running task는 300000 이상(5분 이상) 권장
• working_directory (string, optional)
• background (boolean, optional, default false)
• reasoning_effort (string, optional: minimal | low | medium | high | xhigh)

ask_gemini

• prompt (string, required)
• model (string, optional)
• timeout_ms (number, optional, default 600000)
  • long-running task는 300000 이상(5분 이상) 권장
• working_directory (string, optional)
• background (boolean, optional, default false)

wait_for_job

• job_id (string, required)
• timeout_ms (number, optional, default 3600000, max 3600000)

check_job_status

• job_id (string, required)

kill_job

• job_id (string, required)
• signal (string, optional: SIGTERM | SIGINT, default SIGTERM)

list_jobs

• status_filter (string, optional: active | completed | failed | all, default active)
• limit (number, optional, default 50)

Runtime Notes

• ask_codex: codex exec --ephemeral 호출
• ask_gemini: gemini --prompt <text> 호출
• background: true 호출 시 .codex-gemini-mcp/jobs, .codex-gemini-mcp/prompts에 상태/입출력 파일 저장
• 모델 선택 우선순위: request.model > env default > hardcoded default
  • codex env: MCP_CODEX_DEFAULT_MODEL (기본값: gpt-5.3-codex)
  • gemini env: MCP_GEMINI_DEFAULT_MODEL (기본값: gemini-3-pro-preview)
• timeout_ms 미지정 시 기본값은 MCP_CLI_TIMEOUT_MS 또는 600000ms(10분)

Environment Variables

• MCP_CODEX_DEFAULT_MODEL: codex 기본 모델
• MCP_GEMINI_DEFAULT_MODEL: gemini 기본 모델
• MCP_CLI_TIMEOUT_MS: 기본 CLI timeout(ms)
• MCP_MAX_OUTPUT_BYTES: 최대 출력 바이트(cap, 향후 runtime 확장용)
• MCP_RUNTIME_DIR: 런타임 파일 기본 루트(.codex-gemini-mcp)
• MCP_LOG_DIR: 로그 경로 override
• MCP_LOG_PREVIEW: 로그 preview 저장 여부 (1이면 활성화)
• MCP_LOG_FULL_TEXT: 전체 텍스트 로그 여부 (1이면 활성화)

Current Status

• MCP 등록 엔트리: dist/mcp/codex-stdio-entry.js, dist/mcp/gemini-stdio-entry.js
• 검증 완료: ask_codex, ask_gemini foreground/background 실호출 성공
• 검증 완료: wait_for_job, check_job_status, kill_job, list_jobs 실호출 성공
• 미구현: 구조화 로깅(Phase D), 안정성 강화(Phase E)

Scope (deliberately minimal)

이 샘플에는 아래 기능이 없습니다:

• 구조화 JSONL 로깅
• 모델 fallback chain
• model name regex 검증/표준 에러코드 체계
• standalone bridge 번들링