Codex Semantic Review

Пакет PyPI: codex-commit-review-mcp · Релиз: v0.3.0

Это локальный MCP-сервер без сторонних зависимостей времени выполнения. После успешного коммита кода или конфигурации времени выполнения Codex получает обязательное напоминание $commit-review; при явном вызове он формирует свзанный с планом, читаемый и прослеживаемый сайт ревью кода. Один вызов history позволяет переключать несколько вкладок коммитов на одной странице.

Он собирает в одном интерфейсе тот контекст ревью, которого обычно не хватает в обычном git diff:

• Слева — настоящая рекурсивная сворачиваемая changed-file tree в стиле GitLab, с отображением статуса, важности и количества добавленных/удалённых строк.

• В центре — поддержка unified diff и строго выровненного split-представления before/after с сохранением старых и новых номеров строк, hunk'ов и позиций функций.

• Справа — важные функциональные изменения, а также объяснения по каждому файлу, функции, блоку и строке; клик по объяснению переходит, сменяя изменённый код.

• Вверху — стабильные ID шагов build plan, сопоставленные с файлами и функциями, и отображение covered/unmapped.

• review.json, comments.json и manifest.json предоставляют подтверждающие SHA-256 аудита.

Сайт привязывается только к 127.0.0.1 и не загружает код. Автоматические локализа подсказок всегда помечаются как heuristic; они помогают Codex найти позиции, но не могут удовлетворять финальному порогу семантического ревью.

Интерактивная демонстрация

В репозитории находится двуязычная интерактивная демонстрация, наследующая светлую тему MCP. Она имитирует с обезличенными псевдо-данными полный рабочий процесс в Codex Mac: ввод задачи, генерацию плана, подтверждение выполнения, построение по шагам, доставку и вызов MCP для открытия локального Review. После завершения сохраняется взаимно-одннозначное соответствие plan/под-функция/коммит; клик по любому пункту плана открывает соответствующий коммит, с деревом изменённых файлов, before/after diff, навигацией по файлу/функции/строке, семантическим гейтом и receipt. Демонстрация не читает текущий репозиторий и не загружает данные наружу.

python3 -m http.server 4173 --directory site

Затем откройте http://127.0.0.1:4173/.

Публичная страница продукта: GitHub Pages

Related MCP server: Git Code Review MCP

Установка одной командой

Установите пакет из PyPI и зарегистрируйте stdio MCP для Codex:

python3 -m pip install --user codex-commit-review-mcp==0.3.0 && codex mcp add codex_commit_review -- python3 -m commit_review_mcp

Используйте в Codex встроенный $skill-installer для установки соответствующего workflow-скила:

$skill-installer https://github.com/chi-qhsun/Codex-Semantic-Review/tree/v0.3.0/skills/commit-review

Новый скил будет доступен в следующем цикле. Проверьте MCP командой codex mcp list, затем вызовите вручную $commit-review, чтобы выполнить ревью коммита.

Интеграция в Codex

Официальная интеграция с Codex состоит из трёх уровней:

1. .codex/config.toml регистрирует stdio MCP и использует required = true, чтобы гарантировать доступность при вызове по требованию.

2. AGENTS.md требует от пересменного выполнения после коммита изменения поведения, но не запускает MCP автоматически.

3. .codex/hooks.json в PostToolUse ловит успешный git commit, а в Stop повторяет напоминание; изменения только в документации и изображениях не регистрируют pending и не ограничивают текущий turn.

Репозиторий уже содержит проект-level конфигурацию, готовую к использованию. Codex загружает project-level MCP и hooks только после того, как проект стал доверенным; после первого использования или изменения содержимого hooks проверить и доверить конкретное определde hook в Codex можно через /hooks.

Официальные источники:

• Конфигурация MCP в Codex

• Lifecycle-хуки Codex

• Инструкции проекта AGENTS.md

Шаблон TOML для других репозиториев или настроек пользователя приведён в examples/config.toml. Переиспользуемые скилы расположены в skills/commit-review.

Запуск

Достаточно Python 3.9+:

PYTHONPATH=src python3 -m commit_review_mcp

Лиlsyeтый также можно установить командную строку:

python3 -m pip install .
codex-commit-review-mcp

TOML-конфигурация для случая, когда проект взят как checkout, выглядит так; Codex отмpwаёт относительный cwd к корню текущего продукт-пакета, поэтому . заставляет PYTHONPATH = "src" указывать на каталог с исходному коду в репозитории:

[mcp_servers.codex_commit_review]
command = "python3"
args = ["-m", "commit_review_mcp"]
cwd = "."
env = { PYTHONPATH = "src" }
enabled = true
required = true
enabled_tools = ["prepare_commit_review", "create_commit_review", "prepare_commit_history_review", "create_commit_history_review", "read_commit_review"]
default_tools_approval_mode = "auto"
startup_timeout_sec = 10
tool_timeout_sec = 120

Двунаправления по плану

Отдельный коммит использует prepare_commit_review / create_commit_review. В пределах одного task имеosется несколько pending-коммитов, лучше использовать prepare_commit_выписки_review / create_commit_history_review; результатом является страница с вкладками, переключаемая от older-to-newer, но каждый SHA сохраняет независимые semantic result, digest и receipt.

