cheerio-mcp-bridges

네 가지 "좁은 도구" MCP 서버로, 터미널 GUI를 조작할 수 없는 orchestrator 에이전트(예: 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. 감사: 각 호출 시 logs/<pi|agy|codex|copilot>-YYYYMMDD.jsonl에 JSONL 한 줄 기록(프롬프트, 세션/스레드 id, 종료 코드, 소요 시간, 사용량).

Related MCP server: mcacp

겪었던 문제들 (실측 기반)

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

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

• codex는 반드시 --skip-git-repo-check를 포함해야 함: cwd가 git 저장소가 아닌 경우(예: 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초가 걸립니다. 타임아웃을 너무 짧게 설정하면 MCP 로딩 단계에서 종료될 수 있습니다.

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

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

  • Copilot: copilot billing / copilot limits는 도움말 주제로, 대화형 모드 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 형식)로 설정합니다. 리프 인증서만이 아닌 CA 중간 인증서(intermediate cert)가 필요합니다.

• 엔터프라이즈급 IP 허용 목록이 CLI 액세스를 차단함(브리지 기본 처리됨): 귀하의 계정이 속한 엔터프라이즈급 요금제(예: GitHub Copilot Enterprise)에서 IP 허용 목록을 활성화한 경우, ask_copilot이 API에 의해 차단될 수 있습니다(오류 메시지는 "enterprise has an IP allow list enabled, and your IP address is not permitted"와 유사). 근본 원인은 일반적으로: 브리지 서버의 부모 프로세스 환경에 HTTP_PROXY/HTTPS_PROXY와 같은 프록시 설정이 있고, 자식 프로세스의 CLI 도구가 이러한 프록시 변수를 상속받아 OAuth 요청이 엔터프라이즈 프록시를 통해 나가게 되며, 프록시의 아웃바운드 IP가 상대방의 허용 목록에 없기 때문입니다. 브리지 v0.2.0부터 기본적으로 자식 프로세스 env에서 프록시 환경 변수를 자동으로 제거합니다(HTTP_PROXY/HTTPS_PROXY/ALL_PROXY 대소문자 변형 포함). 이렇게 하면 CLI가 직접 외부에 연결하여 이 문제를 피할 수 있습니다. 환경이 반대인 경우(프록시를 통해서만 대상 서비스에 연결해야 하는 경우), BRIDGE_BYPASS_PROXY=false로 설정하여 자식 프로세스가 프록시 설정을 상속받도록 되돌릴 수 있습니다.

교차 머신 설치 (처음부터)

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

사전 요구 사항

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

• npm ≥ 9

1단계: Clone 및 설치

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

2단계: 사용 가능한 CLI 확인

npm run doctor

4개의 CLI 각각이 발견되었는지, --version을 정상적으로 실행할 수 있는지, 그리고 어떤 브리지를 활성화할지 권장하는 표가 출력됩니다.

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

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

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

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

예를 들어 pi와 copilot만 설치했다면 pi-bridge와 copilot-bridge 두 블록만 추가하세요.

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

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

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

환경 변수

BRIDGE_BYPASS_PROXY: 브리지는 기본적으로 기본 CLI를 호출하기 전에 자식 프로세스 env에서 HTTP_PROXY/HTTPS_PROXY/ALL_PROXY(대소문자 변형 포함)를 제거하여, 자식 프로세스가 부모 프로세스에서 상속받은 엔터프라이즈 프록시 설정의 영향을 받지 않도록 합니다. 명시적으로 문자열 "false"로 설정된 경우에만 제거 동작이 비활성화됩니다.