codex-mcp

Независимый шлюз качества для QA-артефактов, работающий в режиме только для чтения.

codex-mcp — это автономный MCP-сервер, который запускает Codex как второго рецензента-оппонента для проверки кандидатов в тест-кейсы и найденных багов — до того, как агент-автор напишет итоговый отчёт. Codex сам изучает репозиторий, формирует собственное представление о том, что должно быть покрыто тестами или реален ли дефект, и только затем сравнивает это с переданным ему кандидатом.

Он возвращает дельту ревью (review delta). Ваш артефакт он никогда не изменяет.

Authoring agent (Claude, or any MCP client)
        │  gathers the requirement, reads the code, drafts candidates
        ▼
  candidate result — in memory, not yet written
        │
        ▼  codex_qualify
   codex-mcp ──► Codex (read-only sandbox, rooted at your repo)
        │           ├─ reads the code, the diff, the existing tests
        │           ├─ reads blast-radius / test-charter if present
        │           └─ reads Jira / DB / other MCPs if configured, read-only
        ▼
  review delta: accept · modify · remove · missing · evidence · limitations
        │
        ▼
Authoring agent reconciles, then writes the FINAL artifact

Содержание · Установка · Подключение к проекту · Использование · Конфигурация · Коннекторы доказательств · Граница прав доступа · API-контракт · Устранение неполадок · Тестирование

Зачем вторая модель и почему только чтение

Сбой, который здесь устраняется, — это не «агент не умеет писать тест-кейсы». Это ситуация, когда агент, оценивающий собственную работу, соглашается сам с собой. Рецензент, который разделяет контекст автора, наследует и его слепые зоны.

Поэтому две характеристики являются определяющими:

Независимость. Codex получает инструкцию сформировать ожидаемое покрытие до того, как он внимательно изучит кандидата, и пытаться опровергнуть каждое утверждение о баге, а не подтверждать его. Если сначала «заякорить» его на кандидате, рецензент получится более сговорчивым, но менее полезным.

Только чтение. Рецензент работает в read-only песочнице Codex, а каждая достижимая из него нижестоящая система фильтруется через слой политик, который классифицирует каждый инструмент и отказывает всему, что что-то изменяет. Шлюз качества, который нельзя безопасно направить на живой репозиторий, — это шлюз качества, который никто не запускает.

Ни одна из моделей не является авторитетом. Источник истины — это:

requirement / runtime / code / DB / external evidence  >  model opinion

Related MCP server: tenth-man-mcp

Установка

Требуется Node 20+. Четыре команды — один раз на машину.

# 1. The Codex CLI. codex-mcp drives it, and it owns your credentials.
npm install -g @openai/codex@latest

# 2. codex-mcp itself.
git clone <this-repo> codex-mcp && cd codex-mcp
npm install && npm run build && npm link

# 3. Sign in. A browser opens once; that is the whole flow.
codex-mcp login

# 4. Write a config, detecting any MCP servers already on this machine.
codex-mcp init --model gpt-5.6-sol

Затем подтвердите работоспособность, прежде чем доверять шлюзу:

codex-mcp doctor

Каждая строка должна показывать ok. doctor работает только на чтение и безопасен для живого проекта — о том, что означает каждый сбой, см. Устранение неполадок.

Имя codex-mcp в npm принадлежит постороннему, не связанному пакету. Устанавливайте из исходников, как описано выше, либо публикуйте под собственным scope.

Что делает init

Он записывает ~/.config/codex-mcp/codex-mcp.yaml, а рядом с ним .env, если обнаруживает ниже по конвейеру MCP-серверы в стандартных расположениях:

$ codex-mcp init --dry-run
Would write into /home/you/.config/codex-mcp
  codex-mcp.yaml  (new)
  .env            (new)

Detected:
  jira-mcp (jira) -> /home/you/jira-mcp/src/index.js
  db-mcp (database) -> /home/you/db-mcp/dist/index.js

Обнаруженные серверы записываются как включаемые записи коннекторов, при этом их пути хранятся в .env, чтобы YAML оставался переносимым между машинами. --force перезаписывает; без него существующие файлы сохраняются.

