file-analysis-mcp

读取指定文件夹内的非结构化文档（pdf、docx、pptx、txt、svg、png、csv、xlsx）， 掌握其结构，并且未经批准不会保存任何内容的个人本地 MCP。

实际运行示例

针对包含的合成示例文件夹（sample_docs/）运行的实际结果。

list_folder_contents()
→ count: 8, entries: data.csv, diagram.svg, notes.docx, photo.png,
  readme.txt, report.pdf, sheet.xlsx, slides.pptx

describe_file(relative_path="slides.pptx")
→ {"slide_count": 3, "slide_titles": ["팀 소개", "구성원", "다음 스프린트"]}

实际读取这些文件后撰写的报告位于 data/outputs/onboarding-overview-report.md — 已通过结构验证 VALID、文件名依据检查 GROUNDED（100分）。

实际还对一个课程资料文件夹（PPTX，9MB，16 张幻灯片）进行了验证，在此过程中 发现并修复了一个 bug：尝试读取 PowerPoint 打开状态下产生的锁文件（~$*.pptx）， 会导致格式库异常原样抛出。现在会作为包含原因代码和恢复 方法的错误处理。

[INVALID_REQUEST] '~$파일.pptx' 파일을 열지 못했습니다: Package not found ...
복구 방법: list_folder_contents로 파일 목록과 지원 형식을 다시 확인하세요.

Related MCP server: local-docs-mcp

这是什么

指定一个文件夹，即可读取其中的文档，先掌握页面/幻灯片/工作表数量等结构， 并帮助撰写摘要报告。8 种格式分别使用专用 解析器（pypdf/python-docx/python-pptx/openpyxl/Pillow）处理。

为什么不同

• MCP 不会调用 LLM。 实际的摘要句子由 Host（Claude/Codex） 编写。服务器只负责数据查询·结构分析·验证·保存。

• 保存前需要批准令牌和用户的明确批准。 写入 工具只有 save_approved_report 一个，其余 10 个均为只读。

• PNG 不经 OCR，以真实图片内容传递。 Host 的视觉能力 会直接查看并解读。

• 错误总是连同原因代码 + 恢复方法 + 可选值一起返回 （参见上方示例）。

如何运作

list_folder_contents → describe_file → read_file_text(또는 read_image_file)
  → build_summary_prompt → validate_report_draft → check_report_grounding
  → preview_save_report → [사용자 승인] → save_approved_report

开始使用

python -m venv .venv
.venv/Scripts/pip install -e ".[dev]"
.venv/Scripts/python scripts/generate_samples.py
.venv/Scripts/python -m pytest -q
.venv/Scripts/python scripts/smoke_stdio.py

分析真实文件夹

默认值是 sample_docs/。只需在服务器启动前更改一个环境变量即可。

FILE_ANALYSIS_ROOT="D:\내 문서 폴더" .venv/Scripts/python src/file_analysis_mcp/server.py

若要注册到 Codex CLI：

codex mcp add file-analysis --env FILE_ANALYSIS_ROOT="D:\내 문서 폴더" -- \
  "<프로젝트경로>\.venv\Scripts\python.exe" "<프로젝트경로>\src\file_analysis_mcp\server.py"

限制

• 图像不进行 OCR。不是提取文本，而是将图片内容 原样传递给 Host。

• 超过 20MB 的文件只能确认结构，无法读取正文。

• check_report_grounding 是基于正则表达式的启发式方法，可能会有误报 （仅是参考，不会阻止保存）。

• 加密、损坏或被其他程序正在使用的文件会连同原因代码 一起报告为错误 — 服务器不会崩溃。

基础模式

遵循与 personal-meeting-mcp-training 相同的设计原则（分层、stage/ next_actions、批准边界）。详细的工具契约请参阅 src/file_analysis_mcp/ 中各模块的 docstring。