file-analysis

Ein persönlicher lokaler MCP, der unstrukturierte Dokumente (pdf docx pptx svg png) in einem angegebenen Ordner liest und bei der Zusammenfassung der Hauptinhalte und der Analyse der Dateistruktur hilft. Er lässt sich an Claude Code · Codex · Claude Desktop anbinden.

Steht dieselbe Tatsache an zwei Stellen, ist AGENTS.md die Quelle.

Dieser Server fasst nicht zusammen

Das ist die wichtigste Designentscheidung.

Wenn der Server auch zusammenfassen würde, müsste er mit seinem eigenen API-Schlüssel erneut ein Modell aufrufen, und der Host erhielte nur das Zusammenfassungsergebnis und könnte die Begründung nicht mehr abgleichen. Damit öffnet sich ein Pfad, über den falsche Zusammenfassungen still durchgehen. Deshalb liefert der Server nur Originaltext und Anker aus.

Related MCP server: file-analyzer

Schnellstart

Erforderliche Umgebung: Python 3.11 oder höher, uv

uv sync --extra dev

uv run python scripts/make_samples.py

uv run python scripts/smoke_stdio.py

Wenn smoke_stdio.py PASS ausgibt, ist der Server in Ordnung — er startet den Server über das echte MCP-Protokoll, prüft die 17 Harness-Konventionen und durchläuft einen kompletten Zyklus von DISCOVER bis SAVED.

Um die Tools mit dem MCP Inspector visuell zu prüfen:

uv run mcp dev src/file_mcp/server.py

Zu analysierenden Ordner festlegen

allowed_roots in config/roots.toml anpassen. Diese Datei ist die Sicherheitsgrenze des Servers.

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

Fügen Sie keine übergeordneten Ordner wie C:/Users/<Benutzer> komplett ein — das wäre praktisch so, als gäbe es keine Schutzvorrichtung. Der Server öffnet Pfade außerhalb dieser Liste unter keinen Umständen.

Host-Verbindung

Claude Code

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

Codex — In ~/.codex/config.toml den Inhalt von config/codex-config.example.toml einfügen.

Claude Desktop — Siehe config/claude_desktop_config.example.json.

Pipeline

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

Die gestrichelte Linie kennzeichnet, was der Server nicht tut. Den Entwurf schreibt das Host-Modell, die Genehmigung erteilt der Mensch.

Es gibt nur ein einziges Schreib-Tool: save_approved_report. Ohne Genehmigungstoken wird nicht geschrieben. scripts/smoke_stdio.py prüft die Liste der Schreib-Tools. Wenn Sie also weitere Tools hinzufügen, muss der Smoke-Test mit angepasst werden.

Die Einstufung richtet sich nicht nach der Dateiendung, sondern nach dem Inhalt

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 öffnet die Dateien nicht, kann die Stufe also nicht festlegen. pdf·svg bleiben B?, und inspect_document öffnet sie und legt die Stufe fest. Behandeln Sie B? im Scan-Ergebnis nicht als festgelegten Wert.

Die Beispieldateien sind so angeordnet, dass sie das belegen — 흐름도.svg hat text-Knoten und ist daher B, 도형만.svg enthält nur Formen und ist daher C. Gleiche Dateiendung, andere Stufe.

Mit der Vision des Host-Modells lesen. Keine zusätzlichen Abhängigkeiten, und die Genauigkeit bei Koreanisch ist besser als bei tesseract. Falls eine Offline-Stapelverarbeitung nötig wird, wird das Tool extract_text_ocr separat ergänzt.

Auch gescannte PDFs werden ohne Rasterizer gelesen. Da eine gescannte Seite vollständig ein eingebettetes Bild ist, genügt es, dieses Bild mit pypdf herauszuziehen — weder PyMuPDF (AGPL) noch poppler-Binaries sind nötig.

Seiten, die nur vektoriell gezeichnet sind, lassen sich nicht herausziehen; dann meldet der Fehler PDF_PAGE_HAS_NO_IMAGE, dass der Mensch einen Screenshot machen muss. Es wird kein stilles leeres Ergebnis zurückgegeben.

Es liefert nur Inhaltsverzeichnis · Blockanzahl · Zeichenzahl · festgelegte Stufe und estimated_read_calls (Anzahl der Aufrufe, die zum vollständigen Lesen nötig sind). Sein Existenzgrund ist, zu verhindern, dass man den Fließtext einer 300-seitigen PDF in den Kontext gießt, nur um ihre Struktur zu erfahren.

Das Öffnen der Datei kostet genauso viel wie bei read_document — gespart wird nicht Zeit, sondern Kontext.

Zitieranker-Konvention

Die Einheiten unterscheiden sich je nach Format, aber die Schnittstelle von read_document ist eine einzige. Alle Formate werden zu einer eindimensionalen Liste von Blöcken flachgezogen, sodass nur start/end nötig sind. Was ein einzelner Block ist, sagt das unit-Feld der Antwort.

Wenn Sie das Ankerformat ändern, müssen grounding.ANCHOR_PATTERN und der Goldenset mit angepasst werden. Bei Abweichungen werden ansonsten einwandfreie Zitate alle durch GR-02 blockiert.

Was der Begründungsabgleich prüfen kann und was nicht

• Ob der Satz einen Anker zitiert — GR-01

• Ob dieser Anker im Dokument existiert — GR-02

• Ob Zahlen·Daten im Originaltext des zitierten Blocks stehen — GR-03