init — единственная команда, который что-то записывает, и он выполняется до того, как появляется какое-либо ревью. Сами ревью строго read-only.

Хотите написать конфигурацию самостоятельно? Скопируйте codex-mcp.example.yaml в ~/.config/codex-mcp/codex-mcp.yaml — каждое значение в нем снабжено комментарием и является встроенным значением по умолчанию, если комментарий не говорит об ином.

Аутентификация

Одна команда, один раз на машину:

codex-mcp login          # browser opens; sign in to ChatGPT
codex-mcp auth-status    # confirm

Учётные данные попадают в собственное хранилище Codex CLI (~/.codex/auth.json, режим 0600) и обновляются им. Они сохраняются между перезагрузками и терминалами — вам не нужно entry: ... Вам не нужно входить заново для каждого проекта или сессии.

codex-mcp сам никогда не работает с учётными данными. У него нет OAuth-клиента, нет обработчика колбэков и хранилища токенов. Он вызывает codex login status и читает ответ «да» или «нет». Во время ревью здесь ничего не может открыть браузер: аутентифицированный вызов быстро завершится ошибкой instead.

{ "code": "CODEX_AUTH_REQUIRED", "message": "Codex is not authenticated. Run `codex-mcp login`." }

Использование API-ключа как альтернативы

codex-mcp login --mode api                    # hidden prompt
printenv OPENAI_API_KEY | codex-mcp login --mode api

Ключ читается из --api-key, затем из OPENAI_API_KEY, затем из скрытого запроса и передаётся в codex login --with-api-key через stdin — но никогда через элементы argv, поэтому он не попадает в таблицу процессов и историю оболочки. Его хранит Codex CLI; codex-mcp — нет.

Задайте в конфигурации auth.mode соответствующим образом. Если CLI аутентифицирован в режиме, отличном от указанного в конфиге, ревью будет завершаться понятной ошибкой, а не молча спишет средства с не той учётной записи.

Подключение к проекту

Выберите один из этих вариантов. Регистрация в обоих — самая распространённая ошибка настройки — предупреждение ниже.

Вариант А — один проект, коммит в репозиторий

Создайте .mcp.json в корне проекта — а не в .claude/, где хранятся другие файлы, и он будет проигнорирован:

{
  "mcpServers": {
    "codex-mcp": { "command": "codex-mcp", "args": ["start"] }
  }
}

Зафиксируйте его. Теперь у каждого коллеги, который выполнил Установку, есть этот шлюз, при этом каждый использует свой выбор модели из своего конфигурационного файла.

Вариант Б — все ваши проекты, без коммитов

claude mcp add codex-mcp -- codex-mcp start

Это записывает данные в ~/.claude.json и применяется везде, где вы работаете.

Регистрируйте только в одном месте. claude mcp add пишет на локальном уровне, что имеет приоритет над .mcp.json. Если присутствуют оба, проектный файл — включая его env — молча игнорируется. Выполните claude mcp remove codex-mcp, если переходите на .mcp.json.

Перезапустите Claude Code. /mcp теперь должен показывать codex-mcp с тремя инструментами. Если этого нет — см. Устранение неполадок.

Другие MCP-клиенты принимают те же два поля — command: codex-mcp, args: ["start"] — в своём конфигурационном файле.

Использование

Сделайте это автоматическим

Добавьте одно правило в CLAUDE.md проекта. Это и есть вся площадь интеграции — никакой специальной логики Codex для конкретного проекта не требуется:

## Independent QA qualification

Before finalizing test cases or bug reports, send the complete candidate result,
project root, task/requirement context, and any available blast-radius or
test-charter to codex-mcp for independent qualification.

Reconciling means verifying each objection against the evidence it cites — not
accepting it. Apply what the evidence supports. Reject what it does not, and note
why. codex-mcp is a second opinion, not an approver.

One pass is normal. Run a second only if the first forced substantial high-risk
changes.

С этим правилом вы просто пишите обычный запрос, и шлюз выполняется сам:

Создай тест-кейсы для DEV-2951.

Агент собирает требования, читает код, готовит кандидатов, вызывает codex_qualify, согласовывает результат и затем пишет отчёт.

Явно потребовать этого

Когда правила нет или вы хотите применить ревью к уже готовому черновику:

