文件分析 MCP (file-insight-mcp)

读取指定文件夹内的非结构化文档，分析其结构，并撰写按文档分类的摘要和整个文件夹的 摘要报告的个人用本地 MCP 服务器。

本包中 data/sample_docs/ 内的文档均为演示用合成数据。

基础参考

• 服务器结构（FastMCP、stdio、多 MCP 服务器组合）：https://github.com/kyopark2014/mcp

• 哈内斯（harness）规约（分阶段 stage/next_actions、依据锚点、审批边界）：复用同系列 personal-meeting-mcp-training 项目中确立的方式

• 哈内斯工程原则列表：https://github.com/walkinglabs/awesome-harness-engineering （按本项目规模筛选应用上下文预算、预审批钩子、确定性 eval、静态安全扫描器条目）

• MCP Python SDK：https://github.com/modelcontextprotocol/python-sdk

Related MCP server: file-analyzer

该服务器的工作内容

1. 扫描固定目标文件夹（data/sample_docs/）的结构。

2. 仅读取允许的扩展名（.txt .md .csv .log）的文档。

3. 基于规则从文档中提取目录（标题结构）、日期、数值、核心术语候选。

4. 生成结合全部文档的摘要提示词。摘要本身由宿主 LLM（Claude/Codex）撰写， 该 MCP 不调用 LLM API。

5. 验证已撰写摘要报告的结构，并核对提到的文件名是否实际存在。

6. 仅在用户明确批准后才将报告保存为文件。

快速开始

必需环境：Python 3.11 及以上、uv

uv sync --extra dev

安装后确认以下验证一节的四个命令全部通过。

如需通过 MCP Inspector 目视确认工具：

uv run mcp dev src/file_insight_mcp/server.py

项目结构

将领域逻辑与工具规约分离，以便在更改验证规则时无需触碰工具层。

推荐流程

SCAN → LIST → READ → EXTRACT → DRAFT → CHECK → PREVIEW → [사용자 승인] → SAVED

资源与提示词

Harness 设计

该服务器不仅将功能作为设计对象，也将模型使用工具的方式作为设计对象。

• 所有响应都包含 stage 和 next_actions，模型仅凭响应即可选择下一个工具。 blocking: true 是“不要跳过此阶段”的引导提示。实际阻止保存的是结构验证和 审批令牌，提示并不替代该作用。

• 错误通过 ToolFailure 一并返回原因代码、恢复方法和可选值。 目的是让模型无需再次询问即可自行恢复。

• 参数 schema 保持扁平（{"relative_path": "..."}）。若将 Pydantic 模型用作 参数类型，会以 {"params": {...}} 嵌套，从而改变调用形式。

• 返回值是 Pydantic 模型，因此 outputSchema 会自动生成。

• 所有工具都带有 readOnlyHint / destructiveHint，使宿主可以对写入工具 显示不同的审批 UI。

• 只有明确的检查（结构）才阻止保存，启发式检查（文件名核对）仅以警告形式告知。

上下文预算

按照“上下文窗口不是用来丢弃的，而是工作记忆预算”的原则，所有工具都对响应大小 设有明确上限。

• scan_folder_structure：超过 MAX_SCAN_ENTRIES（500）时以 truncated: true 告知并截断。

• read_document：超过 MAX_FILE_BYTES（200KB）的文件不整体读取，而是通过 错误提示仅用 read_document_chunk 读取部分内容。

• extract_key_terms：通过 max_terms 限制各分类的条目数。

• preview_save_report：include_preview=False 为默认值，因此不会将已持有的 草稿再次放入响应。仅在需要时通过 max_preview_chars 限制长度。

• harness.truncate() / harness.number_lines()：始终明确截断状态和引用锚点 （行号），使模型不会猜测“这是全部还是部分”。

安全边界

• 服务器仅处理 security.TARGET_DIR（data/sample_docs/）一个目录。通过 ..、 绝对路径、盘符、符号链接也无法访问其外部（security.safe_relative_path）。

• 不读取扩展名 allowlist（.txt .md .csv .log）之外的文件。可执行/脚本 扩展名始终从目标中排除。

• 文件大小超过 MAX_FILE_BYTES（200KB）时不整体读取，而是通过错误提示。

• 名称以 . 开头的隐藏文件、文件夹从扫描中排除。

• 写入工具仅有 save_approved_report 一个，且仅在 preview_save_report 签发的 （report_id、正文）哈希令牌匹配时运行。

• 该服务器仅读取文档。若源码中出现 eval/exec/subprocess 等代码、shell 执行调用，scripts/validate_package.py 将失败。

验证

uv run pytest -q
uv run python scripts/smoke_stdio.py
uv run python scripts/run_evals.py
uv run python scripts/validate_package.py

四个命令的作用各不相同，因此必须全部通过。

run_evals.py 包含完整保存流程，包括审批令牌正确和错误时保存分别成功、被拒绝的 情况。每次修复 bug 时，在 evals/cases.jsonl 中追加一行可复现该 bug 的用例。 用例语法请参考 evals/README.md。

如果想分析其他文件夹

出于安全考虑，本项目将目标文件夹固定为 src/file_insight_mcp/security.py 中的 TARGET_DIR（包内的 data/sample_docs/）。若要分析实际工作文件夹：

1. 将 TARGET_DIR 改为所需绝对路径，或修改为通过环境变量注入。

2. 将该文件夹中实际存在的扩展名反映到 ALLOWED_EXTENSIONS。

3. 先确认没有敏感子文件夹（认证信息、个人信息等）。

Claude Desktop 连接

将 config/claude_desktop_config.example.json 中的 ABSOLUTE_PROJECT_PATH 替换为 本文件夹的绝对路径后，反映到 Claude Desktop 设置中。必须完全退出应用后重新运行。

设计原则

• MCP 不调用单独的 LLM API。Claude 或 Codex 生成摘要语句， 该 MCP 负责原文、结构、验证和保存。

• 不编造文档中未确认的文件名、数值、日期，依据检查器会机械式核对。

• 最终保存必须同时具备预览中签发的审批令牌和用户的明确批准。

• 将领域逻辑（core、outline、grounding）与工具规约（server、harness、 security）分离。