file-analysis-mcp

"Read all the pdf/docx/pptx/svg/png documents in this folder and summarize them." A personal MCP server that lets you ask Claude Code to do this with a single sentence.

Point it at a folder and it opens the documents inside and returns just the raw text. Summarizing and interpreting is done by the Claude that calls this server during the conversation — not by the server itself. So it runs fully locally and privately, with no separate LLM API key.

Table of Contents

• How it actually works

• Quick start

• The 5 tools

• Registering with Claude Code

• Project structure

• Design principle: harness engineering

Related MCP server: file-analyzer

How it actually works

This is the result of asking Claude Code to look at a real folder (a folder containing internal PRD documents).

Me: Summarize the documents in the docs folder and analyze the file structure

Claude calls analyze_folder_structure → analyze_folder in sequence, then answers based on the raw text it received.

[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는 "파라미터 엑셀 입력 시 집계시트 자동 생성 + 오류 빨강 표시"
공통점: 사람 검토·승인은 항상 최종 단계로 남겨둔다는 원칙이 두 문서 모두에 명시됨.

The server only passed the text — every sentence in the summary above was written by Claude. That is the division of labor this project aims for.

Quick start

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

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

If you need OCR (PNG analysis), install Tesseract-OCR separately — instructions are in the earlier part of Registering with Claude Code below. The other 4 tools work fine even before you install it.

The 5 tools

All tools are read-only and never modify or delete files. Even when a limit (max_files) is hit, files are not silently dropped — the response records exactly how many were skipped, and status becomes PARTIAL so you can tell right away.

Registering with Claude Code

Installing the OCR engine (only needed for PNG analysis)

pytesseract is just a Python binding for the Tesseract-OCR engine; the engine itself must be installed separately.

1. Download the UB-Mannheim Tesseract installer and install it on Windows. (If you need Korean recognition, check Korean under "Additional language data" during installation.)

2. Add the install path (default C:\Program Files\Tesseract-OCR) to your system PATH.

3. Verify the installation with tesseract --version.

Registering the server

This repository already has a .mcp.json prepared at the root. Running Claude Code from the file-analysis-mcp folder (or a parent folder) will pick it up automatically. After restarting, check that the 5 file-analysis tools appear in the /mcp command or the tool list.

To register manually:

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

Recommended flow: first understand the structure with analyze_folder_structure → batch-extract all document text with analyze_folder → Claude summarizes based on the extracted text.

Project structure

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/       # 테스트용 샘플 문서

Design principle: harness engineering

This server prioritizes making it so the model can tell from the response alone what to do next over "adding more features." Of the principles introduced in awesome-harness-engineering, it selectively applies only the ones that actually fit this project's nature — local, single-user, read-only. (OpenTelemetry observability, prompt-injection sandboxing, and mcp-guardian-style scope-approval gating are meant for multi-user, long-running agents, so they would be overkill for a personal tool of this scale and were not applied.)

Deliberately not applied

• Summarization/grounding features: This server is designed to "extract only" (summarizing is the host model's job), so these do not apply.

• Line-number citation anchors (L12 | ...): Without a separate tool that verifies cited evidence, this would only clutter the text, so it was not applied. If it ever becomes necessary, it can be added by reusing harness.number_lines().

• Approval-token-based save workflows: This server does not write files, so it does not apply.