File Analysis MCP

一个读取特定文件夹中的非结构化文档(PDF、DOCX、PPTX、SVG、PNG、JPG)并提取其结构/内容的个人用 MCP 服务器。 摘要由调用此服务器的 Claude Code/Codex 的 LLM 完成，而非此服务器本身。 该服务器仅负责 文本/图像提取和文件夹结构识别。

准备工作

1. Python

python、pip 必须能正常运行。如果在 Windows 上 python 弹出 Microsoft Store 安装提示， 请确认以下事项：

1. 从 python.org 安装 Python 3.11 或更高版本(64-bit)，安装过程中 勾选 "Add python.exe to PATH"。

2. 如果 python 仍然指向 Store 存根：在 设置 → 应用 → 高级应用设置 → 应用执行别名 中 关闭 App Installer 的 python.exe/python3.exe 项。

2. Tesseract-OCR (PNG 的 OCR 功能所需，可选)

使用 UB-Mannheim Tesseract installer 安装后， 将 .mcp.json 中的 TESSERACT_CMD 值设置为实际安装路径。即使不安装，服务器也能正常运行； 分析 PNG 时会返回图像本身(多模态)，仅 OCR 文本会被替换为 "unavailable" 消息。

Related MCP server: ReadPDFx - OCR PDF MCP Server

安装

cd C:\Users\20229\Desktop\MCP
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt

验证

# 1. 샘플 파일 생성 (pdf/docx/pptx/svg/png/txt 각 1개)
.venv\Scripts\python scripts\generate_fixtures.py

# 2. MCP 없이 extractor만 직접 테스트
.venv\Scripts\python scripts\smoke_test.py

Claude Code 注册

此文件夹中的 .mcp.json 已经以项目作用域注册了该服务器。确认 command 路径与实际 .venv\Scripts\python.exe 位置一致后，重启 Claude Code，或使用 /mcp 命令 检查 file-analysis 服务器是否处于 connected 状态。

提供的工具

• scan_folder(folder_path, max_depth=3, max_files=200)：仅返回文件夹树和按扩展名统计的文件数量 (不读取内容)。

• analyze_file(file_path, max_chars=None)：按扩展名提取单个文件。

  • pdf/docx/pptx/svg → 文本/结构信息

  • png/jpg/jpeg → 图像(多模态) + OCR 文本

限制

• SVG 仅解析 XML 结构(文本节点、图形数量、viewBox)。不含文本的纯矢量图 无法从视觉上得知其绘制内容 — 如有需要，请转换为 PNG 后重新分析。

• 提取量设有上限：PDF 50页/5万字，PPTX 100张幻灯片/5万字，PNG OCR 2万字等。 超过上限时，结果中会包含 truncated: true 和提示信息。