跳到主要內容

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。