Codex Semantic Review

PyPI 패키지: codex-commit-review-mcp · 릴리스: v0.3.0

이것은 런타임 서드파티 의존성이 전혀 없는 로컬 MCP server입니다. 코드 또는 런타임 구성을 성공적으로 커밋하고 나면, Codex는 필수 $commit-review 알림을 받습니다. 명시적으로 호출하면 플랜 매핑, 가독성, 추적 가능성을 갖춘 코드 리우 사이트를 생생합니다. history 호출 한 번으으로 같은 페이에서 여러 commit tab을 전환할 수 있습니다.

일반 git diff에 없던 리뷰 컨텍스트를 하나의 인터페이스로 모아 줍니다:

• 왼쪽엔 진짜 재귀적이며 점을 수 있는 GitLab 스타일 changed-file tree가 있고, 상태, 중요도, 추가/삭제 라인 수를 표시합니다.

• 가운데는 unified 및 엄격히 정렬된 before/after split diff를 지원하며, 이전/새 라인 번호, hunk, 함수 위치를 유지합니다.

• 오른쪽엔 중요한 기능 변경과 함께 파일별, 함수별, 블록별, 라인별 설며이 표시되고, 설명을 클릭하면 해당 코드로 이동합니다.

• 상단에 build plan의 안정된 step ID를 파일과 함수에 매핑하고, covered/unmapped를 표시합니다.

• review.json, comments.json, manifest.json은 SHA-256 감사 증거를 제공합니다.

사이트는 127.0.0.1에만 바인딩되며 코드를 업로드하지 않습니다. 자동 위치 찾기 힌트는 항상 heuristic으로 표시됩니다. 이 힌트는 Codex가 위치를 찾는 데는 도움이 되지만, 최종 의미론적 리뷰 기준을 충족하지는 못합니다.

인터랙티브 데모

저장소에는 MCP light theme를 계승한 이중 언어 인터랙티브 데모 페이지가 포함되어 있습니다. 비식명화된 모의 데이터를 사용해 Codex Mac에서의 전체 워크플로우를 시뮬레이션합니다: 작업 입력, Plan 생성, 실행 확인, 항목별 Build, 전달 및 MCP 호출을 통해 로컬 Review 열기. 완료되면 plan/sub-feature/commit은 일대일 매핑을 유지합니다. 아무 플랜 항목이나 클릭하면 해당 commit이 열리며 changed-file tree, before/after diff, 파일/함수/라인 위치, semantic gate 및 receipt를 제공합니다. 데모는 현재 저장소를 읽거나 데이터를 업로드하지 않습니다.

python3 -m http.server 4173 --directory site

그런 다음 http://127.0.0.1:4173/을 엽니다.

공개 제품 페이지: GitHub Pages

Related MCP server: Git Code Review MCP

원클릭 설치

PyPI 패키지를 설치하고 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

Codex에서 기본 제공되는 $skill-installer를 사용해 해당 workflow skill을 설치합니다:

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

새 skill은 다음 턴부터 사용할 수 있습니다. codex mcp list로 MCP를 확인한 다음, $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을 막지도 않습니다.

이 저장소에는 바로 실행 가능한 프로젝트 수준 구성이 포함되어 있습니다. Codex는 프로젝트가 신뢰된 이후에만 프로젝트 수준 MCP와 hooks를 로드합니다. 처음 사용하거나 hook 내용이 변경된 후에는 Codex에서 /hooks로 특정 hook 정의를 확인하고 신뢰해야 합니다.

공식 근거 자료:

• Codex MCP 구성

• Codex lifecycle hooks

• AGENTS.md 프로젝트 지침

다른 저장소나 사용자 수준 구성에 쓰일 TOML 템플릿은 examples/config.toml에서 볼 수 있습니다. 재사용 가능한 skill은 skills/commit-review에 있습니다.

실행

Python 3.9+면 충분합니다:

PYTHONPATH=src python3 -m commit_review_mcp

또한 명령 진입점을 설치할 수도 있습니다:

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

프로젝트 checkout 형태의 TOML 구성은 다음과 같습니다. Codex는 MCP의 상대 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에 pending commit이 여러 개 있다면 먼저 prepare_commit_history_review / create_commit_history_review를 우선 사용합니다. 결과는 oldest-to-newest 순서로 전환할 수 있는 탭 페이지지만, 각 SHA는 여전히 독립된 semantic result, digest, receipt를 가집니다.

첫 번째 단계에서는 prepare_commit_review 또는 prepare_commit_history_review를 호출합니다. 완성된 plan이 있으면 각 항목에 안정적인 id가 있어야 합니다. plan이 없으면 MCP가 명시적인 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"]
  }
}

도구는 다음을 반환합니다:

• important_files: 함수/제어 흐름, 변경 규모, plan 매핑을 함께 고려해 결정됩니다.

• annotation_contract.targets: 반드시 커버해야 하는 file/function/block/line 포인트 앵커.

• review_template: 바로 채워 넣을 수 있는 최종 payload 골격으로, 라인 번호, hunk index, 함수 이름과 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는 중요 파일 설명, 어떤 target 주석, plan 연결 또는 구체적인 summary가 누락된 payload를 거부합니다. 성공 결과에는 semantic_review.passed = true, url, review_dir, review_sha256, important_files, plan_coverage, comment_counts, receipt가 반드시 포함되어야 합니다.

알림 및 감사 루프

성공적으로 리뷰가 끝나면 Git metadata 하위에 codex-commit-review/receipts/<commit>.json을 기록하며, 작업 트리를 오염시키지 않습니다. history 페이지는 각 commit마다 receipt 파일을 작성하고, 모두 동일한 localhost artifact를 가리키면서 각자의 commit, digest, semantic coverage를 함께 바인딩합니다. 알림은 강제되지만, 이 프로젝트의 온디** 그만의 호출 방식은 사용자가 MCP 호출하지 않아도 turn을 막지는 않습니다. 단, 한번 호출되면 MCP는 heuristic-only 또는 불완전한 payload를 엄격히 거부합니다.

후킹은 로컬 워크플로 알림일 뿐 권한을 확장하지 않습니다. push, merge, 업로드, 코드 삭제 또는 다른 프로세 중단 같은 일은 하지 않습니다. amend/rebase 후 발생한 새 SHA는 history 항목으로 다시 진입하며, 이미 도달할 수 없는 superseded SHA는 더 이상 기록 검토를 요구하지 않습니다. 작업 트리의 커밋되지 않은 변경 사항은 커밋된 diff와 분리되어 표시됩니다.

감사 파일

기본 artifact는 ~/.codex/commit-reviews/<repo>/<commit12>/에 있습니다. 이 파일을 쓰지 못하면 결과에도 안내를 표시하고 시스템 임시 디렉터리로 폴백합니다. 디렉터리에는 다음이 포함됩니다:

• review.json: commit, base, plan 매핑, 중요한 변경 사항, diff 모델, semantic coverage.

• comments.json: Codex, heuristic 및 웹 페이지 로컬의 검토 주석.

• manifest.json: static assets, review 및 comments의 SHA-256.

• 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에서 확인..