Skip to main content
Glama

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

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

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

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


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

段階

内容

状態

P0

骨格 + 汚染データセット

✅

P1

採点器 (run_eval.py) — 判定エンジンより先に

✅

P2

元パーサー + 判定5種エンジン + L3欠落

✅

P3

主張抽出 + 値突合(L1・L2) + 記述矛盾(L4)

✅

P4

MCPツール10個ラッピング + スモーク

✅

P5

Codex登録 + 起動確認

✅


Related MCP server: phionyx-pipeline-mcp

検証4階層

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

階層

問うこと

判定

深刻度

L1存在

この値が元にあるか

コード

error

L2整合

該当タスクの該当フィールドと一致するか

コード

error

L3欠落

元から出るべき判定が抜けているか

コード

error

L4解釈

値は正しいが記述が食い違うか

人

warning 固定

  • 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で採点します。

ID

要求

ブロック

G1検出率

C01〜C07 error級汚染を一つも見逃さない

✅

G2誤検知

正常報告書(C10)にerrorを出さない

✅

G3深刻度

C08・C09にerrorを出さない

✅

G4速度

報告書1件60秒以内

✅

G5根拠

すべてのerrorが階層別必須座標を埋める

✅

G6階層正確性

見つけた指摘を正しい階層に分類する

⬜ 観察用

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

階層

報告書位置

元位置

理由

L1

✅

—

元にない値なので指し示すセルがない

L2

✅

✅

両方にある

L3

—

✅

報告書にない項目なので指し示す位置がない

L4

✅

—

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

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にあります。

コード

タイプ

仕込む内容

期待

C01

数値改ざん

L-01 今週進捗率 80 → 90

error L2

C02

日付誤り

L-08 計画完了日を1日ずらす

error L2

C03

値の配置ミス

L-18の60をL-19行に (正解40)

error L2

C04

存在しないタスク

L-31 行を追加

error L1

C05

遅延漏れ

遅延 6→3件、要約件数も一緒に調整

error L3 ×3

C06

未提出隠蔽

未提出表を削除 + 前週値で埋める

error L3 ×3

C07

逆行無視

逆行1件に言及しない

error L3

C08

記述矛盾

64日遅延を「順調に進行中」

warning L4

C09

四捨五入

62.2% → 62%

warning

C10

正常

汚染なし

error 0件

C05・C06・C07が核心だ

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

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

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


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

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

#

ルール

抑制されない場合

1

タスクが元にない場合はその行の他の値は突合しない

— (L1指摘1件で終了)

2

未提出タスクの今週値は突合しない

前週値はそのまま突合する

3

派生値は材料がすでに指摘されていればスキップする

材料が正しければ派生値の誤りを指摘する

4

L3が扱った区分の集計件数指摘を抑止する

項目は正しく件数だけ間違っていれば指摘する

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

検証しない列は宣言する

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個

#

ツール

段階

書き込み

1

list_verification_targets

DISCOVER

2

read_source_data

SOURCE

3

compute_baseline_findings

BASELINE

4

read_report

REPORT

5

extract_report_claims

CLAIM

6

verify_claims

VERIFY (L1·L2)

7

check_completeness

COMPLETE (L3)

8

flag_narrative_risks

NARRATE (L4)

9

preview_verification_report

PREVIEW

10

save_approved_verification

SAVED

✅

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

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

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

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

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

#

拒否条件

理由

1

承認トークンが現在の指摘内容と不一致

人が確認していない内容がファイルに残るのを防ぐ

2

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から取得しました。

Available Tools

10 tools
check_completenessA
Read-onlyIdempotent

원본에서 나와야 할 판정이 보고서에 빠졌는지 봅니다 (L3).

이 검사가 이 도구의 존재 이유입니다. 사람이 주간보고에서 틀리는 것은 대개 숫자가 아니라 안 쓴 항목입니다. 틀린 숫자는 눈에 띄지만 없는 줄은 눈에 띄지 않습니다.