Первая фаза вызывает prepare_commit_review or prepare_commit_history_review. Если план завершён, каждый его пункт должен иметь стабильный id; если плана нет, MCP формирует явный пункт auto-generated / unplanned:

{
  "repo_path": "/absolute/path/to/repo",
  "commit": "a1b2c3d",
  "plan": {
    "title": "Bound retry behavior",
    "items": [
      {"id": "retry", "title": "Bound transient retries", "description": "Retry transient failures at most three times"},
      {"id": "tests", "title": "Prove failure behavior", "acceptance": "Focused success and permanent-failure tests pass"}
    ],
    "decisions": ["Keep the public API compatible"],
    "risks": ["Retries must not hide permanent errors"]
  }
}

Инструменты возвращают:

• important_files — определяется функцией через функции/потоки управления, масштабом изменений и привязком к плану;

• annotation_contract.targets — точные точки вхождения при покрытии файл/функция/блок/строка;

• review_template — скелет почти готового pay-конечного payload, включает номера строк, индексы hunk'ов, имена функций и plan_item_ids.

После заполнения всех позиций при по второй фазе вызывается create_commit_review:

{
  "repo_path": "/absolute/path/to/repo",
  "commit": "a1b2c3d",
  "plan": {"title": "Bound retry behavior", "items": [{"id": "retry", "title": "Bound transient retries"}]},
  "review": {
    "summary": "This commit bounds transient retries while preserving permanent error propagation and the public call contract.",
    "important_changes": [
      {
        "path": "src/retry.py",
        "title": "Bounded retry state machine",
        "body": "Before, every failure escaped immediately; after, only transient failures enter a three-attempt loop and permanent failures still propagate.",
        "plan_item_ids": ["retry"]
      }
    ],
    "comments": [
      {"level": "file", "path": "src/retry.py", "body": "This file now owns retry classification, the bounded loop, and unchanged outward error propagation.", "plan_item_ids": ["retry"]},
      {"level": "function", "path": "src/retry.py", "function": "run", "line": 18, "body": "The function keeps its return contract but adds bounded state around transient calls; permanent exceptions are not caught.", "plan_item_ids": ["retry"]},
      {"level": "block", "path": "src/retry.py", "hunk_index": 0, "line": 19, "body": "This hunk introduces the three-attempt loop and separates retryable failures from the terminal path.", "plan_item_ids": ["retry"]},
      {"level": "line", "path": "src/retry.py", "hunk_index": 0, "line": 22, "body": "The explicit attempt bound prevents an unbounded retry loop while leaving the final exception visible.", "plan_item_ids": ["retry"]}
    ]
  },
  "open_browser": true
}

create_commit_review отклонит payload, в котором не хватает объяснений важных файлов, комментариев для любой из позиций реестровых целей, ссылка на план или конкретного summary. Успешный результат не обязан заверно содержать semantic_review.passed = true, url, review_dir, review_sha256, important_files, plan_coverage, comment_counts и receipt.

Напоминание и замкнутый аудит-цикл

После успешного ревью запись сохраняется в codex-commit-review/receipts/<commit>.json под Git metadata и не загрязняет рабочею дерево. На странице history для каждого сеанса записывается якобы один receipt, и все они соответствуют одному localhost-artifact значения при своей привязке к коммиту, digest'у и семантическому покрытию. Напоминание является обязательным, но по запросу стратегия этого проекта не блокирует turn, если пользователь не вызывает MCP; после вызова MCP продолжает строго отклонять heuristic-only и неполные payload.

Хук — это локальное напоминание в рабочем процессе, а не способ расширения прав: он не создает push, merge, upload, не удаляет код и не завершает другие процессы. Новые SHA после amend/rebase снова попадают в history; уже недостижимые superseded-коммиты больше не требуют ревью. Изменения в рабочейtree, не попавшие в commit, и зафиксированный diff отображаются раздельно.

Аудиткома файлы

Артефакт по умолчанию находится в ~/.codex/commit-reviews/<repo>/<commit12>/. Если эту директорию нельзя записать, в результате будет указано объяснение и фолбэк на температуру системы. Каталог содержит:

• review.json — commit, base, сопоставление плана, важные изменения, модель diff и семантическое покрытие;

• comments.json — комментарии Codex, heuristic и локальных комментариев веб-страки;

• browser.json — SHA-256 статики, review и comments;

• index.html, app.js, styles.css — локальный сайт без зависимости от CDN.

Раз diff ограничения параметром max_diff_bytes; бинарные файлы понижается до файлового уровня ревью. Определение функций — это лёгкое распознавание сигнатур, общее для языков, не претендующая на полное AST-анализ.

Проверка

python3 -m unittest discover -s tests -v
PYTHONPYCACHEPREFIX=/tmp/codex-commit-review-pyc python3 -m py_compile src/commit_review_mcp/*.py .codex/hooks/*.py
node --check src/commit_review_mcp/web/app.js
python3 -m build --wheel --no-isolation

Исследование вариантов визуализации и выбранные компромиссы — на странице docs/research.md.