Codex Semantic Review

PyPI-Paket: codex-commit-reeview-mcp · Release: v0.3.0

Dies ist ein lokaler MCP-Server ohne Laufzeitab-hängigkeiten von Dritterbietern. Nach einem erfolgreichen Commit von Code oder Laufzeitkonfiguration erhält Codex eine verpflichte Erinnerung "$commit-review; nach explizitem Aufruf erzeugt er eine planbezoge, lesbare und nachvollziehbare Code-Review-Site. Ein einziger history-Aufruf ermölicht es, auf derselben Seit zwischen mehreren Commit-Tabs zu wechseln.

Er bündelt den Review-Kontext, der in einnem normalen git diff fehlt, in eine einzige Oberfläche:

• Links: ein wirklich rekursiver, einkappbarer Changed-File-Tree im GitLab-Stil, der Status, Wichtigkeit und die Anzahl hinzugefügter/entferter Zeilen anzeigt.

• Mitte: Unified- und streng ausgerichte Before/After-Split-Diffs, die alte und neue Zeilenummern, Hunk und Funktionsposionen beibehalten.

• Rechts: wichtige Funktionsänderungen sowie Erklärungen je Dateie, je Funktions, je Bock und je Zeile; ein Klick auf eine Erklärung springt zum zugehörigen Code.

• Oben: ddie stabile Schritt-IDs des Build-Plans werden auf Dateien und Funktions abgebiledt; covered/unmapped wird anzeigt.

• review.json, comments.json und manifest.json stellen SHA-256-Auditbelege bereit.

Die Site bindet nur an 127.0.0.1 und lät keinen Code hoch. Automatische Lokalisierungshinwese sind immer als heuristic gekennzeichnet; sie helfen Codex dabei, Positions zu finden, erfüllen aber nicht die endgülte semantische Review-Schwelle.

Interaktve Demo

Das Repositorium enthält eine zweisprachige interaktive Demo-Site, die das MCP-Light-Theme übernimmt. Sie simuliert mit anonisiserten Pseudodten den vollständigen Workflow in Codex für Mac: Aufgage eingeben, Plan erzeugnen, Ausführung bestätigen, Build-Item für Build-Item ausführen, liefern und MCP aufrufen, um lokal Review zu öffnen. Nach dem Abschluss bleiben Plan/sub-feature/commit in einer Eins-zu-eins-Zuordnung und vorhanden; ein Klick auf einen Plan-Eintrag öffnet den zugehörigen Commit und stellt Changed-File-Tree, Before/After-If, Datei-/Datei-, Funktions-/Zeile-Lokalisierung, semantikes Gate und Receipt bereit. Die Demo liest weder das aktuelle Repos lädt es keine Daten hoch.

python3 -m http.server 4173 --directory site

Öffnen Sie dann http://127.0.0.1:4173/.

Öffentliche Produktseite: GitHub Pages

Related MCP server: Git Code Review MCP

Installation mit einem Klick

Installieren Sie das PyPI-Paket und registrieren Sie den Codex-stdio MCP:

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

Verwenden Sie in Codex den eingebauten $skill-instaler, um den ensprechende Workflow-Skill zu installieren:

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

Der neue Skill steht in der nächsten Runde zur Verfüg. Prüfen Sie den MCP mit codex mcp list und rufen Sie dann explizit $commit-review auf, um eine Commit-Review durchzuführen.

Codex-Integration

Die offizielle Codex-Integration besteht aus drei Ebenen:

