cheerio-mcp-bridges

Четыре «узких инструмента» MCP-сервера, которые позволяют агенту-оркестратору (например, Claude, работающему в Cowork), не имеющему возможности управлять терминальным GUI, запускать четыре установленных и авторизованных локальных CLI для кодинга:

Четыре моста независимы друг от друга, устанавливать все четыре не обязательно. Сначала запустите npm run doctor, чтобы узнать, какие CLI доступны на этой машине, и включите только соответствующие мосты.

Каждый из четырёх серверов предоставляет один, узконаправленный инструмент (не универсальный run_command) — он может только «отправить prompt этому агенту». Остаточный риск заключается в том, что базовый CLI может сделать что угодно после получения prompt, поэтому по умолчанию подход консервативный.

Ключевые моменты дизайна

1. Рабочая директория фиксируется сервером: cwd берётся из переменных окружения (PI_BRIDGE_CWD / AGY_BRIDGE_CWD / CODEX_BRIDGE_CWD / COPILOT_BRIDGE_CWD), вызывающая сторона не может его изменить.

2. Детерминированное продолжение сессии:

   • pi: сервер сам генерирует UUID → --session-id (pi поддерживает «создать, если не существует»), при первом вызове id возвращается; при последующих вызовах с тем же id сессия продолжается, без зависимости от неоднозначной семантики «продолжить последнюю».

   • agy: невозможно предварительно указать id, при первом запуске conversation_id извлекается из --output-format stream-json и возвращается; при последующих вызовах используется --conversation <id>.

   • codex: при первом запуске thread_id извлекается из события thread.started и возвращается; при последующих вызовах используется codex exec resume <id>.

   • copilot: сервер сам генерирует UUID → --session-id, при первом вызове id возвращается; при последующих вызовах с тем же id сессия продолжается.

3. Нулевая инъекция в shell: во всех четырёх случаях shell:false для прямого spawn, prompt передаётся как единственный элемент argv, любые специальные символы shell не интерпретируются.

4. Консервативные флаги разрешений:

   • По умолчанию разрешено чтение и запись файлов (соответствует выбору пользователя), но возможности записи/опасные действия всё равно разделены по уровням.

   • pi по умолчанию не использует доверие к проекту -a (approve_project включает его).

   • agy по умолчанию не использует --dangerously-skip-permissions; чтение/запись в workspace разрешены автоматически, команды shell остаются под контролем, если только не указано dangerously_allow_all:true.

   • codex по умолчанию использует sandbox 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 воспринимают piped stdin как дополнительный контекст, Node spawn по умолчанию оставляет открытый stdin pipe, что заставляет CLI зависать в ожидании EOF. Решение: stdio: ['ignore','pipe','pipe'].

• Расширения pi по умолчанию отключены: интерактивные расширения (например, auto-annotate/plannotator) зависают в headless-режиме (ожидают 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.

• MCP-сервер copilot загружается очень медленно: в неинтерактивном режиме copilot всё равно загружает все MCP-серверы (playwright, notion, tavily и т.д.), только запуск занимает 10–30 секунд. Если таймаут слишком короткий, процесс будет убит на этапе загрузки MCP.

• Автоматическая маршрутизация copilot по умолчанию может упереться в квоту: если не указать модель, hydra router copilot автоматически выберет модель (например, 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-трафика. Это приводит к сбою проверки TLS в Node.js, npm install выдаёт ошибки типа UNABLE_TO_GET_ISSUER_CERT_LOCALLY или certificate chain incomplete. Решение: установить переменную окружения NODE_EXTRA_CA_CERTS, указывающую на полный файл цепочки сертификатов компании (формат PEM), обратите внимание, что нужен промежуточный сертификат CA (intermediate cert), а не только leaf cert.

• Список разрешённых IP-адресов GitHub Copilot Enterprise может блокировать доступ CLI: если в вашей учётной записи GitHub Copilot Enterprise включён список разрешённых IP-адресов, ask_copilot может быть напрямую заблокирован API (сообщение об ошибке примерно такое: "enterprise has an IP allow list enabled, and your IP address is not permitted"). Это совершенно не связано с настройками bridge / MCP, необходимо обратиться к администратору GitHub Enterprise, чтобы узнать, есть ли текущий исходящий IP в белом списке, или нужно ли использовать определённый VPN / корпоративную сеть.

Установка на разных машинах (с нуля)

Четыре моста независимы друг от друга. Сначала запустите npm run doctor, чтобы узнать, какие CLI доступны на этой машине, регистрируйте в настройках MCP-клиента только соответствующие мосты, остальные, которые не установлены, не добавляйте.

Предварительные требования

• Node.js ≥ 18 (требуется поддержка node:test и ES module)

• npm ≥ 9

Шаг 1: Клонирование и установка

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-клиент и отправьте небольшой prompt для тестирования с помощью соответствующего инструмента:

• 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).

Ограничение запроса квоты: в CLI Copilot нет неинтерактивной команды для запроса «оставшейся общей квоты». copilot billing / copilot limits полезны только в интерактивном режиме UI. Мост может сообщить только «сколько потрачено на этот вызов» (usage + текущие quotaSnapshots), но не может сообщить оставшуюся общую квоту. Аналогично для Codex, codex login status показывает только статус входа, без запроса использования.

Переменные окружения