cheerio-mcp-bridges

Cuatro servidores MCP de "herramienta estrecha" que permiten que un agente orquestador que no puede operar una terminal GUI (por ejemplo, Claude ejecutándose en Cowork) pueda impulsar cuatro CLI de codificación instalados y con sesión iniciada localmente:

Los cuatro bridges son independientes entre sí; no es necesario instalar los cuatro. Primero ejecuta npm run doctor para ver qué CLI están disponibles en esta máquina y activa solo el bridge correspondiente.

Cada uno de los cuatro servidores expone una herramienta única y de alcance limitado (no es un run_command genérico): solo puede "enviar un prompt a ese agente". El riesgo residual radica en lo que el CLI subyacente puede hacer por sí mismo al recibir el prompt, por lo que la postura predeterminada es conservadora.

Puntos clave de diseño

1. El directorio de trabajo está 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 del llamador no puede cambiarlo.

2. Continuación de sesión determinista:

   • pi: el servidor genera un UUID → --session-id (pi admite "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; después de la primera ejecución, se extrae de conversation_id en --output-format stream-json y se devuelve; luego se continúa con --conversation <id>.

   • codex: después de la primera ejecución, se extrae de thread_id en el evento thread.started y se devuelve; luego se continúa con codex exec resume <id>.

   • copilot: el servidor genera un UUID → --session-id, la primera llamada devuelve el id; las siguientes usan el mismo id para continuar.

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

4. Banderas de permisos conservadoras:

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

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

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

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

   • copilot solo lleva --allow-all-tools por defecto (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).

Related MCP server: mcacp

Errores encontrados (verificados empíricamente)

• stdin debe cerrarse: los CLI tratan el stdin canalizado como contexto adicional; el spawn de Node deja un pipe de stdin abierto por defecto, lo que hace que el CLI se quede esperando 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 (esperando una UI que nunca aparece). Por lo tanto, se usa --no-extensions por defecto; si es necesario, se activa con enable_extensions:true.

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

• copilot en modo no interactivo debe llevar --allow-all-tools: la documentación indica explícitamente que el modo no interactivo debe llevar esta bandera; de lo contrario, se quedará esperando la confirmación de permisos del usuario. El bridge la incluye por defecto, pero --allow-all (incluye paths + urls) solo se activa con dangerously_allow_all:true.

• La carga del servidor MCP de copilot es lenta: en modo no interactivo, copilot aún carga todos los servidores MCP (playwright, notion, tavily, etc.), y solo el arranque tarda de 10 a 30 segundos. Un timeout demasiado corto hará que el proceso se elimine durante la fase de carga de MCP.

• El auto-routing predeterminado de copilot puede chocar con la cuota: si no se especifica un modelo, el router hydra de copilot selecciona automáticamente un modelo (por ejemplo, gpt-5-mini); si la cuota de ese modelo se agota, fallará directamente. Se recomienda que el llamador especifique explícitamente el modelo.

• Copilot/Codex no pueden consultar la cuota total restante de forma no interactiva:

  • Copilot: copilot billing / copilot limits son temas de ayuda y solo son útiles en la UI del modo interactivo. El CLI no interactivo no tiene comandos como copilot usage. El bridge solo puede obtener la "instantánea de la cuota en el momento del fallo" del evento model.call_failure; no puede consultar el saldo restante de forma proactiva.

  • 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 realiza diagnósticos de instalación. El turn.completed.usage del bridge solo contiene el uso de tokens de esa llamada, sin cuota restante.

• Los proxies de interceptación TLS empresariales 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 de forma intermediaria. 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: establece la variable de entorno NODE_EXTRA_CA_CERTS apuntando al archivo de la cadena de certificados completa de la empresa (formato PEM); ten en cuenta que se necesita el certificado intermedio de la CA, no solo el certificado hoja.

• La lista de permitidos de IP empresarial bloquea el acceso al CLI (el bridge ya lo maneja por defecto): si el plan empresarial de tu cuenta (por ejemplo, GitHub Copilot Enterprise) tiene habilitada la lista de permitidos de IP, ask_copilot puede ser bloqueado por la API (mensaje de error similar a "enterprise has an IP allow list enabled, and your IP address is not permitted"). La causa raíz suele ser: el entorno del proceso padre del servidor bridge tiene configuraciones de proxy como HTTP_PROXY/HTTPS_PROXY; los procesos hijos de los CLI heredan estas variables de proxy, lo que hace que las solicitudes OAuth salgan a través del proxy empresarial, y la IP de salida del proxy no está en la lista de permitidos del destinatario. A partir de v0.2.0, el bridge elimina automáticamente las variables de proxy del entorno de los procesos hijos por defecto (HTTP_PROXY/HTTPS_PROXY/ALL_PROXY, incluidas las variantes de mayúsculas/minúsculas), permitiendo que el CLI se conecte directamente para evitar este problema. Si tu entorno es el contrario (debes pasar por un proxy para alcanzar el servicio de destino), puedes establecer BRIDGE_BYPASS_PROXY=false para que los procesos hijos hereden la configuración de proxy.

Instalación en varias máquinas (desde cero)

Los cuatro bridges son independientes entre sí. Primero ejecuta npm run doctor para ver qué CLI están disponibles en esta máquina y registra solo el bridge correspondiente en la configuración del cliente MCP; no agregues los que no estén instalados.

Requisitos previos

• Node.js ≥ 18 (se requiere soporte para 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

Se mostrará una tabla que indica si se encontraron las 4 CLI, si pueden ejecutar --version correctamente y qué bridges se recomienda activar.

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

A continuación se indican los métodos de instalación e inicio de sesión de cada CLI; si no está instalado, omítelo; no es necesario instalar todos:

pi (earendil-works/pi)

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

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

agy (CLI de Google Antigravity)

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

Verificación: agy --version

codex (CLI de OpenAI Codex)

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

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

copilot (CLI de GitHub Copilot)

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

Verificación: copilot --version

Paso 4: Activar bridges de forma selectiva

Copia la configuración de los bridges que necesites desde mcp-config.example.json a la configuración de tu cliente MCP (por ejemplo, ~/.mcp.json o .mcp.json).

No copies los cuatro. Copia solo los bloques correspondientes a las CLI que estén instaladas y con sesión iniciada en esta máquina, y ajusta las rutas y variables de entorno.

Por ejemplo, si solo tienes instalados pi y copilot, agrega solo los bloques pi-bridge y copilot-bridge.

Paso 5: Verificar que el bridge funciona correctamente

Después de iniciar tu cliente MCP, envía 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ías recibir la respuesta pong y una línea de metadatos del bridge. Si recibes un mensaje de error, verifica:

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

• El CLI ha iniciado sesión

• La variable de entorno del 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 額度）

Registro en el cliente MCP

Consulta mcp-config.example.json. Es un menú: según las CLI que realmente tengas en esta máquina, copia solo los bloques correspondientes a la configuración de tu cliente MCP (.mcp.json) y ajusta las rutas reales. No es necesario copiar los cuatro.

Interfaz de herramientas

ask_pi

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

ask_agy

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

ask_codex

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

ask_copilot

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

Limitación de consulta de cuota: el CLI de Copilot no tiene un comando en modo no interactivo para consultar la "cuota total restante". copilot billing / copilot limits solo son útiles en la UI del modo interactivo. El bridge solo puede informar "cuánto se consumió en esta llamada" (usage + quotaSnapshots de esa llamada), no puede informar la cuota total restante. Lo mismo ocurre con Codex: codex login status solo muestra el estado de inicio de sesión, sin consulta de uso.

Variables de entorno

BRIDGE_BYPASS_PROXY: el bridge elimina por defecto las variables HTTP_PROXY/HTTPS_PROXY/ALL_PROXY (incluidas las variantes de mayúsculas/minúsculas) del entorno de los procesos hijos antes de llamar al CLI subyacente, para evitar que los procesos hijos se vean afectados por la configuración de proxy empresarial heredada del proceso padre. Solo cuando se establece explícitamente la cadena "false" se desactiva el comportamiento de eliminación.