file-analyzer-mcp

Beweis

Gib einen Ordner an, und er liefert einen echten Baum zurück, keine Vermutung:

$ analyze_folder_structure({ "folder_path": "tests/fixtures" })

{
  "status": "OK",
  "file_count": 6,
  "supported_file_count": 6,
  "extension_stats": [
    { "extension": ".pdf",  "count": 2, "bytes": 723995 },
    { "extension": ".docx", "count": 1, "bytes": 35505 },
    { "extension": ".pptx", "count": 1, "bytes": 33067 },
    { "extension": ".svg",  "count": 1, "bytes": 319 },
    { "extension": ".png",  "count": 1, "bytes": 74 }
  ],
  "tree_text": "fixtures/\n├── sample.docx (34.7KB)\n├── sample.pdf (431B)\n├── sample.png (74B)\n├── sample.pptx (32.3KB)\n├── sample.svg (319B)\n└── sample_scanned.pdf (706.6KB)"
}

Lies dann eine davon — Überschriften, Absätze und Tabellen kommen strukturiert zurück, nicht flachgewalzt:

$ read_docx({ "file_path": "tests/fixtures/sample.docx" })

{
  "status": "OK",
  "headings": ["테스트 문서"],
  "text": "테스트 문서\n본문 첫 문단입니다.",
  "tables": [{ "index": 0, "rows": [["A", "B"], ["1", "2"]] }]
}

Beide Aufrufe sind reproduzierbar — klone dieses Repo, führe uv sync --extra dev aus und ruf sie selbst gegen tests/fixtures/ auf.

Related MCP server: Agent Helper

Was es ist

Ein persönlicher MCP-Server, der alles liest, was in einem Ordner liegt — PDF, Word, PowerPoint, SVG, PNG — und die Struktur sowie den Rohinhalt an den Agenten zurückgibt, der ihn aufgerufen hat (Claude Code, Claude Desktop, Codex). Er fasst selbst nichts zusammen.

Das ist das gesamte Design: Der Server extrahiert, der Host interpretiert. In diesem Server befindet sich kein LLM-API-Schlüssel. Ein PNG kommt als Base64-Bildinhalt zurück, nicht als Bildunterschrift — die eigene Vision deines Hosts liest es. Ein gescanntes PDF wird nur dann per OCR verarbeitet, wenn du danach fragst.

Werkzeuge

Große Dokumente werden paginiert: page_start/page_end für PDF, slide_start/slide_end für PPTX. Die Standard-Obergrenzen sind 30 Seiten / 60 Folien — darüber hinaus nennt dir next_actions in der Antwort den nächsten Bereich, den du anfordern kannst.

Installation

Bei Claude Code registrieren:

uv sync --extra dev

claude mcp add -s user file-analyzer -- "<uv.exe path>" --directory "<this folder>" run python src/file_analyzer_mcp/server.py

Unter Windows: Wenn uv per pip installiert wurde, ist es nicht im PATH von Claude — verwende den vollständigen Pfad von uv.exe (pip show uv, um ihn zu finden). Beispiele für Claude Desktop und Codex findest du in config/: claude_code.example.md, claude_desktop_config.example.json, codex-config.example.toml.

Sicherheit

Vertrauliche Pfade werden deterministisch abgelehnt — das hängt nicht davon ab, dass das Modell entscheidet, sie nicht zu lesen. Siehe paths.py.

Jeder Aufruf wird außerdem protokolliert — Name des Werkzeugs, Argumente und Ergebnis (erfolgreich oder blockiert) werden an logs/audit.jsonl angehängt. Siehe audit.py. Zusätzlich zu all dem gilt eine Dateigrößen-Obergrenze von 50 MB.

Konventionen für alle, die diesen Server erweitern, stehen in AGENTS.md.

Fehler

Jeder Fehler wirft ToolFailure mit einem Code, einer verständlichen Begründung und einer Anleitung zur Behebung — die Meldung ist für das aufrufende Modell geschrieben, damit es sie liest und danach handelt, nicht nur für einen Menschen.

OCR für gescannte PDFs

read_pdf(ocr=True) benötigt Tesseract:

winget install UB-Mannheim.TesseractOCR
uv run python scripts/setup_ocr.py   # copies eng/osd, downloads kor.traineddata

ocr_lang ist standardmäßig auf "kor+eng" gesetzt. Falscher Tesseract-Pfad? Setze TESSERACT_CMD.

Tests

uv run pytest -q                        # parser / path / audit unit tests
uv run python scripts/smoke_stdio.py    # real stdio round-trip against the server

Beide müssen erfolgreich sein, bevor eine Änderung als abgeschlossen gilt — pytest prüft Module isoliert, der Smoke-Test ist das Einzige, was das tatsächliche MCP-Protokoll durchläuft und Brüche auf Schemaebene abfängt.

Einschränkungen