Прежде чем писать отчёт, отправь эти тест-кейсы в codex-mcp с project.root, указанным как /path/to/repo, и task.id равным DEV-2951. Покажи, против чего он возражает, и согласен ли ты с ним, затем напиши финальную версию.

Прогони только что написанные баг-находки через codex_qualify с параметром reviewType: "bugs". Всё, что он назовёт ложным срабатыванием, проверь — то, на что он ссылается, прежде чем отбрасывать находку.

Проверь их в codex-mcp, но сообщай только о возражениях, где приведённое доказательство действительно подтверждается. Расскажи, какие находки ты тот отклонил и почему.

Полезные варианты:

Разбор ответа

Попросите агента показывать эти вещи, а не молча действовать:

• missing — покрытие, которого, по его словам, вам не хващает. Проверьте, что указанный file:line реален.

• modify — ваше ожидание противоречит коду. Обычно это самой острое замечание.

• remove — избыточное. Проверьте, действительно ли то, что он говорит заменяет ваше, делает это.

• limitations — что он не смог проверить. Уверенное ревью с большим список ограничений — это узко ревью; читайте это, прежде чем доверять остальному.

• disagreements — он и ваш агент читают один и те же факты по-разному. Это нужно принимать вам, а не какой-либо модели.

Пример удачного уточняющего промпта:

По каждому замечанию скажи: на какие доказаться он ссылается, и проверил ли ты это сам. Перечисли всё, что ты отклонил, и почему.

Чего он не будет делать

Он никогда не редактирует файлы, не делает коммиты, не пушит, не пишет в Jira или в базу данных, не пишет ваш отчёт. Если ваш агент утверждает, что codex-mcp что-то изменил, — значит, не он; проверьте git status.

Согласование — важная часть

codex-mcp никогда не советует вам принять Codex. Каждый ответ содержит:

{
  "reconciliation": {
    "instruction": "This is an independent second opinion, not a verdict...",
    "codexIsNotAuthoritative": true
  }
}

Codex objection
      │
      ▼
Author verifies the cited evidence
      │
      ├─ evidence supports it   → apply
      ├─ evidence does not      → reject, and record why
      └─ unclear                → investigate

Затем вы пишете итоговый артефакт.

Защита от циклов

review.maxPasses (по умолчанию 2) ограничивает количество проходов. Проход 1 — обычный случай; проход 2 существует для ревью, которые потребовали требующих большого количества изменений по предварительно картам с большим риском. Запрос, превышающий лимит, отклоняется, а meta.furtherPassesAllowed сообщает, когда выделенный бюджет исчерпать. Итерироваться до согласия двух моделей — не цель: согласие дёшево, и его достижение означает, что одна из них перестала думать.

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

Настройки лежат в ~/.config/codex-mcp/codex-mcp.yaml. Это единственный файл, который нужно редактировать. codex-mcp.example.yaml — аннотированная версия с актуальными идентификаторами моделей Codex.

Отсутствие конфигурационного файла полностью поддерживается — сервер запускается с безопасными значениями по умолчанию. Вы лишаетесь только зафиксированной модели и всех коннекторов, поскольку коннекторы могут быть определены только в YAML.

Где указывается модель

review:
  model: gpt-5.6-sol
  requireModel: true

Её можно задать на трёх уровнях. Выигрывает наивысший по приоритету:

Держите модель в одном слое. Ключ, заданный в двух местах, делает нижнюю копию мёртвой — её редактирование никакого видимого эффекта не давал. doctor предупредит, если модель задана в обоих и они различаются.

Чтобы зафиксировать модель для целого проектной команды, добавьте env в .mcp.json из Варианта A:

{
  "mcpServers": {
    "codex-mcp": {
      "command": "codex-mcp",
      "args": ["start"],
      "env": { "CODEX_MODEL": "gpt-5.6-sol", "CODEX_REASONING_EFFORT": "high" }
    }
  }
}

Это гарантирует всем один и тот же ревьюер, что очень важно при сравнении замечаний между участниками. Цена: коллега, чей Codex CLI слишком старая для данной модели, получит жёсткое сообщение CODEX_MODEL_NOT_AVAILABLE с указанием выполнить codex update. Такой сбой оправдан и намерен — иначе незаметно применялся бы более слабый ревьюер, чьему вердикту он бы доверял.

