file-analyzer-mcp

Proof

Point it at a folder and it hands back a real tree, not a guess:

$ 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)"
}

Then read one of them — headings, paragraphs, and tables come back structured, not flattened:

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

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

Both calls are reproducible — clone this repo, run uv sync --extra dev, and call them against tests/fixtures/ yourself.

Related MCP server: Agent Helper

What it is

A personal MCP server that reads whatever's in a folder — PDF, Word, PowerPoint, SVG, PNG — and hands the structure and raw content back to whichever agent called it (Claude Code, Claude Desktop, Codex). It doesn't summarize anything itself.

That's the whole design: the server extracts, the host interprets. No LLM API key lives in this server. A PNG comes back as base64 image content, not a caption — your host's own vision reads it. A scanned PDF only gets OCR'd when you ask for it.

Tools

Large documents paginate: page_start/page_end for PDF, slide_start/slide_end for PPTX. Default caps are 30 pages / 60 slides — past that, the response's next_actions tells you the next range to ask for.

Install

uv sync --extra dev

Register with Claude Code:

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

On Windows, if uv was installed via pip it won't be on Claude's PATH — use uv.exe's full path (pip show uv to find it). Claude Desktop and Codex examples are in config/: claude_code.example.md, claude_desktop_config.example.json, codex-config.example.toml.

Security

Sensitive paths are refused deterministically — this doesn't depend on the model deciding not to read them. See paths.py.

Every call is also audited — tool name, arguments, and outcome (success or blocked) get appended to logs/audit.jsonl. See audit.py. A 50MB file size cap applies on top of all of this.

Conventions for anyone extending this server are in AGENTS.md.

Errors

Every failure raises ToolFailure with a code, a plain-language reason, and how to recover — the message is written for the calling model to read and act on, not just for a human.

Scanned-PDF OCR

read_pdf(ocr=True) needs Tesseract:

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

ocr_lang defaults to "kor+eng". Wrong Tesseract path? Set TESSERACT_CMD.

Testing

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

Both should pass before a change counts as done — pytest checks modules in isolation, the smoke test is the only thing that exercises the actual MCP protocol and catches schema-level breakage.

Limits