Codex Supervisor MCP

Локальный мост на основе Model Context Protocol (MCP), позволяющий совместимому хосту запускать, отслеживать, направлять, прерывать, возобновлять и одобрять работу Codex app-server.

Он оборачивает codex app-server; он не автоматизирует терминальный интерфейс и не извлекает данные из IDE.

Возможности

Сервер предоставляет следующие MCP-инструменты:

Related MCP server: Codex Bridge MCP

Требования

• Node.js 22 или новее.

• Актуальный Codex CLI, доступный как codex.

• Аутентификация Codex CLI уже настроена.

• Один или несколько явных локальных корней репозиториев.

Этот проект не имеет npm-зависимостей времени выполнения.

Проверка пакета

npm test

Тестовый набор использует совместимый с протоколом имитатор app-server. Он не выполняет запросы к модели и не требует аутентификации Codex.

Установка с помощью Codex CLI

Используйте имя MCP-сервера codex-supervisor. Имя должно совпадать с CODEX_SUPERVISOR_MCP_NAME; мост использует его, чтобы дочерний app-server не загружал этот же MCP-сервер рекурсивно.

macOS или Linux

codex mcp add codex-supervisor \
  --env CODEX_ALLOWED_ROOTS="/Users/you/code:/Users/you/work" \
  --env CODEX_SUPERVISOR_MCP_NAME="codex-supervisor" \
  -- node "/absolute/path/to/codex-supervisor-mcp/src/index.mjs"

Используйте разделитель списка путей платформы между корнями. На macOS и Linux это двоеточие (:).

Windows PowerShell

