file-analysis-mcp

"Lies alle PDF/DOCX/PPTX/SVG/PNG-Dokumente in diesem Ordner und fasse sie zusammen." Ein persönlicher MCP-Server, mit dem man Claude Code genau diesen einen Satz ausführen lassen kann.

Wenn ein Ordner angegeben wird, öffnet der Server die darin enthaltenen Dokumente, extrahiert nur den Text und gibt ihn unverändert zurück. Zusammenfassen und Interpretieren übernimmt nicht dieser Server, sondern der Claude, der ihn aufruft, im Laufe des Gesprächs – daher funktioniert alles ohne separaten LLM-API-Schlüssel, vollständig privat und lokal.

Inhaltsverzeichnis

• So funktioniert es in der Praxis

• Schnellstart

• Die 5 Tools

• Bei Claude Code registrieren

• Projektstruktur

• Designprinzip: Harness Engineering

Related MCP server: file-analyzer

So funktioniert es in der Praxis

Das Ergebnis einer Anfrage in Claude Code mit einem realen Ordner (ein Ordner mit internen PRD-Dokumenten).

Ich: Fasse die Dokumente im Ordner docs zusammen und analysiere die Dateistruktur

Claude ruft nacheinander analyze_folder_structure → analyze_folder auf und antwortet auf Basis des zurückgegebenen Originaltexts wie folgt.

[analyze_folder_structure] pdf 2개, 총 455KB, 최대 파일 prd.pdf(231KB)
[analyze_folder]           2개 파일 모두 추출 성공 (succeeded: 2, failed: 0)

→ Claude의 요약:
두 문서는 같은 프로젝트("ParameterCheck")의 서로 다른 산출물입니다.
- proposal.pdf: RF솔루션 파트의 CAB 파라미터 검증 자동화 기획서
- prd.pdf: 같은 아이디어의 정식 PRD. 목표는 검증 시간 10분→5분 단축,
  MVP는 "파라미터 엑셀 입력 시 집계시트 자동 생성 + 오류 빨강 표시"
공통점: 사람 검토·승인은 항상 최종 단계로 남겨둔다는 원칙이 두 문서 모두에 명시됨.

Der Server hat nur den Text übergeben – die obige Zusammenfassung stammt vollständig von Claude. Genau diese Rollentrennung ist das Ziel dieses Projekts.

Schnellstart

# 1) 의존성 설치 (uv 사용)
uv sync --extra dev

# 2) 확인
uv run pytest                        # 유닛테스트
uv run python scripts/smoke_stdio.py # 실제 MCP 프로토콜로 서버를 띄워보는 스모크 테스트

Falls OCR (PNG-Analyse) benötigt wird, muss Tesseract-OCR separat installiert werden – die Anleitung dazu steht weiter unten im Abschnitt Bei Claude Code registrieren. Auch ohne Installation funktionieren die übrigen 4 Tools normal.

Die 5 Tools

Alle Tools sind schreibgeschützt und verändern oder löschen keine Dateien. Selbst wenn das Limit (max_files) erreicht wird, werden Dateien nicht stillschweigend weggelassen, sondern die Anzahl der nicht gelesenen Dateien bleibt in der Antwort sichtbar; außerdem wird status auf PARTIAL gesetzt, sodass dieser Umstand sofort erkennbar ist.

Bei Claude Code registrieren

OCR-Engine installieren (nur für PNG-Analyse nötig)

pytesseract ist lediglich die Python-Anbindung an die Tesseract-OCR-Engine; die Engine selbst muss separat installiert werden.

1. Laden Sie das UB-Mannheim Tesseract-Installationspaket herunter und installieren Sie es unter Windows. (Falls Koreanisch erkannt werden soll, aktivieren Sie bei der Installation unter "Additional language data" die Option Korean.)

2. Fügen Sie den Installationspfad (Standard: C:\Program Files\Tesseract-OCR) zur System-PATH-Variable hinzu.

3. Prüfen Sie die Installation mit tesseract --version.

Server registrieren

In diesem Repository liegt bereits eine .mcp.json im Root-Verzeichnis bereit. Wenn Sie Claude Code im Ordner file-analysis-mcp (oder einem übergeordneten Ordner) starten, wird sie automatisch erkannt. Prüfen Sie nach dem Neustart über den Befehl /mcp oder in der Tool-Liste, ob die 5 Tools von file-analysis sichtbar sind.

Zur manuellen Registrierung:

claude mcp add file-analysis -- uv --directory "C:\Users\20223\Desktop\file-analysis-mcp" run python src/file_analysis_mcp/server.py

Empfohlener Ablauf: Zuerst die Struktur mit analyze_folder_structure erfassen → dann den gesamten Dokumenttext mit analyze_folder in einem Durchgang extrahieren → Claude fasst auf Basis des extrahierten Texts zusammen.

Projektstruktur

file-analysis-mcp/
├── pyproject.toml
├── .mcp.json
├── src/file_analysis_mcp/
│   ├── server.py        # FastMCP 서버, 도구 5개
│   ├── harness.py        # 응답/오류 계약 (BaseResponse, ToolFailure 등)
│   ├── scanner.py         # 폴더 스캔/구조 분석
│   └── extractors/        # pdf/docx/pptx/svg/image 텍스트 추출기
├── scripts/smoke_stdio.py
├── tests/
│   ├── test_scanner.py           # 도메인 로직(순수 함수) 유닛테스트
│   ├── test_extractors.py        # 포맷별 추출기 유닛테스트
│   └── test_server_contract.py   # 하네스 규약(도구 계약) 테스트
└── data/sample_docs/       # 테스트용 샘플 문서

Designprinzip: Harness Engineering

Dieser Server priorisiert nicht "mehr Funktionen", sondern dass das Modell allein anhand der Antwort weiß, was es als Nächstes tun soll. Aus den Prinzipien, die in awesome-harness-engineering vorgestellt werden, wurden nur diejenigen gezielt übernommen, die zum Charakter dieses Projekts (lokal, Einzelbenutzer, schreibgeschützt) tatsächlich passen. (OpenTelemetry-Observability, Prompt-Injection-Sandboxing, Scope-Approval-Gating wie bei mcp-guardian usw. sind für Mehrbenutzer- und langlaufende Agenten gedacht und wären für ein persönliches Tool dieser Größenordnung übertrieben – daher nicht angewendet.)

Bewusst nicht angewendet

• Zusammenfassungs-/Grounding-Funktion: Da dieser Server nur "extrahieren" soll (Zusammenfassen ist Aufgabe des Host-Modells), nicht zutreffend.

• Zeilennummern-Zitatanker (L12 | ...): Ohne ein separates Tool zur Verifikation der Zitatgrundlage würde der Text nur unübersichtlich – daher nicht angewendet. Falls nötig, kann dies durch Wiederverwendung von harness.number_lines() ergänzt werden.

• Speicher-Workflow mit Genehmigungstoken: Da dieser Server keine Dateien schreibt, nicht zutreffend.