当前位置：首页 > news >正文

从零构建MCP服务器：FastMCP实战指南

news 2025/7/11 21:10:55

引言：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()