cheerio-mcp-bridges

네 가지 '좁은 도구' MCP 서버로, 터미널 GUI를 조작할 수 없는 오케스트레이터 에이전트(예: Cowork에서 실행되는 Claude)가 로컬에 설치·로그인된 네 가지 코딩 CLI를 구동할 수 있게 합니다:

네 브리지는 서로 독립적이며, 네 개 모두 설치할 필요는 없습니다. 먼저 npm run doctor를 실행하여 이 머신에서 사용 가능한 CLI를 확인하고, 해당하는 브리지만 활성화하세요.

네 서버는 각각 단일·범위 제한적인 도구를 노출합니다(일반적인 run_command 아님) – 단지 "프롬프트를 해당 에이전트에 전송"할 수만 있습니다. 잔여 위험은 하위 CLI가 프롬프트를 수신한 후 자체적으로 무엇을 할 수 있는지에 달려 있으므로, 기본 태세는 다소 보수적입니다.

설계 포인트

1. 작업 디렉토리는 서버가 고정: cwd는 환경 변수(PI_BRIDGE_CWD / AGY_BRIDGE_CWD / CODEX_BRIDGE_CWD / COPILOT_BRIDGE_CWD)에서 가져오며, 호출 측의 프롬프트로 변경할 수 없습니다.

2. 확정적인 세션 이어가기:

   • pi: 서버가 직접 UUID 생성 → --session-id(pi는 '존재하지 않으면 생성' 지원), 첫 번째 호출 시 id 반환; 이후 동일한 id로 이어가며 '가장 최근 세션 이어가기' 같은 모호한 의미에 의존하지 않음.

   • agy: id를 미리 지정할 수 없으며, 첫 실행 후 --output-format stream-json의 conversation_id에서 추출하여 반환; 이후 --conversation <id>로 이어가기.

   • codex: 첫 실행 후 thread.started 이벤트의 thread_id에서 추출하여 반환; 이후 codex exec resume <id>로 이어가기.

   • copilot: 서버가 직접 UUID 생성 → --session-id, 첫 번째 호출 시 id 반환; 이후 동일한 id로 이어가기.

3. 제로 셸 인젝션: 네 서버 모두 shell:false로 직접 spawn하며, 프롬프트는 단일 argv 요소로 전달되므로 셸 특수 문자는 해석되지 않습니다.

4. 보수적인 권한 플래그:

   • 기본적으로 파일 읽기/쓰기 허용(사용자 선택에 부합), 하지만 쓰기/위험한 기능은 여전히 분할 제어.

   • pi는 기본적으로 프로젝트 신뢰 -a를 포함하지 않음(approve_project에서만 활성화).

   • agy는 기본적으로 --dangerously-skip-permissions를 포함하지 않음; 워크스페이스 읽기/쓰기는 자동 허용, 셸 명령어는 게이트 유지, dangerously_allow_all:true인 경우 제외.

   • codex는 기본적으로 샌드박스가 read-only(danger-full-access는 명시적으로 지정 필요).

   • copilot은 기본적으로 --allow-all-tools만 포함(비대화형에 필요), --allow-all(paths + urls 포함)은 포함하지 않으며, 후자는 dangerously_allow_all:true가 필요.

5. 감사: 매 호출마다 JSONL 한 줄을 logs/<pi|agy|codex|copilot>-YYYYMMDD.jsonl에 기록(prompt, session/thread id, exit code, 소요 시간, usage).

경험한 함정(실제 테스트 결과)

• stdin은 반드시 닫아야 함: CLI는 파이프된 stdin을 추가 컨텍스트로 간주하며, Node spawn이 기본적으로 열려 있는 stdin 파이프를 남겨두면 CLI가 EOF를 기다리며 멈춥니다. 해결책: stdio: ['ignore','pipe','pipe'].

• pi extensions 기본 비활성화: 대화형 extension(예: auto-annotate/plannotator)은 헤드리스 모드에서 멈춥니다(절대 나타나지 않는 UI를 기다림). 따라서 기본적으로 --no-extensions를 포함하며, 필요 시 enable_extensions:true로 다시 활성화.

• codex는 반드시 --skip-git-repo-check를 포함해야 함: cwd가 git repo가 아닌 경우(예: C:/Cheerio), 이 플래그 없이 바로 오류를 내며 종료됩니다.

