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 fastmcpfastmcp 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_customersearch_ticketsdescribe_tablesummarize_text_file

较差的工具示例：

runprocessdo_thing

4. 仅在必要时添加资源和提示

当客户端需要获取稳定的只读内容（如模式、策略文档或生成的报告）时，添加 @mcp.resource。

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

不要将每个文档都变成提示。应优先考虑：

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

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

使用 FastMCP CLI 进行本地验证：

fastmcp inspect acme_server.py:mcpfastmcp list acme_server.py --jsonfastmcp 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 8000fastmcp list http://127.0.0.1:8000/mcp --jsonfastmcp call http://127.0.0.1:8000/mcp search_resources query=router --json

在声称服务器可以工作之前，始终对每个新工具至少运行一次真实的 fastmcp call。

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

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

fastmcp install claude-code acme_server.pyfastmcp install claude-desktop acme_server.pyfastmcp 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 fastmcpfastmcp version

fastmcp inspect失败

检查：

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

工具在 Python 中可工作，但通过 CLI 不行

运行：

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

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

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

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

参考

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

安装命令

npx skills add https://github.com/nousresearch/hermes-agent --skill fastmcp

Github地址

https://github.com/nousresearch/hermes-agent