Dateianalyse-MCP (file-insight-mcp)

Dies ist ein persönlicher lokaler MCP-Server, der unstrukturierte Dokumente in einem angegebenen Ordner liest, deren Struktur analysiert und eine Zusammenfassung pro Dokument sowie einen Gesamtzusammenfassungsbericht für den Ordner erstellt.

Alle Dokumente im Ordner data/sample_docs/ dieses Pakets sind synthetische Daten, die nur für Demonstrationszwecke erstellt wurden.

Referenzgrundlage

• Serverstruktur (FastMCP, stdio, Kombination mehrerer MCP-Server): https://github.com/kyopark2014/mcp

• Harness-Konventionen (schrittweises stage/next_actions, Begründungsanker, Genehmigungsgrenzen): Wiederverwendung des Ansatzes aus dem verwandten Projekt personal-meeting-mcp-training

• Liste der Harness-Engineering-Prinzipien: https://github.com/walkinglabs/awesome-harness-engineering (Kontextbudget, Vorabgenehmigungs-Hooks, deterministische Eval, statische Sicherheitsscanner – selektiv auf die Größe dieses Projekts angewendet)

• MCP Python SDK: https://github.com/modelcontextprotocol/python-sdk

Related MCP server: file-analyzer

Was dieser Server tut

1. Er scannt die Struktur des festgelegten Zielordners (data/sample_docs/).

2. Er liest nur Dokumente mit zulässigen Erweiterungen (.txt .md .csv .log).

3. Er extrahiert aus den Dokumenten regelbasiert das Inhaltsverzeichnis (Überschriftenstruktur), Datumsangaben, Zahlen und Kandidaten für Schlüsselbegriffe.

4. Er erstellt einen zusammengefassten Prompt, der alle Dokumente kombiniert. Die Zusammenfassung selbst erstellt der Host-LLM (Claude/Codex); dieser MCP ruft keine LLM-API auf.

5. Er validiert die Struktur des erstellten Zusammenfassungsberichts und prüft, ob die erwähnten Dateinamen tatsächlich existieren.

6. Er speichert den Bericht erst, nachdem der Benutzer ihn ausdrücklich genehmigt hat.

Schnellstart

Erforderliche Umgebung: Python 3.11 oder höher, uv

uv sync --extra dev

Nach der Installation prüfen, ob alle vier Befehle im Abschnitt Validierung unten bestanden werden.

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

uv run mcp dev src/file_insight_mcp/server.py

Projektstruktur

Domänenlogik und Tool-Konventionen sind getrennt, sodass Änderungen an den Validierungsregeln die Tool-Ebene nicht berühren.

Empfohlener Ablauf

SCAN → LIST → READ → EXTRACT → DRAFT → CHECK → PREVIEW → [사용자 승인] → SAVED

Ressourcen und Prompts

Harness-Design

Dieser Server behandelt nicht nur die Funktionalität, sondern auch die Art und Weise, wie das Modell die Tools verwendet, als Designgegenstand.

• Jede Antwort enthält stage und next_actions, sodass das Modell allein anhand der Antwort das nächste Tool auswählt. blocking: true ist ein Hinweis, dass dieser Schritt nicht übersprungen werden soll. Was das Speichern tatsächlich blockiert, sind die Strukturvalidierung und das Genehmigungstoken; der Hinweis übernimmt diese Rolle nicht.

• Fehler werden als ToolFailure mit Ursachencode, Wiederherstellungsmethode und auswählbaren Werten zurückgegeben. Ziel ist es, dass das Modell sich selbstständig erholen kann, ohne erneut nachfragen zu müssen.

• Die Argumentschemata bleiben flach ({"relative_path": "..."}). Wenn Pydantic-Modelle als Argumenttypen verwendet würden, würden sie als {"params": {...}} verschachtelt und die Aufrufstruktur würde sich ändern.

• Rückgabewerte sind Pydantic-Modelle, sodass outputSchema automatisch erzeugt wird.

• Alle Tools haben readOnlyHint / destructiveHint, damit der Host für Schreib-Tools eine andere Genehmigungs-UI anzeigen kann.

• Nur eindeutige Prüfungen (Struktur) blockieren das Speichern; heuristische Prüfungen (Dateinamenabgleich) werden nur als Warnung gemeldet.

Kontextbudget

Nach dem Prinzip „Das Kontextfenster ist kein Ablageort, sondern ein Arbeitsgedächtnisbudget" haben alle Tools eine explizite Obergrenze für die Antwortgröße.

