위클리-검증 (weekly-verify-mcp)

作成された週次業務報告(.docx)を元データ(.xlsx)と突き合わせて、誤った値・欠落項目・データと食い違う記述を見つけ出して人に返す個人用MCPサーバー。

修正はしない。指摘のみする。 修正は人が行う。

全体設計は docs/검증프로세스.md を参照してください。

現在の状態 — P0〜P5完了・Codex登録済み

Related MCP server: phionyx-pipeline-mcp

検証4階層

このツールの設計全体がこの表から生まれています。

• L1だけでは不十分だ。 L-18の値をL-19行に書き写すと、両方の値が元に存在するため L1は通ってしまう。タスクコードまで合わせて見るL2だけが捉えられる。

• L3がこのツールの存在理由だ。 人が週次報告で間違えるのは大抵数字ではなく 書かなかった項目である。間違った数字は目につくが、存在しない行は目につかない。

• L4は構造的にerrorになり得ない。 harness.Findingがこれを強制し、 tests/test_harness.pyがロックしている。確信のない検査にブロック権限を与えると正常な報告書が 止まり、人が検査器を切ってしまう。

ゲート6種

evals/weekly-verify.yamlがエンジンに要求するもの。uv run python scripts/run_eval.pyで採点します。

座標要求が階層ごとに異なる (G5)

埋められない座標を無理に埋めると、人が見当違いの場所を開いて確認したと思い込んでしまいます。

N/Aは合格ではない

「悪いことをするな」系ゲート(G2・G3・G5)はエンジンが何も出さなければ自動的に 満たされます。 それをPASSと書くと、機能が一つもないエンジンが6つのうち5つを通過したように 見えます。そこで評価する根拠がなければN/Aと書き、N/Aは合格として数えません。

現在の採点結果 (P3時点 — すべて合格)

C01 수치 조작 [OK] 1/1    C05 지연 누락  [OK] 3/3    C09 반올림 [OK] 0/0
C02 날짜 오기 [OK] 1/1    C06 미제출 은폐 [OK] 3/3    C10 정상   [OK] 오탐 0
C03 값 오배치 [OK] 1/1    C07 역행 무시  [OK] 1/1
C04 없는 과제 [OK] 1/1    C08 서술 상충  [OK] 0/0

[PASS] G1_검출률  11/11 (100%)   [PASS] G4_속도   최장 0.1초 / 제한 60초
[PASS] G2_오탐   error 0건       [PASS] G5_근거   좌표 누락 0건 / error 12건
[PASS] G3_심각도  위반 0건        [PASS] G6_계층정확성  11/11 (100%)

G5がerror 12件を検査したのに期待は11件です。C01の汚染が2つの表のセルをそれぞれ 変えたためであり、両方直す必要があるので重複ではありません。

フォルダ

weekly-verify-mcp/
├─ docs/검증프로세스.md      설계 문서 (13개 절)
├─ src/weekly_verify/
│  ├─ harness.py             도구 응답 규약 · Finding · 두 좌표계
│  ├─ sources.py             원본 xlsx 파서 + DATA_ROOT 가드
│  ├─ findings.py            판정 5종 (원본만 보고 계산)
│  ├─ report.py              보고서 docx 파서
│  ├─ claims.py              주장 추출 (규칙 기반, LLM 미사용)
│  ├─ values.py              L1 존재 · L2 정합 + 억제 규칙 3종
│  ├─ completeness.py        L3 누락 검사
│  ├─ narrative.py           L4 서술 상충 (warning 고정)
│  ├─ verify.py              진입점 — 네 계층 조립 + 계층 간 중복 제거
│  ├─ record.py              검증 결과 문서 생성·저장 + 승인 토큰
│  └─ server.py              MCP 도구 10개 · 리소스 2 · 프롬프트 1
├─ scripts/
│  ├─ make_fixtures.py       오염 시나리오 10종 생성
│  ├─ check_fixtures.py      픽스처 자기검증 (30개 검사)
│  ├─ run_eval.py            채점기 (게이트 6종)
│  ├─ smoke_stdio.py         stdio 기동 + 하네스 검사 15종
│  └─ verify_registration.py 설정 파일의 절대경로로 기동 확인
├─ tests/
│  ├─ test_harness.py        하네스 규약 잠금 (16개)
│  ├─ test_eval_contract.py  채점기 검증 — 가짜 엔진 7종 (20개)
│  ├─ test_findings.py       판정 엔진 ↔ 정답지 1건씩 대조 (27개)
│  ├─ test_completeness.py   L3 누락 검사 (31개)
│  ├─ test_values.py         L1·L2 + 억제 규칙 (53개)
│  ├─ test_narrative.py      L4 서술 상충 (43개)
│  └─ test_server_contract.py docstring ↔ 실제 규칙 잠금 (63개)
├─ data/
│  ├─ 원본/                  ← 서버가 읽는 유일한 곳
│  │  ├─ 마스터_주간보고_누적.xlsx
│  │  └─ 제출_2026-W35/ (담당자 6명)
│  ├─ 보고서/ C01~C10.docx   검증 대상
│  └─ 출력/                  검증 결과 기록 (저장 산출물)
├─ config/                   등록 설정 + README
├─ templates/                검증 결과 문서 템플릿
└─ evals/                    🚫 서버 접근 금지 — evals/README.md 참조
   ├─ 정답지_2026-W35.xlsx
   ├─ fixtures_manifest.json 픽스처가 담고 있는 사실
   └─ weekly-verify.yaml     엔진에게 요구하는 정책