Какую модель выбрать. Отдавайте предпочтение frontier-модели. Вся ценность этого инструмента — понять, что упустил агент- автор; более дешёвый рецензент в основном соответствует тому, что ему показывают. Установите requireModel: true на общем шлюзе, чтобы возможное изменение значения по умолчанию Codex не могло незаметно снизить качество ревью. Если модель недоступна, возникает CODEX_MODEL_NOT_AVAILABLE; codex-mcp не будет работать с другой моделью.

Каждая настройка и её переменная окружения

Приоритет: переменные окружения > codex-mcp.yaml > значения по умолчанию. Переменные существуют, чтобы переопределять одно значение в YAML без редактирования файла — в env в .mcp.json для закрепления проекта, либо для разовой команды shell.

Настройки коннекторов инвертируют этот приоритет: YAML побеждает, потому что это явное намерение для конкретного коннектора, а эти переменные — грубые запасные варианты на случай, когда YAML ничего не говорит.

Эти переключатели соответствуют имени коннектора, а не его типу — коннекторы с именами jira-mcp и db-mcp не соответствуют ни jira, ни database, поэтому оба попадают под CUSTOM_MCPS_ENABLED. Установка enabled: в YAML снимает вопрос полностью.

Две переменные не имеют аналога в YAML, поскольку они читаются до того, как найден какой-либо файл конфигурации: CODEX_MCP_CONFIG (путь к файлу конфигурации) и XDG_CONFIG_HOME (где ищется ~/.config/codex-mcp/).

Где находится файл конфигурации

Побеждает первый найденный:

--config <path>  →  $CODEX_MCP_CONFIG  →  ./codex-mcp.yaml  →  ~/.config/codex-mcp/codex-mcp.yaml

doctor выводит, какой именно загружен. .env рядом с выбранным файлом читается, если присутствует; ничего не требуется. Его стоит заводить только для значений, различающихся от машины к машине — например, путей к коннекторам, на которые ссылается YAML как ${JIRA_MCP_PATH} — и даже они могут иметь запасной вариант ${VAR:-fallback}.

Никогда не помещайте учётные данные в .env или YAML. CHATGPT_TOKEN, SESSION_TOKEN, ACCESS_TOKEN и REFRESH_TOKEN игнорируются полностью, а их наличие сообщается как предупреждение о конфигурации. Аутентификация Codex принадлежит CLI Codex и хранилищу учётных данных вашей ОС.

Коннекторы доказательств

Codex никогда не общается с Jira или вашей базой данных напрямую. Он подключается к брокеру доказательств codex-mcp — отдельному процессу только для чтения, который обнаруживает инструменты каждого нижестоящего сервера, классифицирует их и пересылает только то, что проходит политику — перепроверяя при каждом вызове, а не только при обнаружении.

# ~/.config/codex-mcp/codex-mcp.yaml
connectors:
  jira-mcp:
    enabled: true
    kind: jira
    approval: once
    transport: stdio
    command: node
    args: ['/path/to/jira-mcp/src/index.js']
    cwd: /path/to/jira-mcp

  db-mcp:
    enabled: true
    kind: database
    approval: once
    transport: stdio
    command: node
    args: ['/path/to/db-mcp/dist/index.js']
    cwd: /path/to/db-mcp
    allowTools: ['execute_query']
    denyTools: ['update_query']
    maxRows: 500
    timeoutMs: 10000

kind приводит к нормализации в стабильный словарь — requirement.read, database.query_readonly, testmanagement.search, external_file.read — чтобы запрос рецензента мог спрашивать «требование», не зная, называет ли ваш коннектор его getJiraIssue или get_jira_ticket. Несопоставленные инструменты по-прежнему доступны под своими именами; добавление нового MCP-сервера только для чтения не требует изменения кода.

Нижестоящий сервер получает только PATH, HOME и env, объявленные в его собственной конфигурации — никогда окружение процесса codex-mcp.

Недостижимый коннектор сводит рецензию к зафиксированному ограничению, а не к провалу. Отсутствие доказательств — это факт о рецензии, и ответ так и сообщает.