언급 여부를 두 수준에서 봅니다. 상세 표가 있으면 표에 없는 과제코드가 누락이고, 집계만 했으면 건수가 원본과 맞는지 봅니다 — 집계만 하고 개별 항목을 나열하지 않는 것은 정상적인 보고 방식이기 때문입니다.

Returns: 지적응답: L3 지적 목록. 보고서에 없는 항목이므로 보고서 좌표는 비어 있고 원본 좌표만 채워집니다.

Examples: - 사용: "빠뜨린 지연 과제가 있나요?" - 사용하지 않음: 적힌 값이 맞는지 보려면 → verify_claims

Inputs: 보고서 (required), 전주차, 기준주차, 원본디렉터리. Returns: info, error, stage, status, +4 more

compute_baseline_findingsA
Read-onlyIdempotent

원본 데이터만으로 판정 5종(신규완료·지연·일정변경·역행·미제출)을 계산합니다.

이 도구는 보고서를 입력으로 받지 않습니다. 그것이 핵심입니다. 보고서를 보고 판정을 계산하면 보고서에 이끌려, 보고서에서 빠진 항목을 영영 찾지 못합니다.

판정은 날짜·완료여부 계산으로만 합니다. 담당자가 적은 이슈리스크 텍스트는 판정에 쓰지 않습니다 — 이슈를 적지 않은 지연 과제를 잡아내는 것이 이 도구의 존재 이유입니다.

Returns: 판정응답: 구분별 건수와 판정 목록. 각 판정은 원본 좌표를 갖습니다.

Examples: - 사용: "이번 주에 보고되어야 할 변동이 뭔가요?" - 사용하지 않음: 보고서와 대조하려면 → check_completeness / verify_claims

Inputs: 구분, 전주차, 기준주차, 원본디렉터리. Returns: stage, status, 구분별, 기준일, +3 more

extract_report_claimsA
Read-onlyIdempotent

보고서에서 원본과 대조 가능한 주장을 뽑습니다.

값은 원문 문자열 그대로 담습니다. 숫자로 바꾸거나 정규화하지 않습니다 — 62 를 62.0 으로 바꿔 놓으면 반올림 오류를 반올림 오류로 지적할 수 없습니다.

표 기반 보고서는 열 이름 → 필드 매핑으로 결정적으로 뽑힙니다. 추측이 개입하지 않으므로 같은 보고서는 항상 같은 주장을 냅니다.

미검증열 에는 의도적으로 검증하지 않는 열과 그 이유가 담깁니다. 조용히 건너뛰면 "전부 검증했다"로 읽히기 때문입니다.

Returns: 주장응답: 총 주장 수, 필드별 개수, 주장 목록(잘릴 수 있음).

Examples: - 사용: "보고서가 L-08 계획완료일을 뭐라고 적었나요?" (필드="계획완료일") - 사용하지 않음: 맞는지 틀리는지 판정하려면 → verify_claims

Inputs: 보고서 (required), 필드. Returns: stage, status, 잘림, 주장, +4 more

flag_narrative_risksA
Read-onlyIdempotent

값은 맞지만 서술이 데이터와 어긋나는 후보를 표시합니다 (L4).

64일 지연된 과제를 "순조롭게 진행 중"이라고 쓴 보고서는 숫자가 전부 정확합니다. L1·L2·L3 어디에도 걸리지 않는데, 읽는 사람은 완전히 잘못된 인상을 받습니다.

이 검사는 판단하지 않고 표시만 합니다. 그 서술이 부적절한지는 문맥에 달렸고 기계는 그 차이를 모릅니다. 그래서 결과는 항상 warning 이며 저장을 막지 않습니다. 확신하지 못하는 검사에 차단 권한을 주면 정상 보고서가 막히고, 사람이 검사기를 꺼 버립니다.

