file-analyzer-mcp

Ein persönlicher stdio-MCP-Server, der aus PDF-, DOCX-, PPTX-, SVG- und PNG-Dateien in einem lokalen Ordner nur Text/Struktur extrahiert. Es wird nicht zusammengefasst oder interpretiert – das Lesen und Zusammenfassen der extrahierten Ergebnisse ist Aufgabe des Host-LLMs (z. B. Claude Code), das dieses Tool aufruft.

Was es tut / was es nicht tut

Related MCP server: file-analysis-mcp

Ausführungsbeispiel

> read_document("quarterly-report.pdf")
{
  "type": "pdf",
  "num_pages": 12,
  "text": "Q3 Revenue Summary\n..."
}

> read_document("../../etc/passwd")
{ "error": "'../../etc/passwd' resolves outside the allowed root folder" }

Schnellstart

git clone https://github.com/saewookkangboy/fileanalyzer_mcp_testmonial.git
cd fileanalyzer_mcp_testmonial
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
brew install tesseract   # PNG OCR용 (한국어는 brew install tesseract-lang 추가)

Bei Claude Code registrieren:

claude mcp add file-analyzer --env FILE_ANALYZER_ROOT=/분석할/폴더 -- \
  "$(pwd)/.venv/bin/python" "$(pwd)/server.py"
claude mcp list   # ✔ Connected 확인

Nach der Registrierung in einer neuen Sitzung „Fasse die Dokumente in diesem Ordner zusammen" sagen – dann ruft Claude die folgenden 3 Tools direkt auf.

Tools

Projektstruktur

server.py                    # FastMCP 앱 진입점, 툴 등록, 루트 폴더 검증
file_analyzer/
  security.py                #  경로 격리(resolve_safe_path), 크기 제한
  timeout.py                 #  추출 작업 하드 타임아웃
  audit.py                   #  로컬 감사 로그(logs/audit.jsonl)
  tree.py, metadata.py       #  list_directory / get_file_metadata 로직
  extractors/                #  pdf · docx · pptx · svg · image(OCR) 추출기
tests/                       # pytest 회귀 스위트
AGENTS.md                    # 호출 에이전트(Claude Code)를 위한 운영 지침

Sicherheit & Einschränkungen

Beobachtbarkeit – Audit-Log

Jeder Tool-Aufruf wird lokal zeilenweise in logs/audit.jsonl protokolliert (keine externe Übertragung).

{"timestamp": "2026-08-26T06:03:35Z", "tool": "read_document", "params": {"relative_path": "report.pdf"}, "status": "ok", "duration_ms": 251.3}

Zum Leeren des Logs einfach logs/audit.jsonl löschen.

Entwicklung

pip install -e ".[dev]"
pytest -q

tests/ behandelt die Blockierung von Pfadausbrüchen und absoluter Pfad-Injektion, die 5 Extraktoren, Timeout, Audit-Log und Server-Integration. Bei diesem Projektumfang haben wir entschieden, dass eine lokale pytest-Ausführung ohne CI-Pipeline für die Regressionsprüfung ausreicht, und halten es so.

Warum so entworfen?

• Keine Zusammenfassungsfunktion – Damit es ohne separaten LLM-API-Schlüssel funktioniert, wurde eine minimale Struktur gewählt, bei der der Server die Extraktion und der Host die Zusammenfassung übernimmt.

• PNG per OCR, nicht per Vision-Übergabe – Statt Bilder als base64 an den Host zu senden, wird nur Text extrahiert, um Rückgabemenge und Implementierungskomplexität zu reduzieren (die visuelle Bedeutung von Bildern wird nicht erfasst).

• Nur lokales pytest ohne git/CI – Bei der Größe eines persönlichen lokalen Tools haben wir CI-Infrastruktur als übertrieben beurteilt.

Bekannte Einschränkungen

• Der Timeout ist thread-basiert, daher kann der Hintergrund-Thread eines überschrittenen Aufrufs auch nach der Rückgabe bis zum Ende weiterlaufen.

• .ppt wird nicht unterstützt – bitte in .pptx konvertieren.

Lizenz

Ein persönliches Projekt ohne separate Lizenzdatei.