Запустите codex-mcp doctor после добавления коннектора. Каждая строка коннектора сообщает, сколько инструментов было открыто и сколько скрыто политикой:

[  ok  ] Connector: jira-mcp
           4 read-only tool(s) exposed, 0 withheld by policy.
[  ok  ] Connector: db-mcp
           6 read-only tool(s) exposed, 1 withheld by policy.

Запрос разрешения — поле approval

Чтение проекта, который вам передали, не требует разрешения: вы предоставили project.root, поэтому чтение и есть запрос. Выход за его пределы — трекер задач, рабочая база данных, файловый сервер — это отдельное решение, и enabled: true в файле конфигурации, написанном недели назад, не является информированным согласием на сегодняшнюю рецензию.

Запрос доставляется через MCP elicitation, поэтому он достигает человека в вашем MCP-клиенте. Если ваш клиент не умеет показывать промпты, коннектор пропускается и фиксируется в limitations — а не молча разрешается. Промпт, который никто не может увидеть, — это не согласие. Устанавливайте approval: trusted только на коннекторы, которые вы уже проверили.

Требования

Когда настроен коннектор типа jira и задан task.id, Codex читает тикет сам и рассматривает любой переданный вами текст требований как интерпретацию автора — утверждение, которое нужно сверить, а не источник. Без коннектора он возвращается к предоставленному вами тексту и фиксирует, что не смог проверить его независимо.

База данных

Используется только там, где она может изменить вердикт: персистентность, связи, владение тенантом, переходы состояний, миграции, целостность данных, проверка сообщённого дефекта. Промпт говорит об этом явно, а слой политики обеспечивает остальное.

Используйте учётную запись базы данных только для чтения. codex-mcp отклоняет любые изменяющие операторы, но грант только на чтение — это граница, которая не зависит от корректности этого сервера.

Граница разрешений

Главное правило: Codex может широко просматривать и ничего не изменять.

Читайте «широко» буквально — см. область чтения шире проекта ниже, прежде чем направлять это на машину с секретами, которые вам дороги.

Обеспечение, по слоям:

1. Собственная песочница Codex read-only — основная граница.

2. Политика команд — на основе argv, запрет по умолчанию. Неизвестные бинарники отклоняются; обёртки shell отклоняются, потому что их полезную нагрузку невозможно классифицировать.

3. SQL-политика — комментарии и строковые литералы удаляются перед сканированием ключевых слов, поэтому мутация не может спрятаться внутри значения в кавычках. Один оператор на вызов, ограничение строк внедряется, когда в запросе его нет.

4. Политика инструментов — каждый нижестоящий MCP-инструмент классифицируется как read / write / destructive / unknown; открывается только read. unknown запрещён, если явно не внесён в белый список, и никакой белый список не может спасти изменяющий инструмент — граница, которую можно обойти аргументацией, — не граница.

Классификатор намеренно асимметричен: любой намёк на мутацию перевешивает любой намёк на чтение, и инструмент должен выглядеть однозначно read-only, чтобы быть открытым. Инструмент, который звучит опасно, но не является таковым, стоит вам одной строки конфигурации; инструмент, который звучит безопасно, но не является таковым, стоит вам данных.

tests/security/ проверяет всё это, включая то, что отклонённый вызов никогда не достигает нижестоящего сервера и что фикстурный репозиторий байт-в-байт идентичен после рецензии.

Область чтения шире проекта

Песочница Codex read-only ограничивает запись, а не чтение. Внутри неё Codex может читать любые файлы, доступные вашей учётной записи, — не только файлы в project.root. Проверено напрямую:

$ codex exec --sandbox read-only -C ./proj   "read ../outside.txt"
exec  sed -n '1,$p' ../outside.txt   in .../proj
      succeeded: SECRET_OUTSIDE=canary-9f3a2b

CLI Codex не предлагает опции сузить область чтения; sandbox_permissions только предоставляет дополнительный доступ. Поэтому честная формулировка гарантии такова:

Ничего не изменяется, нигде. Чтение ограничено правами доступа вашей ОС, а не project.root.