codex mcp add codex-supervisor `
  --env CODEX_ALLOWED_ROOTS="C:\src;D:\work" `
  --env CODEX_SUPERVISOR_MCP_NAME="codex-supervisor" `
  -- node "C:\absolute\path\to\codex-supervisor-mcp\src\index.mjs"

В Windows разделитель списка путей — точка с запятой (;).

Подтвердите регистрацию:

codex mcp list

В Codex введите /mcp, чтобы проверить подключённый сервер.

Установка с помощью config.toml

Скопируйте и адаптируйте examples/config.toml, затем поместите его содержимое в ~/.codex/config.toml или в .codex/config.toml доверенного проекта.

Используйте абсолютные пути. Сохраняйте идентификатор сервера и CODEX_SUPERVISOR_MCP_NAME одинаковыми.

ChatGPT desktop или расширение Codex IDE

1. Откройте Settings → MCP servers → Add server.

2. Установите имя codex-supervisor.

3. Выберите STDIO.

4. Установите команду node.

5. Добавьте абсолютный путь к src/index.mjs как единственный аргумент.

6. Добавьте CODEX_ALLOWED_ROOTS и CODEX_SUPERVISOR_MCP_NAME=codex-supervisor.

7. Сохраните и перезапустите хост.

8. Введите /mcp, чтобы проверить инструменты.

Локальные STDIO MCP-серверы не загружаются обычными веб-чатами ChatGPT. Использование этого моста из веба требует отдельно развёрнутого, аутентифицированного удалённого MCP-сервиса или размещённого плагина.

Типичный рабочий процесс

Попросите MCP-хост:

Use codex_start in /absolute/path/to/repository to implement the requested
change. Use workspaceWrite, keep network access disabled, wait for progress,
show me every approval request before resolving it, and report the final diff
and test result.

Хост должен следовать этой последовательности:

codex_start -> codex_wait
  approval request -> inspect -> codex_resolve_approval -> codex_wait
  active correction -> codex_steer -> codex_wait
  completed -> codex_status
  later follow-up -> codex_send -> codex_wait

Каждый вызов start/send/steer/interrupt возвращает eventCursor. Передавайте его как afterSequence в codex_wait или codex_status, чтобы избежать повторного воспроизведения старых событий.

approvalPolicy принимает текущие wire-значения app-server: on-request (по умолчанию) и untrusted. Устаревшие значения onRequest и unlessTrusted принимаются мостом и нормализуются перед запросом к app-server.

Публичный API одобрений принимает decline, даже если релиз Codex app-server для этого запроса объявляет только cancel. В этом случае мост использует безопасный ответ отмены app-server и сообщает и запрошенное, и фактическое решения.

Конфигурация

Аргументы app-server по умолчанию эквивалентны:

-c mcp_servers.<CODEX_SUPERVISOR_MCP_NAME>.enabled=false app-server

Переопределение CODEX_APP_SERVER_ARGS убирает эту защиту от рекурсии. Добавьте эквивалентное отключающее переопределение самостоятельно.

Модель безопасности

• CODEX_ALLOWED_ROOTS обязателен.

• Пути канонизируются с помощью realpath; выходы через симлинки отклоняются.

• Codex получает ограниченный доступ на чтение к выбранному репозиторию и платформенным значениям по умолчанию.

• workspaceWrite ограничивает корни для записи выбранным репозиторием.

• dangerFullAccess не предоставляется.

• Сетевой доступ требует и CODEX_ALLOW_NETWORK=1, и networkAccess: true в задаче.

• У моста нет универсального, неизолированного shell-инструмента.

• Одобрения на выполнение команд и изменение файлов должны разрешаться явно.

• Потоки вне разрешённых корней отклоняются или фильтруются.

• Полезные нагрузки событий ограничены по размеру перед хранением.

• Сохранённые пути потоков повторно канонизируются при использовании; удалённые или заменённые пути репозиториев закрываются отказом.

• Мутации в одном потоке, ответы на одобрения и повторные удалённые вызовы сериализуются или дедуплицируются, а не выполняются дважды.

• Транспортные ошибки рекурсивно редактируются и ограничиваются по размеру перед пересечением границ STDIO или HTTP.

• Учётные данные ретранслятора и удалённого сервера (BIOTELE_* и CODEX_REMOTE_*) удаляются из среды дочернего Codex.

• Удалённые отправки результатов аутентифицируются через HMAC, кодируются base64url, разбиваются на ограниченные фрагменты и проверяются по длине и SHA-256 перед использованием. Кодирование защищает транспорт от контентных фильтров; это не шифрование.

Дочерний app-server по-прежнему наследует настройки процесса, не относящиеся к ретранслятору, и вашу более широкую конфигурацию Codex. Проверьте прочие секреты среды, приложения, навыки, хуки и настроенные MCP-серверы перед использованием с недоверенным кодом. Очистка окружения не является границей безопасности операционной системы: дочерний процесс, работающий от того же пользователя Windows, может намеренно запрашивать настройки уровня пользователя. Используйте отдельную учётную запись Windows, если такая угроза входит в область риска.

Поддерживаемые запросы одобрений

Этот релиз разрешает:

• item/commandExecution/requestApproval

• item/fileChange/requestApproval

Прочие запросы app-server остаются видимыми через codex_status и codex_list_approvals, но мост отказывается отвечать на них. Это предотвращает возможность молчаливого предоставления разрешений или передачи чувствительных пользовательских данных через универсальную конечную точку ответов.

Сохранение и мониторинг

Codex владеет сохранённой историей потоков. Мост хранит в памяти буферы потоковых событий, последние дельты и состояние ожидающих запросов. Перезапуск MCP-сервера очищает это временное состояние, но codex_list_threads и codex_read_thread могут восстановить авторизованные сохранённые потоки.

Разработка

npm test
node --check src/index.mjs

Структура проекта:

src/app-server-client.mjs  Codex app-server JSONL client
src/approval-policy.mjs    Approval-policy validation and legacy normalization
src/event-store.mjs        Bounded event, turn, and approval state
src/security.mjs           Repository-root policy
src/supervisor-service.mjs Codex lifecycle orchestration
src/tool-registry.mjs      MCP tool schemas and validation
src/mcp-server.mjs         Dual-era MCP STDIO transport
src/index.mjs              Entrypoint
test/                      Unit and integration tests

Лицензия

MIT

Совместимость с Codex App Server

Версия 1.0.3 удаляет устаревшие поля readOnly.access и workspaceWrite.readOnlyAccess из turn/start. Текущие релизы Codex App Server используют профили разрешений, когда клиенту нужны пользовательские ограниченные области чтения. Супервизор продолжает ограничивать корни для записи выбранным репозиторием и проверяет каждый каталог задачи на соответствие CODEX_ALLOWED_ROOTS.

Удалённый ретранслятор Hostinger

Версия 1.2.5 предоставляет совместимый с Hostinger ретранслятор для удалённого MCP-доступа ChatGPT:

ChatGPT -> OAuth bearer JWT -> Hostinger /mcp -> namespace-routed queue
  codex_*  -> outbound Windows local-agent -> Codex app-server
  reeves_* -> outbound Reeves Android agent -> accessibility service

Публичная конечная точка /mcp проверяет RS256 OAuth-токены доступа от внешнего поставщика идентификации. Агенты Windows и Reeves используют независимые HMAC- учётные данные только для исходящего опроса, статуса, получения аренды и отправки результатов. Ретранслятор Hostinger никогда не запускает Codex и не читает локальные репозитории.

Размещённый ретранслятор сохраняет все существующие инструменты codex_* и дополнительно предоставляет reeves_status, reeves_tap, reeves_swipe, reeves_type, reeves_back, reeves_home, reeves_recents, reeves_sequence и reeves_screenshot. Локальный реестр STDIO Codex остаётся только для Codex. Заявки агентов фильтруются по аутентифицированному идентификатору ключа; поля маршрутизации, предоставленные клиентом, игнорируются.

reeves_screenshot возвращает пиксели Android как стандартный MCP-блок содержимого image (image/png с данными base64) вместе с шириной, высотой, временем захвата, идентификатором агента и метаданными длины в байтах. Агент Android использует объявляемый ретранслятором протокол фрагментированных результатов, поэтому непригодный локальный путь Android не раскрывается, и каждый подписанный HTTP-запрос остаётся в пределах лимита тела ретранслятора.

reeves_sequence отправляет от 1 до 50 упорядоченных действий устройства в одной маршрутизированной задаче. Android выполняет локально действия tap, swipe, type, Back, Home, Recents, wait и screenshot, по умолчанию останавливается на первой ошибке и по умолчанию возвращает одно итоговое MCP- изображение. Результаты включают индексированные результаты действий и аддитивные, не содержащие секретов тайминги этапов ретранслятора/Android. Существующий 25-секундный запрос агента — это длинный опрос с пробуждением при постановке в очередь, а не задержка получения; Android сразу начинает новый запрос после каждой успешной отправки результата и повторно использует один пул соединений OkHttp.

Этот релиз также согласовывает поддерживаемую версию протокола MCP, выдаёт ограниченную сессию, привязанную к субъекту OAuth, и требует эту сессию в последующих запросах. Повторные вызовы инструментов привязываются к субъекту OAuth, MCP-сессии, типизированному JSON-RPC id и хэшу запроса; завершение сессии аннулирует её кэшированную или ожидающую работу. Релиз также очищает отменённую работу ретранслятора и состояние аварийно завершившегося app-server, повторно проверяет авторизованные пути, изолирует события по потокам и редактирует ограниченные вложенные данные об ошибках на каждом публичном транспорте.

Версия 1.2.5 также согласует codex_status.latestAgentMessage с авторизованной сохранённой стенограммой. Полностью сохранённые внешние завершения Codex, включая синтезированные ходы rollout-*, теперь заменяют устаревшие сообщения, наблюдаемые мостом, в то время как неполные или прерванные хвосты стенограммы остаются исключёнными.

Разверните обновлённый ретранслятор перед обновлением агента Windows. Новый ретранслятор по-прежнему принимает устаревшие одноразовые результаты, тогда как новый агент использует фрагментированный формат только после того, как ретранслятор объявит о его поддержке.

См. docs/REMOTE_DEPLOYMENT.md с шагами Hostinger hPanel, DNS для mcp.biotele.mx, настройкой Auth0, настройкой Microsoft Entra ID, настройкой и восстановлением веб-коннектора ChatGPT, переменными окружения, установкой локального агента и моделью угроз.