• copilot 비대화형 모드에서는 반드시 --allow-all-tools: 문서에 명시적으로 비대화형 모드에서는 이 플래그가 필요하다고 적혀 있으며, 그렇지 않으면 사용자 권한 확인을 기다리며 멈춥니다. 브리지는 기본적으로 --allow-all-tools를 포함하지만, --allow-all(paths + urls 포함)은 dangerously_allow_all:true인 경우에만 활성화됩니다.

• copilot MCP 서버 로딩이 매우 느림: 비대화형 모드에서도 copilot은 모든 MCP 서버(playwright, notion, tavily 등)를 로드하며, 시작만 해도 10~30초가 걸립니다. timeout을 너무 짧게 설정하면 MCP 로딩 단계에서 kill됩니다.

• copilot 기본 auto-routing이 quota에 걸릴 수 있음: model을 지정하지 않으면 copilot의 hydra 라우터가 자동으로 모델을 선택하며(예: gpt-5-mini), 해당 모델의 할당량이 소진되면 바로 실패합니다. 호출 측에서 명시적으로 model을 지정하는 것이 좋습니다.

• Copilot/Codex 모두 비대화형으로 남은 총 할당량을 조회할 수 없음:

  • Copilot: copilot billing / copilot limits는 help topic으로, 대화형 모드 UI에서만 유용합니다. 비대화형 CLI에는 copilot usage 같은 명령어가 없습니다. 브리지는 model.call_failure 이벤트의 quotaSnapshots에서 '이번 실패 시의 스냅샷'만 얻을 수 있으며, 남은 할당량을 능동적으로 조회할 수 없습니다.

  • Codex: codex login status는 로그인 방식만 표시(Logged in using ChatGPT), 사용량/할당량 조회는 불가. codex doctor는 설치 진단만 수행. 브리지의 turn.completed.usage는 해당 토큰 사용량만 있으며, 남은 할당량은 없습니다.

• 기업용 TLS 차단 프록시로 인해 npm install이 실패할 수 있음: 일부 조직에서는 TLS 검사형 프록시(예: 보안 업체의 인증서 차단 솔루션)를 사용하여 HTTPS 트래픽을 중간자 복호화합니다. 이로 인해 Node.js의 TLS 검증이 실패하여 npm install이 UNABLE_TO_GET_ISSUER_CERT_LOCALLY 또는 certificate chain incomplete 같은 오류를 발생시킵니다. 해결책: 환경 변수 NODE_EXTRA_CA_CERTS를 회사의 전체 인증서 체인 파일(PEM 형식)로 설정합니다. leaf cert뿐만 아니라 CA 중간 인증서(intermediate cert)가 필요합니다.

• GitHub Copilot Enterprise의 IP 허용 목록이 CLI 접근을 차단할 수 있음: GitHub Copilot Enterprise 계정에서 IP 허용 목록이 활성화된 경우, ask_copilot이 API에서 직접 차단될 수 있습니다(오류 메시지: "enterprise has an IP allow list enabled, and your IP address is not permitted"). 이는 브리지/MCP 설정과 전혀 관련이 없으며, GitHub Enterprise 관리자에게 현재 아웃바운드 IP가 허용 목록에 있는지, 또는 특정 VPN/회사 네트워크를 통해서만 사용해야 하는지 확인해야 합니다.

크로스 머신 설치(처음부터 시작)

네 브리지는 서로 독립적입니다. 먼저 npm run doctor를 실행하여 이 머신에서 사용 가능한 CLI를 확인하고, 해당하는 브리지만 MCP 클라이언트 설정에 등록하고, 설치되지 않은 것은 추가하지 마세요.

사전 요구 사항

• Node.js ≥ 18(node:test 및 ES 모듈 지원 필요)

• npm ≥ 9

Step 1: Clone & 설치

git clone https://github.com/CheerioCorner/cheerio-mcp-bridges.git
cd cheerio-mcp-bridges
npm install

Step 2: 사용 가능한 CLI 확인

npm run doctor

출력은 표 형태로, 4개의 CLI 각각이 발견되었는지, --version이 정상 실행되는지, 그리고 어떤 브리지를 활성화할지 권장합니다.

Step 3: 필요한 CLI 설치(아직 설치되지 않은 경우)

각 CLI의 설치 및 로그인 방법은 다음과 같습니다. 설치되지 않은 것은 건너뛰고, 모두 설치할 필요는 없습니다:

pi(earendil-works/pi)

npm install -g @earendil-works/pi-coding-agent
pi   # 首次啟動會引導登入