project.root направляет куда смотрит рецензент — это рабочая директория и предмет промпта — но это не тюрьма для чтения.

Что это означает на практике:

• .env, приватный ключ или файл с учётными данными, доступный вашему пользователю где угодно, достижим для рецензента, и его содержимое может быть отправлено в OpenAI как часть контекста модели.

• Ограничение путей артефактов codex-mcp (assertArtifactPathAllowed) не даёт codex-mcp читать файлы вне проекта в промпт. Оно не ограничивает и не может ограничить то, что Codex читает внутри своей собственной песочницы.

• Результаты редактируются перед записью в журнал, но это контроль журналирования, а не изоляции.

Если это важно для вашего окружения, запускайте codex-mcp в контейнере или виртуальной машине с смонтированным только проектом. Это единственный надёжный способ ограничить чтение на сегодняшний день.

Что рецензент читает по замыслу

Внутри корня проекта он читает всё, включая скрытые директории. Скрытие .claude, .cursor, .github или собственного .qa команды от рецензента — это путь к тому, что он игнорирует именно те правила, которые проект записал для себя. Известные кеши инструментов (.venv, .pytest_cache, .next и подобные) по-прежнему перечисляются, но не рекомендуются ему как материал для чтения.

Файлы соглашений — CLAUDE.md, AGENTS.md, CONTRIBUTING.md, TESTING.md, .cursorrules, CODEOWNERS — выносятся в промпт как «прочитайте это в первую очередь».

Контракт

codex_qualify

Обязательны: reviewType, project.root и набор кандидатов, соответствующий типу рецензии. Всё остальное необязательно и никогда не блокирует рецензию.

{
  "reviewType": "test-design",

  "project": { "root": "/absolute/path/to/project", "branch": "feature/DEV-123" },

  "task": {
    "id": "DEV-123",
    "source": "jira",
    "title": "Archive a resource",
    "description": "A user may archive a resource belonging to their own tenant.",
    "acceptanceCriteria": ["Archiving an active resource sets status to archived."]
  },

  "artifacts": {
    "blastRadiusPath": "docs/blast-radius.md",
    "testCharterPath": "docs/test-charter.md"
  },

  "candidate": {
    "testCases": [{ "id": "TC-001", "title": "Archive an active resource", "priority": "high" }],
    "bugs": []
  },

  "options": { "useJira": true, "useDatabase": true, "useExternalMcps": true }
}

Кандидаты передаются в полезной нагрузке. Они ещё никуда не записаны, и требование временного файла отчёта лишило бы смысла всю затею.

Пути артефактов разрешаются внутри project.root; путь, выходящий за его пределы, отклоняется.

Типы рецензий

Результат тест-дизайна

{
  "status": "CHANGES_REQUIRED",
  "summary": { "accepted": 18, "modify": 2, "remove": 1, "missing": 3 },
  "accepted": ["TC-001", "TC-002"],
  "modify": [{
    "candidateId": "TC-014",
    "reason": "Expected state contradicts persistence logic.",
    "evidence": [{ "source": "code", "location": "src/session/service.ts:143" }],
    "recommendation": "Queue should remain persisted after this transition."
  }],
  "remove": [{ "candidateId": "TC-022", "reason": "Duplicates TC-018.", "supersededBy": "TC-018" }],
  "missing": [{
    "title": "Verify cross-tenant access is rejected",
    "priority": "high",
    "dimension": "authorization",
    "reason": "Target lookup accepts an externally supplied identifier.",
    "evidence": [{ "source": "code", "location": "src/resource/controller.ts:82" }]
  }],
  "disagreements": [],
  "limitations": []
}

Результат по багам

{
  "status": "CHANGES_REQUIRED",
  "summary": { "verified": 1, "falsePositive": 1, "needsMoreEvidence": 0, "other": 0 },
  "findings": [{
    "candidateId": "BUG-003",
    "verdict": "FALSE_POSITIVE",
    "confidence": "high",
    "severityAssessment": null,
    "reason": "Ownership validation occurs in router-level middleware.",
    "evidence": [
      { "source": "code", "location": "src/routes/users.ts:42" },
      { "source": "code", "location": "src/middleware/access.ts:91" }
    ],
    "recommendation": "Remove the finding unless runtime evidence contradicts the middleware."
  }],
  "limitations": []
}

