cheerio-mcp-bridges

Cuatro servidores MCP de «herramientas estrechas» que permiten a un agente orquestador que no puede operar una terminal GUI (por ejemplo, Claude ejecutándose en Cowork) impulsar cuatro CLI de codificación instaladas localmente y con sesión iniciada:

Los cuatro puentes son independientes entre sí, no es necesario instalar los cuatro. Primero ejecute npm run doctor para ver qué CLI están disponibles en esta máquina y active solo los puentes correspondientes.

Cada servidor expone una herramienta única y de alcance limitado (no un run_command genérico) — solo puede «enviar un prompt a ese agente». El riesgo residual radica en lo que la CLI subyacente puede hacer al recibir el prompt, por lo que la postura predeterminada es conservadora.

Puntos clave de diseño

1. Directorio de trabajo fijado por el servidor: el cwd proviene de variables de entorno (PI_BRIDGE_CWD / AGY_BRIDGE_CWD / CODEX_BRIDGE_CWD / COPILOT_BRIDGE_CWD), el prompt de la parte llamante no puede cambiarlo.

2. Continuación determinista de sesión:

   • pi: el servidor genera un UUID → --session-id (pi soporta «crear si no existe»), la primera llamada devuelve el id; las siguientes usan el mismo id para continuar, sin depender de la semántica ambigua de «continuar el más reciente».

   • agy: no se puede preespecificar un id, la primera ejecución extrae el conversation_id de --output-format stream-json y lo devuelve; luego se continúa con --conversation <id>.

   • codex: la primera ejecución extrae el thread_id del evento thread.started y lo devuelve; luego se continúa con codex exec resume <id>.

   • copilot: el servidor genera un UUID → --session-id, la primera llamada devuelve el id; luego se continúa con el mismo id.

3. Sin inyección de shell: los cuatro usan shell:false para spawn directo, el prompt se pasa como un solo elemento argv, ningún carácter especial de shell será interpretado.

4. Banderas de permisos conservadoras:

   • Por defecto se permite lectura/escritura de archivos (acorde a la elección del usuario), pero las capacidades de escritura/peligrosas aún se controlan por segmentos.

   • pi por defecto no lleva la confianza de proyecto -a (se activa con approve_project).

   • agy por defecto no lleva --dangerously-skip-permissions; la lectura/escritura del workspace se permite automáticamente, los comandos de shell permanecen controlados, a menos que dangerously_allow_all:true.

   • codex por defecto tiene sandbox en read-only (danger-full-access debe especificarse explícitamente).

   • copilot por defecto solo lleva --allow-all-tools (necesario para no interactivo), no lleva --allow-all (incluye paths + urls), esto último requiere dangerously_allow_all:true.

5. Auditoría: cada llamada escribe una línea JSONL en logs/<pi|agy|codex|copilot>-YYYYMMDD.jsonl (prompt, id de sesión/hilo, código de salida, duración, uso).

Errores encontrados (obtenidos de pruebas reales)

• stdin debe cerrarse: las CLI tratan el stdin canalizado como contexto adicional, Node spawn deja un pipe de stdin abierto por defecto, lo que hace que la CLI se quede esperando un EOF. Solución: stdio: ['ignore','pipe','pipe'].

• Las extensiones de pi están desactivadas por defecto: las extensiones interactivas (como auto-annotate/plannotator) se cuelgan en modo headless (esperan una UI que nunca aparece). Por lo tanto, por defecto se usa --no-extensions, y se activan con enable_extensions:true cuando sea necesario.

• codex debe llevar --skip-git-repo-check: si el cwd no es un repositorio git (por ejemplo, C:/Cheerio), sin esta bandera falla directamente con un error.

• El modo no interactivo de copilot requiere --allow-all-tools: la documentación indica claramente que el modo no interactivo debe llevar esto, de lo contrario se queda esperando la confirmación del usuario. El puente por defecto lleva --allow-all-tools, pero --allow-all (incluye paths + urls) solo se activa con dangerously_allow_all:true.

• El servidor MCP de copilot carga lentamente: incluso en modo no interactivo, copilot carga todos los servidores MCP (playwright, notion, tavily, etc.), solo el inicio toma de 10 a 30 segundos. Si el timeout es demasiado corto, se mata durante la carga de MCP.

• El enrutamiento automático de copilot puede chocar con la cuota: si no se especifica un modelo, el enrutador hydra de copilot selecciona automáticamente un modelo (por ejemplo, gpt-5-mini), y si la cuota de ese modelo se agota, falla directamente. Se recomienda que la parte llamante especifique explícitamente el modelo.

• Copilot/Codex no pueden consultar el saldo restante en modo no interactivo:

  • Copilot: copilot billing / copilot limits son temas de ayuda, solo útiles en la UI del modo interactivo. La CLI no interactiva no tiene un comando como copilot usage. El puente solo puede obtener la «instantánea en el momento del fallo» del evento model.call_failure con quotaSnapshots, no puede consultar el saldo restante activamente.

  • Codex: codex login status solo muestra el método de inicio de sesión (Logged in using ChatGPT), sin consulta de uso/cuota. codex doctor solo hace diagnóstico de instalación. El turn.completed.usage del puente solo tiene el uso de tokens de esa vez, sin saldo restante.