• Ob direkte Zitate (in Anführungszeichen) mit dem Originaltext übereinstimmen — GR-04

• Ob die Zusammenfassung die Bedeutung des Originaltexts korrekt wiedergibt

• Ob Wichtiges ausgelassen wurde

• Ob der zitierte Anker ein angemessener Anker ist (GR-05 ist nur ein Hinweis auf lexikalische Überschneidung)

Ein Bestehen bedeutet nicht „richtig". Das Feld not_verifiable der Antwort macht diese Grenze jedes Mal explizit — wenn man so tut, als hätte man etwas geprüft, das man nicht prüfen kann, glaubt der Mensch „es ist bestanden, also wird es schon stimmen", und das ist gefährlicher als gar keine Prüfung.

Den Originaltext umzuformulieren ist normal. Der Abgleich prüft nur Anker, Zahlen und direkte Zitate.

Speicher-Gate

preview_save_report prüft sowohl Struktur (ST-*) als auch Begründung (GR-*) und stellt das Genehmigungstoken nur aus, wenn kein einziger Fehler vorliegt. Das Token ist sha256(ursprünglicher relativer Pfad + Entwurf), sodass es ungültig wird, sobald man auch nur ein Zeichen am Entwurf ändert — der Pfad, mit einem sauberen Entwurf eine Vorschau zu machen und dann einen anderen Entwurf zu speichern, wird blockiert.

save_approved_report prüft das Gate vollständig erneut. Es vertraut nicht der Aussage des Modells, dass die Vorschau bestanden hat.

Wenn bereits ein Artefakt existiert, wird es überschrieben, und der Hash des vorherigen Inhalts wird im Prüfprotokoll festgehalten. Das Prüfprotokoll (data/outputs/_audit.jsonl) ist append-only.

Harness-Ebenen (CAR)

Unterteilt in die drei Achsen Control–Agency–Runtime. Legen Sie zuerst fest, zu welcher Achse die zu ändernde Datei gehört. Wenn die Achse unklar ist, ist das ein Zeichen für einen falschen Entwurf.

Die detaillierten Verträge und Abhängigkeitsrichtungen je Achse stehen in AGENTS.md Kapitel 2.

Den Fortschritt (wie weit gelesen wurde) hält der Server nicht fest. Das Modell besitzt ihn, und der Server teilt in next_actions nur mit: mit start=N fortfahren. Dadurch ist der Server zustandslos, und die Schreib-Tools bleiben auf das eine Speichern beschränkt.

Selbstprüfung

Unmittelbar bevor eine Antwort zurückgegeben wird, werden Invarianten geprüft; wenn sie verletzt sind, wird statt einer falschen Antwort ein Fehler ausgegeben.

Was hier hängen bleibt, ist kein Problem der Benutzereingabe, sondern ein Server-Bug. Deshalb lautet die Fehlermeldung auch nicht „Bitte prüfen Sie die Datei", sondern „Das ist ein Serverfehler — brechen Sie die Arbeit ab und melden Sie ihn".

Beobachtbarkeit

Jeder Tool-Aufruf wird als eine Zeile in data/traces/YYYY-MM-DD.jsonl festgehalten.

uv run python scripts/trace_report.py

Wichtiger ist, was nicht festgehalten wird. Wenn man echte interne Dokumente analysiert, können die Traces zu Kopien dieser Dokumente werden.

Nicht als Konvention, sondern per Code durchgesetzt und per Test geprüft (tests/test_trace.py). Wenn trace_dir innerhalb von allowed_roots liegt, schaltet sich der Trace von selbst ab — damit der zu analysierende Ordner nicht mit eigenen Aufzeichnungen verschmutzt wird.

Alle 8 Lese-Tools haben readOnlyHint: True, aber der Trace schreibt Dateien.

Dieser Hinweis bedeutet, dass die zu analysierenden Dokumente nicht verändert werden. Der Trace ist ein Instrumentierungsprotokoll außerhalb von allowed_roots und wird über keine Tools exponiert. Als Schreib-Tool ist nur save_approved_report exponiert, und der Smoke-Test prüft diese Liste.

Evaluierung

uv run python scripts/eval_extract.py

Die erwarteten Werte in evals/golden/samples.json werden mit den tatsächlichen Extraktionsergebnissen abgeglichen und das Ergebnis in evals/reports/ festgehalten. pytest sagt nur, ob es „gerade jetzt besteht", dieser Report hält fest, wann was bestanden hat.

Die erwarteten Werte sind von Hand notiert, nachdem man sich angesehen hat, was scripts/make_samples.py in die Dateien gelegt hat. Sie sind keine Kopie der Extraktor-Ausgabe. Wenn man den Goldenset an die Ergebnisse anpasst, lässt die Evaluierung sich selbst bestehen. Ein legitimer Grund zum Ändern ist nur, wenn sich die Ankerkonvention, die Stufendefinition oder der Beispielinhalt geändert hat.

Abhängigkeiten

svg wird mit dem Standard-xml.etree gelesen — 0 Abhängigkeiten.

Warum nicht PyMuPDF (fitz): Die Leistung ist besser, aber es ist AGPL-3.0, sodass die Weitergabe an interne Tools Verteilungsbedingungen mit sich bringt. Falls Tabellenextraktion tatsächlich nötig wird, fügen Sie pdfplumber (MIT) hinzu.

Was nicht committet wird

Legen Sie keine echten zu analysierenden Dokumente in dieses Repository.