cheerio-mcp-bridges

Четыре «узких» MCP-сервера, позволяющие агенту-оркестратору, который не может работать с терминалом GUI (например, Claude, работающий в Cowork), управлять четырьмя локально установленными и авторизованными 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, после первого запуска извлекается из 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, запрос передаётся как один элемент argv, любые специальные символы shell не интерпретируются.

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

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

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

   • agy по умолчанию не использует --dangerously-skip-permissions; чтение/запись в рабочей области разрешены автоматически, команды 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 (запрос, id сессии/потока, код возврата, время выполнения, использование).

Related MCP server: mcacp

Подводные камни, выявленные при тестировании

• stdin должен быть закрыт: CLI воспринимают переданный через stdin контент как дополнительный контекст. Оставленный открытым stdin pipe в Node spawn заставляет 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), а не только конечный сертификат.

• Корпоративный IP allow list блокирует доступ CLI (мост обрабатывает это по умолчанию): если корпоративный план вашей учётной записи (например, GitHub Copilot Enterprise) включает IP allow list, ask_copilot может быть заблокирован API (сообщение об ошибке типа "enterprise has an IP allow list enabled, and your IP address is not permitted"). Коренная причина обычно в том, что окружение родительского процесса моста содержит настройки прокси HTTP_PROXY/HTTPS_PROXY, которые наследуются дочерним процессом CLI, в результате OAuth-запросы идут через корпоративный прокси, а исходящий IP прокси не входит в allow list. Начиная с версии v0.2.0 мост по умолчанию автоматически удаляет переменные прокси из окружения дочернего процесса (HTTP_PROXY/HTTPS_PROXY/ALL_PROXY во всех регистрах), чтобы CLI подключался напрямую и избегал этой проблемы. Если в вашей среде наоборот необходимо проходить через прокси для доступа к целевому сервису, установите BRIDGE_BYPASS_PROXY=false, чтобы вернуть наследование прокси дочерним процессом.

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

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

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

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

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

• 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: мост по умолчанию удаляет переменные HTTP_PROXY/HTTPS_PROXY/ALL_PROXY (во всех регистрах) из окружения дочернего процесса перед вызовом базового CLI, чтобы избежать влияния корпоративных настроек прокси, унаследованных от родительского процесса. Поведение удаления отключается только при явном указании строки "false".