跳到主要内容

Fastmcp

使用 Python 中的 FastMCP 构建、测试、检查、安装和部署 MCP 服务器。在创建新的 MCP 服务器、将 API 或数据库封装为 MCP 工具、公开资源或提示（prompts），或为 Claude Code、Cursor 或 HTTP 部署准备 FastMCP 服务器时使用。

技能元数据​

来源可选 — 使用 hermes skills install official/mcp/fastmcp 安装
路径optional-skills/mcp/fastmcp
版本1.0.0
作者Hermes Agent
许可证MIT
标签MCP, FastMCP, Python, Tools, Resources, Prompts, Deployment
相关技能native-mcp, mcporter

参考：完整 SKILL.md​

信息

以下是 Hermes 在触发此技能时加载的完整技能定义。这是技能激活时代理看到的指令。

FastMCP

使用 FastMCP 在 Python 中构建 MCP 服务器，在本地验证它们，将其安装到 MCP 客户端中，并将它们部署为 HTTP 端点。

何时使用​

当任务涉及以下情况时，请使用此技能：

  • 在 Python 中创建新的 MCP 服务器
  • 将 API、数据库、CLI 或文件处理工作流封装为 MCP 工具
  • 除了工具之外，还公开资源或提示
  • 在将其接入 Hermes 或其他客户端之前，使用 FastMCP CLI 对服务器进行冒烟测试
  • 将服务器安装到 Claude Code、Claude Desktop、Cursor 或类似的 MCP 客户端中
  • 准备用于 HTTP 部署的 FastMCP 服务器仓库

如果服务器已存在且只需连接到 Hermes，请使用 native-mcp。如果目标是临时通过 CLI 访问现有的 MCP 服务器而不是构建新服务器，请使用 mcporter。

先决条件​

首先在工作环境中安装 FastMCP：

pip install fastmcp
fastmcp version

对于 API 模板，如果尚未安装 httpx，请安装它：

pip install httpx

包含的文件​

模板​

  • templates/api_wrapper.py - 支持认证头部的 REST API 封装器
  • templates/database_server.py - 只读 SQLite 查询服务器
  • templates/file_processor.py - 文本文件检查和搜索服务器

脚本​

  • scripts/scaffold_fastmcp.py - 复制入门模板并替换服务器名称占位符

参考资料​

  • references/fastmcp-cli.md - FastMCP CLI 工作流、安装目标和部署检查

工作流​

1. 选择最小可行的服务器形态​

首先选择最狭窄但有用的表面范围：

  • API 封装器：从 1-3 个高价值端点开始，而不是整个 API
  • 数据库服务器：公开只读内省功能和受限制的查询路径
  • 文件处理器：公开具有显式路径参数的确定性操作
  • 提示/资源：仅当客户端需要可重用的提示模板或可发现的文档时才添加

相比于拥有模糊工具的大型服务器，更倾向于拥有良好命名、文档字符串和架构的轻量级服务器。

2. 从模板搭建脚手架​

直接复制模板或使用脚手架助手：

python ~/.hermes/skills/mcp/fastmcp/scripts/scaffold_fastmcp.py \
  --template api_wrapper \
  --name "Acme API" \
  --output ./acme_server.py

可用模板：

python ~/.hermes/skills/mcp/fastmcp/scripts/scaffold_fastmcp.py --list

如果手动复制，请将 __SERVER_NAME__ 替换为真实的服务器名称。

3. 首先实现工具​

在添加资源或提示之前，先从 @mcp.tool 函数开始。

工具设计规则：

  • 为每个工具赋予基于具体动词的名称
  • 将文档字符串编写面向用户的工具描述
  • 保持参数显式且类型化
  • 尽可能返回结构化的 JSON 安全数据
  • 尽早验证不安全的输入
  • 在初始版本中默认倾向于只读行为

良好的工具示例：

  • get_customer
  • search_tickets
  • describe_table
  • summarize_text_file

较差的工具示例：

  • run
  • process
  • do_thing

4. 仅在有帮助时添加资源和提示​

当客户端受益于获取稳定的只读内容（如架构、策略文档或生成的报告）时，添加 @mcp.resource。

当服务器应为已知工作流提供可重用的提示模板时，添加 @mcp.prompt。

不要将每个文档都变成提示。更倾向于：

  • 使用工具执行操作
  • 使用资源进行数据/文档检索
  • 使用提示提供可重用的 LLM 指令