표는 보지 않습니다. 표의 칸은 값이고 값의 정합은 L2 소관입니다.

Returns: 지적응답: L4 후보 목록. error 는 구조적으로 나올 수 없습니다.

Examples: - 사용: "지연된 과제를 괜찮다고 써 놓은 데가 있나요?" - 사용하지 않음: 숫자 대조 → verify_claims

Inputs: 보고서 (required), 전주차, 기준주차, 원본디렉터리. Returns: info, error, stage, status, +4 more

list_verification_targetsA
Read-onlyIdempotent

검증할 수 있는 보고서와 대조 기준이 되는 원본 파일 목록을 조회합니다.

검증 작업의 출발점입니다. 여기서 얻은 파일명을 다른 도구에 넘깁니다.

Returns: 대상목록응답: 원본 엑셀 목록과 .docx 보고서 목록.

Examples: - 사용: "검증할 수 있는 보고서가 뭐가 있나요?" - 사용하지 않음: 이미 파일명을 알고 바로 검증할 때 → preview_verification_report

Inputs: 원본디렉터리, 보고서디렉터리. Returns: stage, status, 보고서, next_actions, +2 more

preview_verification_reportA
Read-onlyIdempotent

네 계층을 모두 돌려 지적 목록과 저장 대상, 승인 요청 문장을 돌려줍니다.

이 도구 하나로 L1·L2·L3·L4 전부를 검사합니다. 중간 도구들은 "왜 그렇게 판정했는지"를 사람에게 보여줄 때 씁니다.

승인토큰 은 지적 내용에서 계산됩니다. 지적이 하나라도 달라지면 토큰이 달라지므로, 사용자가 확인한 내용과 저장될 내용이 같다는 것을 보장할 수 있습니다.

approval_request 문장을 사용자에게 그대로 보여 주고, 명시적으로 승인받은 뒤에만 save_approved_verification 을 호출하십시오.

Returns: 미리보기응답: 지적 목록, 저장 경로, 승인토큰, 지금 쓸 수 있는 결론 후보.

Examples: - 사용: "이 보고서 검증해 주세요" - 사용하지 않음: 사용자 승인 없이 저장 → 절대 금지

Inputs: 보고서 (required), 전주차, 기준주차, 원본디렉터리. Returns: info, error, stage, status, +9 more

read_reportA
Read-onlyIdempotent

검증 대상 보고서(.docx)의 구조를 표와 문단으로 읽습니다.

각 표에 직전 제목을 붙여 돌려줍니다. "이 표가 무엇에 대한 표인가"를 알아야 지연 표에서 빠진 과제를 찾을 수 있기 때문입니다.

Returns: 보고서응답: 표별 제목·헤더·행수와 보고서에 등장한 과제코드 목록.

Examples: - 사용: "이 보고서에 어떤 표가 들어 있나요?" - 사용하지 않음: 값을 대조하려면 → extract_report_claims → verify_claims

Inputs: 보고서 (required). Returns: 표, stage, status, 파일, +4 more

read_source_dataA
Read-onlyIdempotent

원본 엑셀을 읽어 정규화 사실표로 만들고 그 규모를 돌려줍니다.

제출본에는 주차 열이 없으므로 기준주차를 스탬프로 찍어 적재합니다. 모든 행은 자기 좌표(파일·시트·행)를 들고 다니며, 그것이 나중에 지적의 근거가 됩니다.

Returns: 원본데이터응답: 행 수, 주차별 과제 수, 미제출 과제코드 목록.

Examples: - 사용: "원본에 몇 개 과제가 들어와 있나요?" / "누가 안 냈나요?" - 사용하지 않음: 판정 5종이 필요할 때 → compute_baseline_findings

Inputs: 전주차, 기준주차, 원본디렉터리. Returns: stage, status, 전주차, next_actions, +6 more

save_approved_verificationA
Idempotent

사용자가 승인한 검증 결과를 파일로 저장합니다. 유일한 쓰기 도구입니다.