status: PASS · CHANGES_REQUIRED · INCONCLUSIVE · ERROR

verdict: VERIFIED · FALSE_POSITIVE · NEEDS_MORE_EVIDENCE · SEVERITY_DISAGREEMENT · DUPLICATE_OR_ALREADY_COVERED · INCONCLUSIVE

Что гарантирует конверт

codex-mcp нормализует вывод ревьюера перед возвратом, потому что модель, оценивающая список, иногда отклоняется:

• придуманные ревьюером id отбрасываются с пометкой — вы не можете действовать по ссылке на тест-кейс, которого не существует;

• кандидат, которого ревьюер не упомянул, записывается как unreviewed и никогда не повышается до accepted, потому что молчание — не одобрение;

• баг без вердикта становится явным INCONCLUSIVE;

• счётчики summary пересчитываются из массивов;

• status выводится из дельты, а не из самооценки ревьюера.

meta.evidence сообщает, на чём фактически основывался ревью — были ли доступны git, blast-radius, test-charter и доступ к требованиям, и какие коннекторы были достижимы. Сам путь проекта никогда не логируется и не возвращается; meta.evidence.projectRootId — это хэш.

codex_auth_status

Аутентифицирован ли Codex, в каком режиме и совпадает ли это с вашим настроенным auth.mode. Никогда не возвращает учётные данные.

codex_capabilities

Диагностика. Какие свидетельства может получить этот экземпляр, какие нижестоящие инструменты были скрыты и почему, и явный список того, что ревьюеру запрещено делать.

CLI

codex-mcp init         # write ~/.config/codex-mcp/, detecting local MCP servers
codex-mcp start        # run the MCP server on stdio (what a client launches)
codex-mcp login        # authenticate (--mode chatgpt|api)
codex-mcp auth-status  # report auth state, never credentials
codex-mcp doctor       # diagnose everything; mutates nothing

init принимает --model <id>, --force и --dry-run. start и doctor принимают --config <path>. doctor также принимает --project <path> и --json.

codex-mcp broker — внутренняя команда — брокер свидетельств, который запускает Codex. Вы не запускаете его вручную.

Устранение неполадок

Всё, что сообщает doctor, — либо ok, либо warn (работает, но менее строго, чем следует), либо FAIL (ревью не могут работать).

Ошибки

Стабильные коды, по которым можно безопасно ветвиться. Полезные данные редактируются до выхода из процесса.

CODEX_AUTH_REQUIRED              CODEX_NOT_INSTALLED
CODEX_MODEL_NOT_CONFIGURED       CODEX_MODEL_NOT_AVAILABLE
INVALID_PROJECT_ROOT             PROJECT_ACCESS_DENIED
INVALID_REVIEW_REQUEST           INVALID_REVIEW_TYPE
DOWNSTREAM_MCP_UNAVAILABLE       DOWNSTREAM_MCP_PERMISSION_DENIED
DB_QUERY_DENIED                  DB_QUERY_TIMEOUT
CODEX_EXECUTION_FAILED           CODEX_OUTPUT_INVALID
REVIEW_TIMEOUT                   INTERNAL_ERROR

Если Codex возвращает вывод, не соответствующий схеме, codex-mcp повторяет попытку один раз с явной корректировкой, запрещающей повторный анализ. Если это тоже не удаётся, он возвращает CODEX_OUTPUT_INVALID. Он не возвращает частично разобранный ревью — вы бы действовали по нему.

Наблюдаемость

Структурированный JSON в stderr (stdout принадлежит транспорту MCP). Логируются: id и тип ревью, хэшированный id проекта, модель, тайминги, доступность коннекторов, количество кандидатов, статус выхода Codex, статус валидации схемы.

Никогда не логируются: токены, пароли, учётные данные БД, куки, секреты, найденные в исходниках. Редактирование выполняется на каждом уровне, включая debug.

Тестирование

Пять уровней, от самых дешёвых к дорогим. Проходите их сверху вниз — сбой на одном уровне делает результат следующего бессмысленным.

1. Автоматизированный набор — бесплатно, офлайн, ~7с