확인: pi --version 또는 pi --help

agy(Google Antigravity CLI)

# 請參考官方文件安裝，通常是一個獨立執行檔
# https://github.com/nicholasareed/antigravity
agy   # 首次啟動會引導 Google 帳號授權

확인: agy --version

codex(OpenAI Codex CLI)

# 請參考 OpenAI 官方文件安裝
# Windows 通常安裝在 %LOCALAPPDATA%/Programs/OpenAI/Codex/
codex login   # 會引導 ChatGPT 帳號授權

확인: codex --version, codex login status

copilot(GitHub Copilot CLI)

npm install -g @github/copilot-cli
copilot login   # 會引導 GitHub 帳號授權

확인: copilot --version

Step 4: 선택적으로 브리지 활성화

필요한 브리지 설정을 mcp-config.example.json에서 복사하여 MCP 클라이언트 설정(예: ~/.mcp.json 또는 .mcp.json)에 붙여넣습니다.

네 개 모두 복사하지 마세요. 이 머신에 설치되고 로그인된 CLI에 해당하는 블록만 복사하고, 경로와 환경 변수를 조정하세요.

예: pi와 copilot만 설치된 경우, pi-bridge와 copilot-bridge 두 블록만 추가하세요.

Step 5: 브리지 정상 작동 확인

MCP 클라이언트를 시작한 후, 해당 도구로 작은 프롬프트를 전송하여 테스트:

• ask_pi: { "prompt": "Reply only: pong" }

• ask_agy: { "prompt": "Reply only: pong" }

• ask_codex: { "prompt": "Reply only: pong" }

• ask_copilot: { "prompt": "Reply only: pong" }

pong 응답과 함께 브리지 메타데이터 한 줄을 수신해야 합니다. 오류 메시지를 수신하면 다음을 확인:

• CLI 실행 파일 경로(환경 변수 *_BRIDGE_ENTRY)가 올바른지

• CLI가 로그인되었는지

• cwd 환경 변수(*_BRIDGE_CWD)가 존재하는지

빠른 시작

cd C:/Cheerio/Claude/mcp-bridges   # 或你 clone 的路徑
npm install
npm run doctor        # 檢查哪些 CLI 可用
npm test              # 執行 parser/arg-builder 單元測試（不花 API 額度）

MCP 클라이언트에 등록

mcp-config.example.json 참조. 이는 메뉴입니다 – 이 머신에 실제로 있는 CLI에 따라, 해당 블록만 선택하여 MCP 클라이언트 설정(.mcp.json)에 복사하고 실제 경로에 맞게 조정하세요. 네 개 모두 복사할 필요는 없습니다.

도구 인터페이스

ask_pi

반환: pi의 최종 텍스트 + 한 줄 pi-bridge metadata(session_id 포함).

ask_agy

반환: agy의 최종 응답 + 한 줄 agy-bridge metadata(conversation_id, status 포함).

ask_codex

반환: Codex의 최종 텍스트 + 한 줄 codex-bridge metadata(thread_id, usage 포함).

ask_copilot

| 매개변수 | 타입 | 기본값 | 설명 | | ----------------------- | ---------------cription: | ``` prompt | string | — | Copilot에 보낼 명영어(필수) | | session_id | string | 자동 생성 | 이전 반화 값을 전달하면 동일 대하 이어가기 | | model | string | — | model 재정了这个(예: claud-haiku-4.5) | | effort | none|minimal|low|medium|high|xhigh|max | — | 추론 강도 | | max_ai_credits | number | — | 단일 호출 비용 상한(안전 밸브) | | dangerously_allow_all | boolean | false | 위험: --allow-all(paths + urls 포함) 추가 | | timeout_ms | number | 300000 | 하드 타임아웃 |

반환: Copilot의 최종 응답 + 한 줄 copilot-bridge metadata(session_id, usage, quota_snapshots 포함).

할당량 조회 제한: Copilot CLI에는 비대화형 모드에서 '남은 총 할당량'을 조회할 수 있는 명렁어가 없습니다. copilot billing / copilot limits는 대화형 모드 UI에서만 유용합니다. 브리지는 '이 호출에서 얼마나 소모되었는지'만 보고할 수 있으며(usage + quotaSnapshots), 남은 총 할당량을 보고할 수 없습니다. Codex도 마찬가기지입니다. codex login status는 로그인 상태만 표시하며 사용량 젅회는 불가합니다.

환경 번수