• Los proxies de interceptación TLS a nivel empresarial pueden causar fallos en npm install: algunas organizaciones utilizan proxies de inspección TLS (por ejemplo, soluciones de interceptación de certificados de proveedores de seguridad) para descifrar el tráfico HTTPS mediante intermediarios. Esto hace que la verificación TLS de Node.js falle, y npm install reporte errores como UNABLE_TO_GET_ISSUER_CERT_LOCALLY o certificate chain incomplete. Solución: establecer la variable de entorno NODE_EXTRA_CA_CERTS apuntando al archivo de cadena de certificados completa de la empresa (formato PEM), tenga en cuenta que se necesita el certificado intermedio de la CA, no solo el certificado hoja.

• La lista de IP permitidas de GitHub Copilot Enterprise puede bloquear el acceso de la CLI: si su cuenta de GitHub Copilot Enterprise tiene habilitada la lista de IP permitidas, ask_copilot puede ser bloqueado directamente por la API (mensaje de error similar a «enterprise has an IP allow list enabled, and your IP address is not permitted»). Esto no tiene nada que ver con la configuración del puente/MCP, debe consultar con el administrador de GitHub Enterprise si la IP de salida actual está en la lista blanca, o si es necesario usar una VPN/red corporativa específica.

Instalación entre máquinas (desde cero)

Los cuatro puentes son independientes entre sí. Primero ejecute npm run doctor para ver qué CLI están disponibles en esta máquina, registre solo los puentes correspondientes en la configuración del cliente MCP, no agregue los que no están instalados.

Requisitos previos

• Node.js ≥ 18 (debe soportar node:test y módulos ES)

• npm ≥ 9

Paso 1: Clonar e instalar

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

Paso 2: Verificar qué CLI están disponibles

npm run doctor

Esto generará una tabla que indica si se encontraron las 4 CLI, si pueden ejecutar --version correctamente, y qué puentes se recomienda activar.

Paso 3: Instalar las CLI que necesite (si aún no están instaladas)

A continuación se muestran las formas de instalar e iniciar sesión para cada CLI, si no está instalada, simplemente omítala, no es necesario instalar todas:

pi (earendil-works/pi)

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

Verificación: pi --version o pi --help

agy (Google Antigravity CLI)

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

Verificación: agy --version

codex (OpenAI Codex CLI)

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

Verificación: codex --version, codex login status

copilot (GitHub Copilot CLI)

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

Verificación: copilot --version

Paso 4: Activar los puentes de forma selectiva

Copie la configuración del puente que necesite desde mcp-config.example.json a la configuración de su cliente MCP (por ejemplo, ~/.mcp.json o .mcp.json).

No copie los cuatro. Copie solo los bloques correspondientes a las CLI que tenga instaladas y con sesión iniciada en esta máquina, luego ajuste las rutas y variables de entorno.

Por ejemplo, si solo tiene instalados pi y copilot, agregue solo los bloques pi-bridge y copilot-bridge.

Paso 5: Verificar que el puente funciona correctamente

Después de iniciar su cliente MCP, envíe un prompt muy pequeño con la herramienta correspondiente para probar:

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

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

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

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

Debería recibir una respuesta pong y una línea de metadatos del puente. Si recibe un mensaje de error, verifique:

• La ruta del ejecutable de la CLI (variable de entorno *_BRIDGE_ENTRY) es correcta

• La CLI ha iniciado sesión

• La variable de entorno cwd (*_BRIDGE_CWD) existe

Inicio rápido

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

Registrar en el cliente MCP

Consulte mcp-config.example.json. Es un menú — según las CLI que realmente tenga en esta máquina, seleccione solo los bloques correspondientes y cópielos en la configuración de su cliente MCP (.mcp.json), y ajústelos según las rutas reales. No es necesario copiar los cuatro.

Interfaz de herramientas

ask_pi

Devuelve: texto final de pi + una línea pi-bridge metadata (incluye session_id).

ask_agy

Devuelve: respuesta final de agy + una línea agy-bridge metadata (incluye conversation_id, status).

ask_codex

Devuelve: texto final de Codex + una línea codex-bridge metadata (incluye thread_id, usage).

ask_copilot

Devuelve: respuesta final de Copilot + una línea copilot-bridge metadata (incluye session_id, usage, quota_snapshots).

Limitación de consulta de crédito: la CLI de Copilot no tiene un comando en modo no interactivo para consultar el «saldo total restante». copilot billing / copilot limits solo son útiles en la UI del modo interactivo. El puente solo puede informar «cuánto se consumió en esta llamada» (usage + quotaSnapshots de esa vez), no puede informar el saldo total restante. Codex es similar, codex login status solo muestra el estado de inicio de sesión, sin consulta de uso.

Variables de entorno