file-analyzer-mcp

A personal stdio MCP server that extracts only text/structure from PDF·DOCX·PPTX·SVG·PNG files in a local folder. It does not summarize or interpret — reading and summarizing the extracted results is the job of the host LLM (Claude Code, etc.) that calls this tool.

What it does / What it doesn't do

Related MCP server: file-analysis

Usage example

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

Quick start

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 추가)

Register with Claude Code:

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

After registration, if you ask in a new session to "summarize the documents in this folder," Claude will call the 3 tools below directly.

Tools

Project structure

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)를 위한 운영 지침

Security & constraints

Observability — audit log

Every tool call is recorded locally, one line at a time, in logs/audit.jsonl (no external transmission).

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

To clear the log, delete logs/audit.jsonl.

Development

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

tests/ covers path escape/absolute path injection blocking, the 5 extractors, timeout, audit log, and server integration. At this project's scale, I judged that local pytest runs alone, without a CI pipeline, are sufficient for regression verification, and have kept it that way.

Why I designed it this way

• No summarization feature — to work without a separate LLM API key, I chose a minimal structure where the server handles extraction and the host handles summarization.

• PNG uses OCR, not vision delivery — instead of passing images to the host as base64, I extract only text to reduce response size and implementation complexity (cannot see the visual meaning of images).

• Local pytest only, no git/CI — I judged CI infrastructure to be overkill for a single-person local tool.

Known limitations

• The timeout is thread-based, so the background thread of an exceeded call may keep running to completion even after the return.

• .ppt is not supported — convert to .pptx before use.

License

A personal project with no separate license file.