file-analysis

指定したフォルダの非構造化ドキュメント（pdf docx pptx svg png）を読み取り、主要な内容の要約とファイル構造の分析を支援する個人用ローカルMCPです。Claude Code・Codex・Claude Desktopに接続します。

同じ事実が2箇所にある場合は、AGENTS.mdが原本です。

このサーバーは要約しません

最も重要な設計上の決定です。

サーバーが要約まで行うと、サーバーが自分のAPIキーでモデルを再度呼び出す必要があり、ホストは要約結果だけを受け取って根拠を照合できなくなります。誤った要約が静かに通過する経路が開かれます。そこでサーバーは原文とアンカーのみを提供します。

Related MCP server: file-analyzer

クイックスタート

必須環境: Python 3.11以上、uv

uv sync --extra dev

uv run python scripts/make_samples.py

uv run python scripts/smoke_stdio.py

smoke_stdio.pyがPASSを出力すればサーバーは正常です — 実際のMCPプロトコルでサーバーを起動してハーネス規約17個を検査し、DISCOVERからSAVEDまで一周します。

MCP Inspectorでツールを目視確認するには:

uv run mcp dev src/file_mcp/server.py

分析するフォルダの指定

config/roots.tomlのallowed_rootsを編集します。このファイルがサーバーのセキュリティ境界です。

allowed_roots = [
  "data/samples",
  "C:/Users/<사용자>/Desktop/분석대상",
]

C:/Users/<ユーザー>のように上位フォルダを丸ごと入れないでください — ガードが事実上ないのと同じになります。サーバーはこのリスト外のパスをいかなる場合も開きません。

ホスト接続

Claude Code

claude mcp add file-analysis -- uv --directory "<이-저장소를-클론한-절대경로>" run python src/file_mcp/server.py

Codex — ~/.codex/config.tomlにconfig/codex-config.example.tomlの内容を貼り付けます。

Claude Desktop — config/claude_desktop_config.example.jsonを参照。

パイプライン

flowchart LR
    S["scan_folder<br/><i>추정 등급 B?</i>"] --> I["inspect_document<br/><i>확정 등급 A/B/C</i>"]
    I --> P["build_analysis_prompt<br/><i>앵커 붙은 원문</i>"]
    P --> D(["초안 작성<br/><i>호스트 모델</i>"])
    D --> G["check_summary_grounding<br/><i>GR-01 … GR-04</i>"]
    G --> V["preview_save_report<br/><i>승인 토큰 발급</i>"]
    V --> H{{"사람의 승인"}}
    H --> W["save_approved_report<br/><i>유일한 쓰기</i>"]

    classDef server fill:#ddf4ff,stroke:#54aeff,color:#1f2328
    classDef notserver fill:#ffffff,stroke:#afb8c1,stroke-dasharray:5 4,color:#656d76
    classDef write fill:#fff8c5,stroke:#d4a72c,color:#1f2328
    class S,I,P,G,V server
    class D,H notserver
    class W write

点線はサーバーが行わないことです。下書きはホストモデルが書き、承認は人間が行います。

書き込みツールはsave_approved_reportの1つだけです。 承認トークンなしでは書き込みません。scripts/smoke_stdio.pyが書き込みツールのリストを検査するため、ツールを追加したらスモークテストも一緒に修正する必要があります。

グレードは拡張子ではなく内容で決まります

flowchart TD
    X["파일"] --> Y{"확장자"}
    Y -->|"docx · pptx"| A["<b>등급 A</b><br/>구조까지"]
    Y -->|"png"| C1["<b>등급 C</b><br/>이미지 판독"]
    Y -->|"pdf"| PQ{"공백 제거 후 페이지 텍스트<br/>8자 이상?"}
    Y -->|"svg"| SQ{"내용 있는<br/>text 노드?"}
    PQ -->|"있음"| B1["<b>등급 B</b><br/>본문만"]
    PQ -->|"없음"| C2["<b>등급 C</b><br/>스캔 PDF"]
    SQ -->|"있음"| B2["<b>등급 B</b><br/>본문만"]
    SQ -->|"없음"| C3["<b>등급 C</b><br/>그림"]

    classDef ga fill:#dafbe1,stroke:#2da44e,color:#1f2328
    classDef gb fill:#ddf4ff,stroke:#54aeff,color:#1f2328
    classDef gc fill:#fff8c5,stroke:#d4a72c,color:#1f2328
    class A ga
    class B1,B2 gb
    class C1,C2,C3 gc

scan_folderはファイルを開かないため、グレードを確定できません。pdf・svgはB?のままで、inspect_documentが開いて確定します。スキャン結果のB?を確定済みの値として読まないでください。

サンプルはこれを証明するように配置されています — 흐름도.svgはtextノードがあるためB、도형만.svgは図形のみのためCです。同じ拡張子、異なるグレード。

ホストモデルのビジョンで読み取ります。追加の依存関係がなく、韓国語の精度はtesseractより優れています。オフラインのバッチ処理が必要になったら、extract_text_ocrツールを別途追加します。

スキャンPDFもラスタライザなしで判読されます。 スキャンページは全体が1つの埋め込み画像であるため、pypdfでその画像を取り出せばよいのです — PyMuPDF(AGPL)もpopplerバイナリも必要ありません。

