FastMCP 实战：一小时搭建本地文档管理与 AI 交互服务器

一、核心概述

本教程基于 FastMCP（Python 版 MCP 框架）演示如何在 1 小时内完成一个可供本地大语言模型（LLM）调用的文档管理服务。通过该服务，LLM 能够 读取、搜索、编辑、创建、删除 任意文本文件，并可在 Talk with Me、Open Code 等 AI 助手中直接使用这些工具，实现代码审查、文学点评、批量排错等实用场景。

核心痛点：

• 传统 MCP 仅有 Java 实现，生态局限；
• 大多数 AI 项目基于 Python，缺少快速搭建的桥梁；
• 手动实现文件检索与编辑逻辑繁琐，难以复用。

FastMCP 的亮点在于 几行代码即可声明工具、自动生成 OpenAPI 文档，并通过 MCP Inspector 或任意兼容客户端直接调用。

二、实操步骤与核心流程详解

1. 环境准备

• 确保 Python ≥3.9，推荐使用虚拟环境 python -m venv venv && source venv/bin/activate。
• 安装核心依赖：pip install fastapi fastmcp uvicorn
• （可选）安装 Talk with Me 或 Open Code 客户端，以便后续演示工具调用。

2. 编写 DocumentStore 类

class DocumentStore:
    def __init__(self, root: str):
        self.root = Path(root)
        self.root.mkdir(parents=True, exist_ok=True)

    def list_documents(self) -> List[str]:
        return [str(p.relative_to(self.root)) for p in self.root.rglob("*.*")]

    def read(self, path: str) -> str:
        return (self.root / path).read_text(encoding="utf-8")

    def write(self, path: str, content: str) -> None:
        (self.root / path).write_text(content, encoding="utf-8")

    def search(self, keyword: str) -> List[str]:
        return [p for p in self.list_documents() if keyword in self.read(p)]

• 关键点：使用 Path.rglob 支持递归扫描，所有方法均保持 同步阻塞，便于 FastMCP 自动包装为工具。

3. 注册 MCP 工具

from fastmcp import MCPServer

store = DocumentStore("./docs")
server = MCPServer()

server.add_tool(
    name="list_all_documents",
    func=store.list_documents,
    description="列出当前目录下所有可访问文档的相对路径"
)
server.add_tool(
    name="read_document",
    func=store.read,
    description="读取指定路径的文档内容"
)
server.add_tool(
    name="write_document",
    func=store.write,
    description="覆盖写入指定路径的文档内容"
)
server.add_tool(
    name="search_documents",
    func=store.search,
    description="在所有文档中搜索包含关键字的文件路径列表"
)

• 关键点：add_tool 的 description 会自动转化为 tool‑description，供 LLM 在调用前阅读。

4. 启动服务器

uvicorn my_mcp:server.app --host 0.0.0.0 --port 8899

• 服务器默认在 http://localhost:8899 提供 OpenAPI 与 MCP‑Inspector 页面，打开后即可看到已注册的四个工具。

5. 在 AI 客户端中调用

• 在 Talk with Me 中创建一个新聊天房间，勾选 “连接 MCP 服务器”，填写 http://localhost:8899。
• 通过提示让模型使用工具，例如：

  "请列出所有文档并读取 chapter_1.md，判断其中是否存在 Java 代码。"

• 模型会自动发起 list_all_documents → read_document 两次调用，返回文件内容并进行分析。

6. 实战示例

• 代码审查：让模型读取 ThreadSafeCounter.java，利用 search_documents 检索关键字 synchronized，并通过 write_document 自动修复竞争条件。
• 文学点评：为每章创建三种人格（乐观、客观、苛刻），分别调用 read_document → analysis → write_document（仅在只读模式下会被阻止），实现多视角评论。
• 批量纠错：开启编辑权限后，指示模型 search_documents “typo”，遍历返回列表并逐一 write_document 修正。

三、实战技巧与核心小结

• 权限控制：在 MCPServer 实例化时通过 allow_edit=False 禁止写操作，防止 LLM 误删或误改重要文件。
• 工具描述要具体：描述中加入 示例（如 list_all_documents → “返回 ['chapter_1.md', 'README.md']”）可显著提升模型的调用成功率。
• 模型选择：Gemma‑4‑B 在工具调用上表现不稳定，建议使用 Claude‑3、GPT‑4o 或 Quen（内部模型）以获得更可靠的 tool‑calling。
• 调试技巧：使用 MCP‑Inspector 实时查看工具调用日志；若模型返回错误，检查返回的 error 字段并在 Prompt 中加入 “如果工具调用失败，请重新尝试并报告错误”。
• 扩展思路：
  1. 将 DocumentStore 替换为 向量数据库 接口，实现混合 RAG + MCP；
  2. 在 FastMCP 上层封装 邮件、Git、Jira 等业务系统，实现“一键自动化”。

核心小结：FastMCP 让 Python 开发者在几分钟内把本地文件系统暴露为 LLM 可调用的工具集合，配合 Talk with Me、Open Code 等前端即可实现 代码审查、文稿点评、批量编辑 等真实生产需求。只要合理设计工具描述、控制权限，即可安全、可靠地让大模型“动手”而不是仅仅“说话”。