file-analyzer-mcp

Ein persönlicher stdio-MCP-Server, der nur Text/Struktur aus PDF·DOCX·PPTX·SVG·PNG in lokalen Ordnern extrahiert. Er fasst nicht zusammen und interpretiert nicht – das Lesen und Zusammenfassen der extrahierten Ergebnisse ist Aufgabe des Host-LLM (z. B. Claude Code), das dieses Tool aufruft.

Was es tut / was es nicht tut

Related MCP server: Docalyze

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/asuramama-hue/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 추가)

Registrierung in Claude Code:

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

Wenn Sie nach der Registrierung in einer neuen Sitzung „Fasse die Dokumente in diesem Ordner zusammen" anfordern, 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}

Um das Log zu leeren, löschen Sie einfach logs/audit.jsonl.

Entwicklung

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

tests/ deckt Pfadausbruch- und absolute-Pfadinjektion-Blockierung, die 5 Extraktoren, Timeout, Audit-Log und Serverintegration ab. Bei dieser Projektgröße haben wir entschieden, dass lokale pytest-Ausführung ohne CI-Pipeline für die Regressionsprüfung ausreicht, und haben es so beibehalten.

Warum so gestaltet?

• Keine Zusammenfassungsfunktion — Damit es ohne separaten LLM-API-Schlüssel funktioniert, haben wir eine minimale Struktur gewählt, bei der der Server extrahiert und der Host zusammenfasst.

• PNG per OCR, nicht Vision — Statt Bilder als base64 an den Host zu senden, wird nur Text extrahiert, um Antwortmenge 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

• Das Timeout ist threadbasiert, daher kann der Hintergrund-Thread des überschrittenen Aufrufs auch nach der Rückgabe bis zum Ende weiterlaufen.

• .ppt wird nicht unterstützt — bitte in .pptx konvertieren und dann verwenden.

Lizenz

Ein persönliches Projekt ohne separates Lizenzdatei.