• scan_folder_structure: Wenn MAX_SCAN_ENTRIES (500) überschritten wird, wird mit truncated: true informiert und gekürzt.

• read_document: Dateien über MAX_FILE_BYTES (200KB) werden nicht vollständig gelesen; stattdessen wird per Fehler darauf hingewiesen, nur einen Teil mit read_document_chunk zu lesen.

• extract_key_terms: Begrenzt die Anzahl der Einträge pro Kategorie mit max_terms.

• preview_save_report: include_preview=False ist der Standardwert, sodass ein bereits vorhandener Entwurf nicht erneut in die Antwort aufgenommen wird. Nur wenn er aufgenommen werden soll, wird die Länge mit max_preview_chars begrenzt.

• harness.truncate() / harness.number_lines(): Kürzungsstatus und Zitatanchor (Zeilennummer) werden immer explizit angegeben, damit das Modell nicht raten muss, ob es sich um den vollständigen oder einen Teilinhalt handelt.

Sicherheitsgrenzen

• Der Server behandelt nur security.TARGET_DIR (data/sample_docs/). Auch mit .., absoluten Pfaden, Laufwerksbuchstaben oder symbolischen Links kann nicht darauf zugegriffen werden (security.safe_relative_path).

• Dateien außerhalb der Erweiterungs-Allowlist (.txt .md .csv .log) werden nicht gelesen. Ausführbare/Skript-Erweiterungen sind immer vom Ziel ausgeschlossen.

• Wenn die Dateigröße MAX_FILE_BYTES (200KB) überschreitet, wird nicht vollständig gelesen, sondern per Fehler darauf hingewiesen.

• Versteckte Dateien und Ordner, deren Name mit . beginnt, werden vom Scan ausgeschlossen.

• Das einzige Schreib-Tool ist save_approved_report; es funktioniert nur, wenn das von preview_save_report ausgestellte Hash-Token (report_id, Inhalt) übereinstimmt.

• Dieser Server liest nur Dokumente. Wenn Code- oder Shell-Ausführungsaufrufe wie eval/exec/subprocess in den Quellcode gelangen, schlägt scripts/validate_package.py fehl.

Validierung

uv run pytest -q
uv run python scripts/smoke_stdio.py
uv run python scripts/run_evals.py
uv run python scripts/validate_package.py

Die vier Befehle haben unterschiedliche Prüfbereiche, daher müssen alle bestanden werden.

run_evals.py enthält den gesamten Speicherablauf, einschließlich der Fälle, in denen das Speichern bei korrektem und bei falschem Genehmigungstoken jeweils erfolgreich bzw. abgelehnt wird. Bei jedem Fehlerfix wird ein Fall, der den Fehler reproduziert, als eine Zeile zu evals/cases.jsonl hinzugefügt. Die Fallgrammatik ist in evals/README.md beschrieben.

Wenn ein anderer Ordner analysiert werden soll

Aus Sicherheitsgründen ist der Zielordner in diesem Projekt auf TARGET_DIR (das data/sample_docs/ im Paket) in src/file_insight_mcp/security.py festgelegt. Um einen tatsächlichen Arbeitsordner zu analysieren:

1. TARGET_DIR auf den gewünschten absoluten Pfad ändern oder so anpassen, dass er per Umgebungsvariable injiziert wird.

2. Die tatsächlich im Ordner vorhandenen Erweiterungen in ALLOWED_EXTENSIONS aufnehmen.

3. Zuerst prüfen, ob es keine sensiblen Unterordner gibt (Anmeldeinformationen, personenbezogene Daten usw.).

Claude Desktop-Verbindung

ABSOLUTE_PROJECT_PATH in config/claude_desktop_config.example.json durch den absoluten Pfad dieses Ordners ersetzen und dann in den Claude Desktop-Einstellungen übernehmen. Die App muss vollständig beendet und dann neu gestartet werden.

Designprinzipien

• Der MCP ruft keine separate LLM-API auf. Claude oder Codex erstellt die Zusammenfassungssätze; dieser MCP ist für Originaltext, Struktur, Validierung und Speicherung zuständig.

• Es werden keine Dateinamen, Zahlen oder Daten erfunden, die nicht im Dokument bestätigt wurden; der Begründungsprüfer gleicht mechanisch ab.

• Für die endgültige Speicherung müssen sowohl das im Vorschaubildschirm ausgestellte Genehmigungstoken als auch die ausdrückliche Genehmigung des Benutzers vorliegen.

• Domänenlogik (core, outline, grounding) und Tool-Konventionen (server, harness, security) sind getrennt.