5. 在集成到任何地方之前测试服务器​

使用 FastMCP CLI 进行本地验证：

fastmcp inspect acme_server.py:mcp
fastmcp list acme_server.py --json
fastmcp call acme_server.py search_resources query=router limit=5 --json

为了快速迭代调试，在本地运行服务器：

fastmcp run acme_server.py:mcp

要在本地测试 HTTP 传输：

fastmcp run acme_server.py:mcp --transport http --host 127.0.0.1 --port 8000
fastmcp list http://127.0.0.1:8000/mcp --json
fastmcp call http://127.0.0.1:8000/mcp search_resources query=router --json

在声称服务器正常工作之前，务必针对每个新工具至少运行一次真实的 fastmcp call。

6. 本地验证通过后安装到客户端​

FastMCP 可以将服务器注册到支持的 MCP 客户端：

fastmcp install claude-code acme_server.py
fastmcp install claude-desktop acme_server.py
fastmcp install cursor acme_server.py -e .

使用 fastmcp discover 检查机器上已配置的命名 MCP 服务器。

当目标是 Hermes 集成时，可以：

  • 使用 native-mcp 技能在 ~/.hermes/config.yaml 中配置服务器，或者
  • 在接口稳定之前，在开发过程中继续使用 FastMCP CLI 命令

7. 本地契约稳定后进行部署​

对于托管主机，Prefect Horizon 是 FastMCP 文档中最直接推荐的路径。在部署之前：

fastmcp inspect acme_server.py:mcp

确保仓库中包含：

  • 一个包含 FastMCP 服务器对象的 Python 文件
  • requirements.txt 或 pyproject.toml
  • 部署所需的任何环境变量文档

对于通用 HTTP 托管，请先在本地验证 HTTP 传输，然后部署到任何能够暴露服务器端口的兼容 Python 平台。

常见模式​

API 封装模式​

当将 REST 或 HTTP API 作为 MCP 工具公开时使用此模式。

推荐的初始功能切片：

  • 一个读取路径
  • 一个列表/搜索路径
  • 可选的健康检查

实现注意事项：

  • 将身份验证信息保存在环境变量中，不要硬编码
  • 在一个辅助函数中集中处理请求逻辑
  • 以简洁的上下文呈现 API 错误
  • 在返回之前规范化不一致的上游负载

从 templates/api_wrapper.py 开始。

数据库模式​

当公开安全的查询和检查能力时使用此模式。

推荐的初始功能切片：

  • list_tables
  • describe_table
  • 一个受约束的读取查询工具

实现注意事项：

  • 默认使用只读数据库访问
  • 在早期版本中拒绝非 SELECT SQL 语句
  • 限制行数
  • 返回行数据以及列名

从 templates/database_server.py 开始。

文件处理器模式​

当服务器需要按需检查或转换文件时使用此模式。

推荐的初始功能切片：

  • 总结文件内容
  • 在文件中搜索
  • 提取确定性元数据

实现注意事项：

  • 接受显式的文件路径
  • 检查缺失的文件和编码失败
  • 限制预览和结果数量
  • 除非需要特定的外部工具，否则避免调用 shell

从 templates/file_processor.py 开始。

质量标准​

在交付 FastMCP 服务器之前，请验证以下所有事项：

  • 服务器导入干净无误
  • fastmcp inspect <file.py:mcp> 成功执行
  • fastmcp list <server spec> --json 成功执行
  • 每个新工具至少有一个真实的 fastmcp call
  • 环境变量已有文档说明
  • 工具表面足够小，无需猜测即可理解

故障排除​

缺少 FastMCP 命令​

在当前激活的环境中安装该软件包：

pip install fastmcp
fastmcp version

fastmcp inspect 失败​

检查以下事项：

  • 文件导入时不会因副作用而崩溃
  • FastMCP 实例在 <file.py:object> 中命名正确
  • 已安装模板中的可选依赖项

工具在 Python 中有效，但在 CLI 中无效​

运行：

fastmcp list server.py --json
fastmcp call server.py your_tool_name --json

这通常会暴露命名不匹配、缺少必需参数或返回值不可序列化的问题。

Hermes 无法看到已部署的服务器​

服务器构建部分可能正确，但 Hermes 配置不正确。加载 native-mcp 技能并在 ~/.hermes/config.yaml 中配置服务器，然后重启 Hermes。

参考​

有关 CLI 详细信息、安装目标和部署检查，请阅读 references/fastmcp-cli.md。