ベクターのみで描画されたページは取り出せず、その場合はPDF_PAGE_HAS_NO_IMAGEエラーが「人間が画面キャプチャする必要がある」と通知します。静かに空の結果を返しません。

目次・ブロック数・文字数・確定グレードとestimated_read_calls（全体を読むのに必要な呼び出し回数）のみを返します。300ページのPDFの概要を知るために本文をコンテキストに流し込むことを防ぐのが存在理由です。

ファイルを開くコストはread_documentと同じです — 節約されるのは時間ではなくコンテキストです。

引用アンカー規約

形式ごとに単位は異なりますが、read_documentのインターフェースは1つです。すべての形式をブロックの1次元リストにフラット化するため、start/endだけを使えばよいのです。1つのブロックが何を指すかは、応答のunitが教えてくれます。

アンカー形式を変更したら、grounding.ANCHOR_PATTERNとゴールデンセットも一緒に修正する必要があります。ずれると、正常な引用がすべてGR-02でブロックされます。

根拠照合が確認できることとできないこと

• 文がアンカーを引用しているか — GR-01

• そのアンカーがドキュメントに存在するか — GR-02

• 数値・日付が引用ブロックの原文にあるか — GR-03

• 直接引用（引用符内）が原文と一致するか — GR-04

• 要約が原文の意味を正しく伝えているか

• 重要なことを見落としていないか

• 引用したアンカーが適切なアンカーか （GR-05は語彙の重複ヒントにすぎない）

通過が「正しい」という意味ではありません。 応答のnot_verifiableがこの限界を毎回明示します — 確認できないことを確認したふりをすると、人間が「通過したから正しいだろう」と信じてしまい、それは検証がないことよりも危険です。

原文を言い換えて書くことは正常です。照合はアンカー・数値・直接引用のみを見ます。

保存ゲート

preview_save_reportは構造（ST-*）と根拠（GR-*）の両方を確認し、エラーが1つもないときだけ承認トークンを発行します。トークンはsha256(元の相対パス + 下書き)であるため、下書きを1文字でも修正すると無効になります — きれいな下書きでプレビューして別の下書きを保存する経路がブロックされます。

save_approved_reportはゲートをすべて再度確認します。プレビューが通過したというモデルの言葉を信じません。

既存の成果物があれば上書きし、以前の内容のハッシュを監査記録に残します。監査記録（data/outputs/_audit.jsonl）はappend-onlyです。

ハーネス階層（CAR）

Control–Agency–Runtimeの3軸に分けます。変更するファイルがどの軸かを先に決めてください。 軸が不明確なら、設計が間違っているサインです。

軸別の詳細契約と依存方向はAGENTS.md 2章にあります。

進行状況（どこまで読んだか）はサーバーが保持しません。 モデルが所有し、サーバーはnext_actionsにstart=Nで続きからとだけ知らせます。そのためサーバーはステートレスで、書き込みツールが保存の1つに保たれています。

自己検証

応答を返す直前に不変条件を確認し、壊れていたら誤った回答の代わりにエラーを出します。

ここで引っかかるのはユーザー入力の問題ではなくサーバーのバグです。そのためエラーメッセージも「ファイルを確認してください」ではなく「これはサーバーの欠陥なので作業を中止して報告してください」と言います。

観測可能性

ツール呼び出し1つがdata/traces/YYYY-MM-DD.jsonlに1行として残ります。

uv run python scripts/trace_report.py

残さないことの方が重要です。 実際の社内ドキュメントを分析すると、トレースがそのドキュメントのコピーになり得ます。

規約ではなくコードで強制し、テストで確認します（tests/test_trace.py）。trace_dirがallowed_roots内にあると、トレースが自動的にオフになります — 分析対象フォルダを自分の記録で汚染しないためです。

読み取りツール8つがすべてreadOnlyHint: Trueなのに、トレースはファイルを書き込みます。

そのヒントは分析対象ドキュメントを変更しないという意味です。トレースはallowed_rootsの外の計測ログであり、ツールとして公開もされません。書き込みツールとして公開されるのはsave_approved_reportの1つだけで、スモークテストがこのリストを検査します。

評価

uv run python scripts/eval_extract.py

evals/golden/samples.jsonの期待値と実際の抽出結果を照合し、結果をevals/reports/に残します。pytestは「今通っているか」しか教えてくれず、このレポートはいつ何が通ったかを残します。

期待値は、scripts/make_samples.pyがファイルに何を入れたかを見て手で書いたものです。抽出器の出力をコピーしたものではありません。 ゴールデンセットを結果に合わせて修正すると、評価が自分自身を通してしまいます。修正すべき正当なケースは、アンカー規約・グレード定義・サンプル内容が変わったときだけです。

依存関係

svgは標準のxml.etreeで読み取ります — 依存関係0。

PyMuPDF（fitz）を使わない理由: 性能は良いですがAGPL-3.0のため、社内ツールに入れると配布条件が発生します。表の抽出が実際に必要になったら、pdfplumber（MIT）を追加してください。

コミットしないもの

分析対象の実際のドキュメントをこのリポジトリ内に置かないでください。