npm install
npm run build
npm test
npm run typecheck

400+ тестов против фейкового CLI Codex и намеренно враждебного фейкового MCP-сервера. Без сети, без вызовов моделей, детерминированно. Это то, что вы запускаете при каждом изменении и в CI.

tests/security/ — часть, которую стоит прочитать: она проверяет, что правки файлов, коммиты, пуши, запись issues и мутации БД отклоняются — и что отклонённый вызов никогда не достигает нижестоящего сервера.

2. doctor — правильно ли настроена эта установка

codex-mcp doctor
codex-mcp doctor --project /path/to/repo

Только чтение, безопасен для живого проекта. Проверяет Node, CLI Codex, аутентификацию, согласованность режима аутентификации, модель, песочницу, файл конфигурации и каждый настроенный коннектор.

3. codex_capabilities — какие свидетельства он реально может получить

doctor даёт количества; этот даёт разбивку по инструментам, включая почему каждый скрытый инструмент был скрыт. Вызовите его из вашего MCP-клиента или:

node -e "
import('./dist/src/config/config.js').then(async ({loadConfig}) => {
  const {CodexMcpServer} = await import('./dist/src/server.js');
  const {Logger} = await import('./dist/src/util/logger.js');
  const s = new CodexMcpServer({config: loadConfig(), logger: new Logger('error', {}, {write(){}})});
  console.log(JSON.stringify(await s.callToolForTesting('codex_capabilities', {}), null, 2));
  process.exit(0);
});"

Проверьте, что ожидаемые инструменты есть в allowedTools, и что каждая запись в deniedTools — та, которую вы хотите запретить. Инструмент только для чтения с необычным именем попадает в deniedTools как unknown — добавьте его в allowTools этого коннектора.

4. npm run try — реальный ревью, реальная модель, реальная стоимость

Это единственный уровень, который тратит бюджет. Он проверяет весь путь: аутентификацию, модель, песочницу, сбор свидетельств, коннекторы, промпт, структурированный вывод.

npm run try -- --project /path/to/repo
npm run try -- --project /path/to/repo --type bugs
npm run try -- --project /path/to/repo --type combined --task DEV-123
npm run try -- --project /path/to/repo --candidates ./candidates.json --json

Без --candidates он отправляет набор с известными дефектами — два дубликата, одно утверждение, которому противоречит код, и несколько очевидных пробелов. В этом суть: вы тестируете ревьюера, поэтому используйте входные данные, правильный ответ для которых вы уже знаете.

Оценивайте по:

• поместил ли он дубликат в remove?

• поместил ли он противоречащее утверждение в modify со ссылкой на код?

• есть ли у каждой записи missing реальный file:line, а не размытая область?

• остался ли репозиторий неизменным после (git status)?

PASS на наборе с дефектами означает, что что-то не так, а не что ваш код чист.

Передайте --candidates со своим JSON, чтобы отрепетировать реальный рабочий процесс:

{ "testCases": [{ "id": "TC-1", "title": "..." }], "bugs": [] }

5. End-to-end фикстур — по желанию

CODEX_MCP_E2E=1 npm test -- tests/e2e

Создаёт фикстур-репозиторий с реальным пробелом в покрытии (идемпотентность) и баг-репортом, который уже опровергает middleware роутера, запускает полную квалификацию против реального CLI Codex и проверяет, что фикстур побайтово идентичен после. Занимает несколько минут.

Использование в качестве MCP-сервера

Когда уровни выше пройдены, используйте его так, как это будет делать клиент:

printf '%s\n%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"1"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | codex-mcp start

Затем зарегистрируйте его в Claude Code и используйте на реальном тикете.

Разработка

src/
  config/      resolution, precedence, validation
  auth/        Codex CLI delegation for both auth modes
  codex/       process spawning, argv construction, output parsing
  review/      orchestration, per-type reviewers, output normalization
  evidence/    repository, git, artifacts, requirement, database, external
  mcp-broker/  downstream clients, discovery, classification, the broker server
  policy/      command, SQL, MCP-tool, permission, and consent decisions
  prompts/     base reviewer, test-design, bug-review
  schemas/     public request and result contracts
  tools/       the three MCP tools

Лицензия

MIT