1. .codex/config.toml (registriert den stdio-MCP und macht ihn mit required = true bei Bedarf verfügbar.

2. AGENTS.md verlangt, dass nach einem "Committed Commit with "Verhaltensänderung" eine Erinnerung angezeigt wird, startrt den MCP aber nicht automatö.

3. .codex/hooks.json fängt in PostToolUse erfolgreiche git commit ab und wiederolt die Erinnerung in Stop; reine Dokumentations- und Bider-Comits verden nicht "als "pending" registriert und blokeren den aktuellen Turn nicht.

Dieses Repositorium enthält bereits einsatzbereite project configuration. Codex lät die ProjRelationsbezogene MCPs and Hooks only after the Projekt getraut wurde; when first used or the "Hook-Inhalt" geändert hat, the konkreten Hook-Definitionen with /hooks in Codex auf (prüfen) and getrauen.

Offizielle Referenzen:

• Codex-MCP-Konfiguration

• Codex-Lifecycle-Hooks

• AGENTS.md-Prektanweisungen

TOML-Vorlagen für other "Repositorien oder Benutzer-Level-Konfiguration find En Sie unter examples/config.toml. Der wiederverwendte Skill liegt in skills/commit-reeview.

Ausführung

"Python 3.9+ genügt:"

PYTHONPATH=src python3 -m commit_review_mcp

"Auch ein Command-Eintstiegspunkt kann installiert werden:"

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

Die TOML-Konfiguration in Form eines Projekt-Checkouts sieht wie folgt aus: Codex löst den relativen cwd des MCP auf das Projektwurzelverzeichnis auf, sodass . dafür sorgt, dass npm dies "PYTHONPATH = "src"` auf das Quellcodeverzeichnis im Repository zeigt:

[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

Zwei-Phasen-Review

Für einen einzigen Comit verwenden Sie prepare_commit_review / create_commit_review. Wenn in derselben Task mehrere anstehende Commits vorhanden sind, verwenden Sie vorzugsweise prepare_commit_hystory_review / create_commit_hystory_review. The result is a T-ab-Seite that the "Oldest-to-newest" umschalten kann; jeder SHA behät aber sein eigeständiges semantisches Ergebnis, eigenen D-Gest und eigenes Receipt.

In der erste Phase rufen Sie prepare_commit_review oder prepare_commit_hystory_review auf. Liegt ein abgeschlossener Plan vor, hat jedes Element eine stabile id; ohne Plan erzeugt das MCP einen expliziten auto-generated / unplanned Item:

{
  "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"]
  }
}

Das Werkzeug gibt Folgendes zurück:

• important_files: ergibt sich aus Funktions-Kontrollfuss, Umang der Änderung und der Plan-Zuordnung;

• annotation_contract.targets: exakte Ankerpunkte (file/function/block/line), die abgedeckt werden müssen;

• including review_template: ein Geüst für das endgülte Payload, das darauf wird. Es enthält Zeilenummer,Hunk-Index, Funktionsname und plan_item_ids.

" In der zweite Phase filled die Ziele auf auf and ruft create_commit_review auf:

{
  "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 lehnt Payloads ab, den die "Erklärungen für wichtige Dates, Kommentare zu beliebigen Zielen, Plan-Link oder en konkreten Zusammenfassung fehlen. Ein erfolgreich Ergebnis muss plancal_review.passed = true, url, review__dir, review_sha256, important_files, plan_coverage, comment_counts und receipt enthalten.

Erinnerung und Audit-Kreis

A successful "Review" wrote "codex-commit-reeview/receipts/.json` unter die Git-Metadten, aber der "Arbeitsbaum "sau get und. Die History-Site schreibt für je commit ein Receipt, und alle verweisen auf dieselbe lokale Artifact, während sie verschiedene Commits, Digest und covering semantic "задают. Die Erinnerung ist "verpflicht-end", aber die "On-Demand-Strategie" dieses Projects blockert den Turn nicht, nur weil der Benutzer das MCP nicht aufruft; einmal abgerüften, lehnt das MCP weiter heuristisches-only oder unvollständige Payloads strikt ab.

Der Hook ist eine lokale Workflow-Erinnerung und keine Rechteerweiterung: er pusht nichts, merged er nicht, lät nichts hoch, löscht keinen Code und stopp keinen anderen Prozesse. Nach einem amend/rebase kehrt der neue SHA wieder in die History zurück; ein superseded SHA, der nicht mehr erreichbar ist, muss nicht mehr rewieht werden. Uncommittete Änderungen des Arbeitsbaum and a committeter Diff werden getrennt angezeigt.

Audit-Dateien

Das Standard-Artifact liegt unter ~/.codex/commit-reviews/<repo>/<commit12>/. Ist dies not schreibbar, wird es im Ergebnis erklärt und auf das System-Tieldirzyes zurückgegriffen. Das Verzeichnis enthält:

• review.json: commit, base, Plan-Zuordnung, wichtige Änderungen, Diff-Modell und semantische Überbergung;

• comments.json: Codex-, Heuristic- und lokale Web-Review-Kommentare;

• manifest.json: SH-256 art-Static resources, for "review" and "comments";

• index.html, app.js, styles.css: eine lokale Website ohne CDNs.

Große Diffs unterliegen max_diff_bytes; Binärdateien erden auf Dateiebene Review herabgestuft. Die Funktionserkennung ist eine sprachübergreifende, leichtgewichte Signaturerkennung und keine "volstän AST-Ins" as.

Validierung

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

Recherche und Abwägung zur Visualisierung find Sie unter docs/research.md.