这是一个个人使用的 stdio MCP 服务器，用于从本地文件夹中的 PDF·DOCX·PPTX·SVG·PNG 文件中仅提取文本/结构。它不进行摘要或解读——读取提取结果并进行摘要的工作由调用此工具的宿主 LLM（如 Claude Code 等）负责。
做什么 | 不做什么 |
提取指定根文件夹下文档的文本结构 | 摘要·解读（由宿主 LLM 负责） |
统计文件夹树·按扩展名统计文件数/容量 | 文件写入·删除·移动（只读） |
提取 PNG 的 OCR 文本 | 理解图像的视觉含义（图片·图表） |
对大型/损坏文件进行超时处理 | 服务器运行期间更改分析目标文件夹 |
Related MCP server: file-analysis-mcp
> 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" }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 추가)注册到 Claude Code：
claude mcp add file-analyzer --env FILE_ANALYZER_ROOT=/분석할/폴더 -- \
"$(pwd)/.venv/bin/python" "$(pwd)/server.py"
claude mcp list # ✔ Connected 확인注册后，在新会话中请求"帮我总结这个文件夹的文档"，Claude 就会直接调用以下 3 个工具。
工具 | 说明 |
| 文件夹树，按扩展名统计文件数/容量 |
| 文本/结构提取 — |
| 大小、修改时间、页数/幻灯片数、图像分辨率等 |
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)를 위한 운영 지침项目 | 策略 |
路径隔离 | 仅可访问 |
文件大小 | 超过 50MB 时不读取并返回错误 |
超时 | 提取/元数据解析超过 30 秒时以错误中止返回 |
支持的扩展名 |
|
图像解读 | 仅提取 OCR 文本，无法理解图片/图表的视觉含义 |
分析目标文件夹 | 服务器启动时固定一次，运行期间不可更改 |
所有工具调用仅以逐行方式记录在 logs/audit.jsonl 中（无外部传输）。
{"timestamp": "2026-08-26T06:03:35Z", "tool": "read_document", "params": {"relative_path": "report.pdf"}, "status": "ok", "duration_ms": 251.3}如需清空日志，删除 logs/audit.jsonl 即可。
pip install -e ".[dev]"
pytest -qtests/ 涵盖路径逃逸·绝对路径注入拦截、5 种提取器、超时、审计日志、服务器集成。考虑到此项目规模，我们认为无需 CI 流水线，仅通过本地 pytest 执行即可充分完成回归验证，因此一直保持这种方式。
没有摘要功能 — 为了在没有单独 LLM API 密钥的情况下也能运行，采用了提取由服务器负责/摘要由宿主负责的最小结构。
PNG 使用 OCR，不传递 vision — 不将图像以 base64 形式传给宿主，而是只提取文本返回，降低了返回量和实现复杂度（无法看到图片的视觉含义）。
无 git/CI，仅本地 pytest — 在单人本地工具规模下，判断 CI 基础设施过于冗余。
超时基于线程实现，超时的调用本身的后台线程在返回后仍可能继续执行到底。
不支持 .ppt — 请转换为 .pptx 后使用。
这是一个没有单独许可证文件的个人项目。
This server cannot be deployed
Convert PDF, Word, Excel and scanned documents to Markdown, tables and RAG chunks. OCR.
Extract text, pages and metadata from PDFs in bulk, with OCR for scanned files.
Deterministic DOCX/PPTX/XLSX/PDF parser: track changes, comments, headers, footers, merged cells.
High-fidelity PDF to structured Markdown conversion and document field extraction.