사용자가 명시적으로 승인한 뒤에만 호출하십시오. 승인 없이 호출하지 마십시오.

저장하는 것은 지적 기록입니다. 보고서를 고치지 않습니다. 그래서 error 가 있다는 이유만으로 저장을 막지는 않습니다 — 오히려 error 가 있을 때 기록이 가장 필요합니다.

두 경우에만 거부합니다.

  1. 승인토큰이 현재 지적 내용과 맞지 않을 때. 사람이 확인하지 않은 내용이 파일로 남는 것을 막습니다. preview_verification_report 를 다시 호출하십시오.

  2. error 가 있는데 결론을 '통과' 로 적으려 할 때. 그것은 기록이 아니라 거짓입니다. '보류' 또는 '반송' 을 쓰십시오.

Returns: 저장응답: 저장 경로와 기록된 결론.

Examples: - 사용: 사용자가 "보류로 저장해 주세요"라고 승인한 뒤 - 사용하지 않음: 미리보기를 보여 주기 전 / 승인 문구가 없을 때

Inputs: 결론 (required), 보고서 (required), 승인토큰 (required), 전주차, +2 more. Returns: info, error, stage, status, +4 more

verify_claimsA
Read-onlyIdempotent

보고서의 값을 원본과 대조합니다. L1(원본에 없음) · L2(원본과 다름).

L1 만으로는 부족합니다. L-18 의 값을 L-19 행에 옮겨 적으면 두 값 다 원본에 존재하므로 L1 은 통과합니다. 과제코드까지 맞춰 보는 L2 만이 잡습니다.

한 번의 실수가 여러 값을 틀리게 만들므로 억제 규칙이 있습니다 — 원본에 없는 과제는 그 행의 다른 값을 대조하지 않고, 미제출 과제의 금주 값은 대조하지 않으며, 파생 값(증감·경과일)은 재료가 이미 지적되면 건너뜁니다. 한 번 잘못 적은 것을 두 건으로 보고하지 않기 위한 것입니다.

반올림(0.5 이내) 차이는 error 가 아니라 warning 입니다.

Returns: 지적응답: L1·L2 지적 목록. 각 지적은 보고서 좌표와 원본 좌표를 갖습니다.

Examples: - 사용: "보고서 숫자가 원본과 맞나요?" - 사용하지 않음: 빠진 항목을 찾으려면 → check_completeness

Inputs: 보고서 (required), 전주차, 기준주차, 원본디렉터리. Returns: info, error, stage, status, +4 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.6/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool owns a distinct stage or verification level (L1/L2 vs L3 vs L4), and the descriptions explicitly cross-reference when another tool should be used instead. The aggregate preview tool is clearly positioned as a convenience wrapper over the intermediate tools, so there is no real ambiguity.

    Naming Consistency5/5

    All tool names follow a consistent snake_case verb_noun pattern with specific, informative verbs: list, read, compute, extract, verify, check, flag, preview, save. The naming style is uniform and each name accurately predicts the tool's operation.

    Tool Count5/5

    Ten tools map cleanly onto the stages of the verification pipeline: discover targets, load source, compute expected findings, parse report, extract claims, verify values, check completeness, flag narrative risks, preview, and save. The count is well-scoped and every tool has a clear purpose.

    Completeness5/5

    The set covers the full verification lifecycle from target discovery through source normalization, report parsing, claim extraction, multi-level checks, all-level preview, and an approval-gated save. There are no obvious dead ends: the only write tool is intentionally gated, and every intermediate tool feeds into the preview/save flow.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables verification of AI coding agent self-reports against git diff truth and a deterministic gate, producing pass/regenerate/reject directives to ensure claimed work matches actual changes.
      6
      AGPL 3.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Deterministic verification for AI-generated analysis. Reconciliation, consistency and Excel-integrity checks that stop the line when the numbers don't add up.
      1
      MIT