manifestとsuiteを分けた理由は関心事が異なるからです — 前者は生成器が作った 事実なのでdocxが変われば一緒に変わり、後者は人が決めた方針なのでdocxとは無関係です。 1つのファイルにまとめると期待値が2か所に生まれてドリフトします。

汚染シナリオ10種

data/보고서/C01~C10.docx。各ファイルの期待検出はevals/fixtures_manifest.jsonにあります。

C05・C06・C07が核心だ

この3つは汚染された報告書の内部整合を維持します。 遅延3件を消しながら要約表の件数も 6→3に一緒に直しました。だから報告書だけ読んでも何の矛盾もなく、元と突き合わせて初めて 明らかになります。削除したL-02・L-08・L-19は、担当者が이슈리스크欄を空欄にしたまさにその3件です。

C09・C10もそれと同じくらい重要だ

誤検知防止テストです。正常な報告書にerrorを出す検査器は誰も使いません。

抑制ルール — 一度のミスを1件として報告する

汚染が1か所だけ変わっても派生値が連鎖で間違います。C02は계획완료일だけ1日ずらしたのに 경과일も一緒に間違い、C03は금주진척률だけ変えたのに증감も間違います。そのまま指摘すると 一度の書き間違いが指摘2件になり、人が2か所を探し回り、指摘件数で深刻度を 推し量ることもできなくなります。

抑制は無条件ではありません。 各ルールごとに抑制される側と抑制されない側をペアで テストしました — 抑制ルールは「これも指摘してほしい」と思う瞬間に静かに崩れます。

検証しない列は宣言する

claims.미검증_열に5種を理由とともに書いてあります (상태は判定ラベルなのでL3所管、 逆行表のO (완료 2026-08-20)形式は自由書式なので突合が不安定、など)。静かに スキップすると「すべて検証した」と読まれるのに、実際には見ていない列があります。

実行

uv sync --extra dev

uv run python scripts/make_fixtures.py

uv run python scripts/check_fixtures.py

uv run python scripts/run_eval.py

uv run python -m pytest -q

uv run python scripts/smoke_stdio.py

uv run python scripts/verify_registration.py

MCPツール10個

高速パス: 9番だけで4階層すべてを実行します。中間ツールは「なぜそう判定したか」を 人に見せるときに使います。

リソース template://verification・report://{보고서}、プロンプト verify_weekly_report。

保存は「指摘記録」である — errorはブロックしない

設計草案には「errorが1つでもあれば保存を拒否する」と書いてありましたが、間違った ルールでした。 保存するのは指摘記録であり、errorがあるときこそ記録が最も必要な ときです。そこでブロックするとツールが役に立たなくなります。

ブロックすべきは別のものでした。

結論は통과・보류・반송のいずれかです。承認トークンは指摘内容から計算されるので、 指摘が1つでも変わるとトークンが食い違い保存が拒否されます。

この2条件はsave_approved_verificationのツール説明に明記されており、 tests/test_server_contract.pyが説明と実際のコードを突き合わせてロックします — モデルはコードを 読まないので、説明にないルールはモデルにとって存在しません。

登録 (P5)

Codex登録完了 — ~/.codex/config.toml に [mcp_servers.weekly-verify] が 入っています (バックアップ: config.toml.bak-2026-08-26)。Codexを再起動するとツールが表示されます。

Claude Desktopは%APPDATA%\Claudeが部分ブロックパスのためツールが書き込めません。 config/claude_desktop_config.example.json の内容を直接マージしてください — 意図されたブロックであり、迂回しません。

commandは必ず絶対パスでなければなりません。デスクトップアプリはログインシェルのPATHを 引き継がないため、uvとだけ書くとターミナルでは動くのにアプリではサーバーが起動しません。

uv run python scripts/verify_registration.py

例示設定2種と実際に登録されたライブ設定まで3つを確認します。例示が合っていても 実際の登録が間違っていればアプリでは起動しないからです。

データについて

data/のすべてのデータは実習用の仮想(架空)データです。担当者名は古典小説の人物名、 タスクは実在しない物流自動化テーマです。社内の実データ・個人情報は一切 含まれておらず、実際の社内ファイルをこのフォルダに入れないでください。

元データはmx-agentic-ai-day1-prdから取得しました。