file-analysis-mcp

Liest unstrukturierte Dokumente (pdf, docx, pptx, txt, svg, png, csv, xlsx) in einem angegebenen Ordner, erfasst deren Struktur und ist ein persönlicher lokaler MCP, der ohne Genehmigung nichts speichert.

Beispiel aus der Praxis

Tatsächliches Ergebnis, ausgeführt gegen den enthaltenen synthetischen Beispielordner (sample_docs/).

list_folder_contents()
→ count: 8, entries: data.csv, diagram.svg, notes.docx, photo.png,
  readme.txt, report.pdf, sheet.xlsx, slides.pptx

describe_file(relative_path="slides.pptx")
→ {"slide_count": 3, "slide_titles": ["팀 소개", "구성원", "다음 스프린트"]}

Der Bericht, der durch tatsächliches Lesen dieser Dateien erstellt wurde, befindet sich in data/outputs/onboarding-overview-report.md — Strukturprüfung VALID, dateinamenbasierte Prüfung GROUNDED (100 Punkte) bestanden.

Wurde auch gegen einen echten Vorlesungsordner (PPTX, 9 MB, 16 Folien) validiert. Dabei wurde ein Fehler entdeckt und behoben, bei dem eine Formatbibliotheksausnahme direkt hochkam, als versucht wurde, eine Sperrdatei (~$*.pptx) zu lesen, die entsteht, während PowerPoint geöffnet ist. Jetzt wird dies als Fehler mit Ursachencode und Wiederherstellungsmethode behandelt.

[INVALID_REQUEST] '~$파일.pptx' 파일을 열지 못했습니다: Package not found ...
복구 방법: list_folder_contents로 파일 목록과 지원 형식을 다시 확인하세요.

Related MCP server: local-docs-mcp

Was ist es

Wenn ein Ordner angegeben wird, werden die darin enthaltenen Dokumente gelesen, zuerst die Struktur wie Seiten-/Folien-/Blattanzahl erfasst und beim Erstellen eines Zusammenfassungsberichts geholfen. Die 8 Formate werden jeweils mit dedizierten Parsern (pypdf/python-docx/python-pptx/openpyxl/Pillow) verarbeitet.

Warum anders

• Der MCP ruft kein LLM auf. Die tatsächlichen Zusammenfassungssätze schreibt der Host (Claude/Codex). Der Server übernimmt nur Datenabfrage, Strukturanalyse, Validierung und Speicherung.

• Vor dem Speichern sind sowohl ein Genehmigungstoken als auch die ausdrückliche Genehmigung des Benutzers erforderlich. Das einzige Schreibwerkzeug ist save_approved_report, die übrigen 10 sind schreibgeschützt.

• PNG wird ohne OCR als echter Bildinhalt übergeben. Die Vision-Fähigkeit des Hosts sieht und interpretiert es direkt.

• Fehler geben immer einen Ursachencode + Wiederherstellungsmethode + auswählbare Werte zurück (siehe obiges Beispiel).

Wie es funktioniert

list_folder_contents → describe_file → read_file_text(또는 read_image_file)
  → build_summary_prompt → validate_report_draft → check_report_grounding
  → preview_save_report → [사용자 승인] → save_approved_report

Erste Schritte

python -m venv .venv
.venv/Scripts/pip install -e ".[dev]"
.venv/Scripts/python scripts/generate_samples.py
.venv/Scripts/python -m pytest -q
.venv/Scripts/python scripts/smoke_stdio.py

Einen echten Ordner analysieren

Der Standardwert ist sample_docs/. Vor dem Serverstart muss nur eine Umgebungsvariable geändert werden.

FILE_ANALYSIS_ROOT="D:\내 문서 폴더" .venv/Scripts/python src/file_analysis_mcp/server.py

Zur Registrierung in der Codex CLI:

codex mcp add file-analysis --env FILE_ANALYSIS_ROOT="D:\내 문서 폴더" -- \
  "<프로젝트경로>\.venv\Scripts\python.exe" "<프로젝트경로>\src\file_analysis_mcp\server.py"

Einschränkungen

• Bilder werden nicht per OCR verarbeitet. Es wird kein Text extrahiert, sondern der Bildinhalt unverändert an den Host übergeben.

• Bei Dateien über 20 MB ist nur die Strukturprüfung möglich, der Text kann nicht gelesen werden.

• check_report_grounding ist eine regexbasierte Heuristik, daher kann es zu Fehlalarmen kommen (nur beratend, blockiert das Speichern nicht).

• Verschlüsselte, beschädigte oder von anderen Programmen verwendete Dateien werden mit Ursachencode als Fehler gemeldet — der Server stürzt nicht ab.

Zugrunde liegendes Muster

Folgt den Designprinzipien von personal-meeting-mcp-training (Schichttrennung, stage/ next_actions, Genehmigungsgrenzen). Detaillierte Werkzeugverträge finden Sie in den Docstrings der jeweiligen Module unter src/file_analysis_mcp/.