file-analysis-mcp

“请把这个文件夹里的 pdf/docx/pptx/svg/png 文档都读一遍并总结一下。” 这是一个个人用 MCP 服务器，只为让 Claude Code 执行这一句话。

指定文件夹后，它会打开其中的文档，只把文本原样提取出来返回。 摘要、解读不是由这个服务器完成，而是在对话中由调用它的 Claude 完成——因此无需单独的 LLM API 密钥，完全在本地以个人方式运行。

目录

• 实际运行效果

• 快速开始

• 5 个工具

• 在 Claude Code 中注册

• 项目结构

• 设计原则：harness 工程

Related MCP server: file-analyzer

实际运行效果

这是在 Claude Code 中指定实际文件夹（存放公司内部 PRD 文档的文件夹）提问后的结果。

我：帮我总结一下 docs 文件夹里的文档，并分析文件结构

Claude 依次调用 analyze_folder_structure → analyze_folder，并基于返回的原文文本这样回答。

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

服务器只是传回了文本，上面这些摘要语句全部由 Claude 生成——这正是本项目所追求的角色分工。

快速开始

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

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

如果需要 OCR（PNG 分析），请另行安装 Tesseract-OCR——下面在 Claude Code 中注册的开头部分有说明。即便不安装，其余 4 个工具也能正常工作。

5 个工具

所有工具均为只读，不会修改/删除文件。即使触达上限（max_files），也不会悄悄漏掉文件，而是在响应中如实标注有多少个文件未能读取；同时 status 会变成 PARTIAL，让你立即知晓这一情况。

在 Claude Code 中注册

安装 OCR 引擎（仅 PNG 分析需要）

pytesseract 只是 Tesseract-OCR 引擎的 Python 绑定，引擎本身需要另外安装。

1. 下载 UB-Mannheim Tesseract 安装包并安装到 Windows。（如果需要韩语识别，请在安装过程中的“Additional language data”里勾选 Korean。）

2. 将安装路径（默认 C:\Program Files\Tesseract-OCR）添加到系统 PATH。

3. 用 tesseract --version 确认安装成功。

注册服务器

本仓库根目录已备好 .mcp.json。在 file-analysis-mcp 文件夹（或其上级文件夹）中运行 Claude Code 时会自动识别。重启后请在 /mcp 命令或工具列表中确认能否看到 file-analysis 的 5 个工具。

如需手动注册：

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

推荐流程：先用 analyze_folder_structure 了解结构 → 再用 analyze_folder 批量提取全部文档文本 → 由 Claude 基于提取出的文本进行总结。

项目结构

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

设计原则：harness 工程

这个服务器的优先目标不是“增加功能”，而是让模型只看响应就知道下一步该做什么。在 awesome-harness-engineering 介绍的诸多原则中，只选择了真正符合本项目“本地、单用户、只读”特性的部分加以应用。（OpenTelemetry 观测、提示注入沙箱、mcp-guardian 之类的范围审批门控等，是为多用户、长期运行的代理设计的，对这样规模的个人工具来说过于沉重，因此没有采用。）

有意未采用的内容

• 总结/依据验证（grounding）功能：本服务器设计为“只做提取”（总结是宿主模型的职责），因此不适用。

• 行号引用锚点（L12 | ...）：在没有单独的引用依据验证工具的情况下，只会让文本变得杂乱，因此没有采用。如果以后需要，可以复用 harness.number_lines() 来添加。

• 基于审批令牌的保存工作流：本服务器不写入文件，因此不适用。