引言:MCP協議與FastMCP框架
Model Context Protocol(MCP)是連接AI模型與外部服務的標準化協議,允許LLM(如Claude、Gemini)調用工具、訪問數據。然而,直接實現MCP協議需要處理JSON-RPC、會話管理等繁瑣細節。FastMCP作為Python框架,封裝了這些底層邏輯,讓開發者專注于業務功能。本文將通過分步實戰,從零構建一個完整的MCP服務器,涵蓋工具、資源、動態模板等核心功能。
一、環境準備:安裝FastMCP
首先確保安裝FastMCP框架,推薦使用pip:
pip install fastmcp
二、Step 1:創建基礎服務器
所有FastMCP應用的起點是FastMCP
類實例,它作為工具、資源的容器。
代碼示例:
# my_mcp_server.py
from fastmcp import FastMCP# 初始化MCP服務器,指定名稱(用于標識服務)
mcp = FastMCP(name="My First MCP Server")
說明:
- 這行代碼創建了一個空的MCP服務器,暫時不包含任何功能。
- 名稱參數(
name
)用于區分不同服務器,便于客戶端識別。
三、Step 2:添加工具(Tools)
工具是LLM可調用的函數(如計算、數據處理),通過@mcp.tool
裝飾器定義。
代碼示例:
from fastmcp import FastMCPmcp = FastMCP(name="My First MCP Server")@mcp.tool
def add(a: int, b: int) -> int:"""Adds two integer numbers together."""return a + b
FastMCP自動處理的細節:
- 工具名稱:默認使用函數名(如
add
)。 - 描述:從函數文檔字符串(docstring)提取,供LLM理解用途。
- 輸入 schema:通過類型注解(
a: int
、b: int
)生成JSON schema,確保LLM傳入正確類型的參數。
優勢:無需手動定義協議格式,專注函數邏輯即可。
四、Step 3:添加靜態資源(Resources)
資源是LLM可訪問的只讀數據(如配置、知識庫),通過@mcp.resource
裝飾器定義,并綁定唯一URI。
代碼示例:
@mcp.resource("resource://config")
def get_config() -> dict:"""Provides the application's configuration."""return {"version": "1.0", "author": "MyTeam"}
說明:
- URI:
resource://config
是資源的唯一標識,客戶端通過該路徑訪問。 - 懶加載:函數
get_config
僅在客戶端請求時執行,避免不必要的計算。 - 返回格式:支持字典、字符串等,FastMCP自動序列化為JSON返回給客戶端。
五、Step 4:添加動態資源模板(Resource Templates)
資源模板允許通過URI參數生成動態內容,URI中的占位符(如{name}
)會映射為函數參數。
代碼示例:
@mcp.resource("greetings://{name}")
def personalized_greeting(name: str) -> str:"""Generates a personalized greeting for the given name."""return f"Hello, {name}! Welcome to the MCP server."
使用方式:
- 客戶端請求
greetings://Alice
時,FastMCP自動調用personalized_greeting(name="Alice")
,返回"Hello, Alice!..."
。 - 占位符與函數參數名必須一致(如
{name}
對應name: str
),支持多個參數(如greetings://{name}/{title}
)。
六、Step 5:運行服務器
通過mcp.run()
啟動服務器,默認使用STDIO傳輸(適合本地客戶端如Claude Desktop)。
完整代碼:
from fastmcp import FastMCP# 1. 初始化服務器
mcp = FastMCP(name="My First MCP Server")# 2. 添加工具
@mcp.tool
def add(a: int, b: int) -> int:"""Adds two integer numbers together."""return a + b# 3. 添加靜態資源
@mcp.resource("resource://config")
def get_config() -> dict:"""Provides the application's configuration."""return {"version": "1.0", "author": "MyTeam"}# 4. 添加動態資源模板
@mcp.resource("greetings://{name}")
def personalized_greeting(name: str) -> str:"""Generates a personalized greeting for the given name."""return f"Hello, {name}! Welcome to the MCP server."# 5. 啟動服務器
if __name__ == "__main__":mcp.run()
啟動命令:
python my_mcp_server.py
傳輸方式擴展:
- 默認STDIO傳輸適用于本地客戶端。
- 如需HTTP服務,可通過
mcp.http_app()
創建ASGI應用,搭配uvicorn運行(詳見FastMCP部署文檔)。
七、服務器功能驗證
客戶端(如Claude Desktop)可通過以下方式交互:
- 調用工具:請求調用
add
工具,傳入a=3
、b=5
,返回8
。 - 訪問靜態資源:請求
resource://config
,返回配置字典。 - 訪問動態資源:請求
greetings://Bob
,返回"Hello, Bob!..."
。
八、總結:FastMCP的核心優勢
- 極簡開發:用Python函數+裝飾器定義工具和資源,無需關注協議細節。
- 自動適配:自動生成schema、處理序列化,確保與MCP客戶端兼容。
- 靈活擴展:支持靜態資源、動態模板、多傳輸方式(STDIO/HTTP)。
通過本文的步驟,你已構建了一個功能完整的MCP服務器。后續可擴展更復雜的工具(如數據庫查詢、API調用)和資源(如實時數據),為LLM提供更強大的外部能力。