快速手搓一个MCP服务指南（三）：FastMCP的核心组件-构建MCP服务的关键技术实现

FastMCP 是一套面向 LLM 应用开发的工具框架，通过标准化协议衔接大语言模型与外部功能组件，构建「LLM+工具」的闭环交互体系。其核心技术体系包含四大模块：工具系统将 Python 函数转化为 LLM 可调用的能力单元，通过类型注解实现参数自动校验与协议转换；资源与模板机制提供数据访问接口，支持静态数据与参数化动态数据的标准化输出；提示系统通过参数化模板复用 LLM 交互逻辑，实现提示工程的模块化管理；上下文机制则贯穿请求生命周期，提供日志记录、进度反馈、LLM 二次调用等运行时能力。这套体系以「语义抽象+协议自动化」为核心设计理念，既屏蔽了底层通信细节，又通过标签过滤、动态禁用等机制实现细粒度的组件控制，最终帮助开发者高效构建类型安全、可扩展的 AI 应用系统，尤其适合需要多工具协同的复杂 LLM 场景。

FastMCP 工具核心技术文档详解

一、工具的本质与核心作用

FastMCP 工具是连接 LLM 与外部系统的桥梁，将 Python 函数转换为可被 LLM 调用的能力。其核心价值在于：

• 扩展 LLM 能力：让 LLM 能执行数据库查询、API 调用、文件操作等外部任务
• 类型安全交互：通过参数校验确保 LLM 输入符合函数预期
• 协议自动化：自动将函数转换为 MCP 协议支持的接口规范

当 LLM 调用工具时，流程如下：

1. 发送带参数的请求 → 2. FastMCP 验证参数 → 3. 执行函数 → 4. 返回结果至 LLM

二、工具创建与装饰器用法

1. 基础工具定义

from fastmcp import FastMCPmcp = FastMCP(name="CalculatorServer")@mcp.tool
def add(a: int, b: int) -> int:"""两整数相加"""return a + b

• 工具名称默认使用函数名（add）
• 描述默认使用函数文档字符串
• 自动生成参数 schema（基于类型注解）

2. 装饰器参数详解

参数名	类型	作用描述
name	str	自定义工具名称（覆盖函数名）
description	str	自定义描述（覆盖文档字符串）
tags	set[str]	工具标签（用于过滤或分类）
enabled	bool	初始化禁用工具（enabled=False）
exclude_args	list[str]	隐藏参数（不暴露给 LLM）
annotations	dict	添加元数据（如只读标记、幂等性提示）

示例：自定义工具元数据

@mcp.tool(name="find_products",description="按关键词搜索产品目录",tags={"search", "catalog"},annotations={"readOnlyHint": True}
)
def search(query: str, limit: int = 10) -> list:...

三、参数类型与校验

1. 类型注解的重要性

• LLM 引导：明确参数类型帮助 LLM 生成正确输入
• 自动校验：FastMCP 基于类型注解验证客户端输入
• 协议生成：生成符合 MCP 规范的 JSON Schema

2. 支持的参数类型

类型分类	示例注解	说明
基础类型	int, float, str, bool	自动进行类型转换（如字符串 "42" 转为整数）
集合类型	list[float], dict[str, int]	支持嵌套结构（JSON 自动解析为对应类型）
日期时间	datetime, date	接受 ISO 格式字符串（如 "2025-06-24"）
约束类型	Literal["asc", "desc"]	限制参数取值范围（LLM 只能输入指定值）
Pydantic 模型	class User(BaseModel)	处理复杂结构化数据（自动校验嵌套字段）
二进制数据	bytes	支持原始二进制或 Base64 编码（需手动解码）

3. 参数元数据与校验

使用 pydantic.Field 增强参数定义：

from typing import Annotated
from pydantic import Field@mcp.tool
def process(text: Annotated[str, Field(min_length=3, max_length=500)],score: Annotated[float, Field(ge=0, le=100)],mode: Annotated[str, Field(pattern=r"^[a-z]+$")]
) -> str:...

• min_length/max_length：字符串长度限制
• ge/le/gt/lt：数值范围约束
• pattern：正则表达式校验
• description：参数说明（展示给 LLM）

四、工具高级功能

1. 异步工具（IO 密集型任务）

import aiohttp
from fastmcp import FastMCPmcp = FastMCP()@mcp.tool
async def fetch_weather(city: str) -> dict:"""异步获取天气数据"""async with aiohttp.ClientSession() as session:resp = await session.get(f"https://api.weather.com/{city}")return await resp.json()

• 使用 async def 定义异步工具
• 适用于网络请求、数据库查询等耗时操作
• 避免阻塞服务器主线程

2. 工具返回值处理

FastMCP 自动转换返回值类型：

• str → 文本内容
• dict/list → JSON 字符串
• bytes → Base64 编码（Blob 资源）
• Image/Audio → 专用内容类型（需导入 fastmcp.utilities.types）

示例：返回图片数据

from fastmcp.utilities.types import Image
from PIL import Image as PILImage
import io@mcp.tool
def generate_image(width: int, height: int) -> Image:img = PILImage.new("RGB", (width, height), "white")buffer = io.BytesIO()img.save(buffer, format="PNG")return Image(data=buffer.getvalue(), format="png")

3. 错误处理与安全控制

• 标准异常：抛出 ValueError 等常规异常，错误信息会返回给 LLM
• ToolError：专用错误类（强制显示错误信息，不受 mask_error_details 影响）
• 错误屏蔽：服务器配置 mask_error_details=True 隐藏详细堆栈

from fastmcp.exceptions import ToolError@mcp.tool
def divide(a: float, b: float) -> float:if b == 0:raise ToolError("除数不能为零")return a / b

五、MCP 上下文（Context）

工具可通过 Context 对象访问运行时功能：

from fastmcp import Context@mcp.tool
async def process_data(uri: str, ctx: Context) -> dict:# 日志记录await ctx.info(f"处理资源: {uri}")# 读取资源resource = await ctx.read_resource(uri)# 进度报告await ctx.report_progress(50, 100)# 调用 LLM 辅助summary = await ctx.sample("总结数据: " + resource[0].content)return {"summary": summary.text}

• 日志：ctx.debug/info/warning/error
• 资源访问：ctx.read_resource
• 进度跟踪：ctx.report_progress
• LLM 交互：ctx.sample（在工具中调用 LLM）

六、工具管理与服务器行为

1. 标签过滤与禁用

• 标签过滤：通过服务器配置 include_tags/exclude_tags 控制工具暴露
• 动态禁用：tool.disable()/tool.enable() 运行时控制工具状态

# 仅暴露带"public"标签的工具
mcp = FastMCP(include_tags={"public"})@mcp.tool(tags={"public"})
def public_tool():...@mcp.tool(tags={"internal"})
def internal_tool():...  # 不会暴露

2. 重复工具处理

服务器创建时配置 on_duplicate_tools 策略：

• "warn"（默认）：警告并替换
• "error"：抛出异常阻止注册
• "replace"：静默替换
• "ignore"：忽略新注册

mcp = FastMCP(on_duplicate_tools="error")@mcp.tool
def my_tool():...@mcp.tool  # 重复注册会抛出异常
def my_tool():...

3. 动态移除工具

mcp = FastMCP()@mcp.tool
def old_tool():...# 移除工具
mcp.remove_tool("old_tool")

七、关键概念总结

模块	核心要点
工具定义	@mcp.tool 装饰器，类型注解是关键，参数元数据用 Field 增强
异步处理	async def 定义异步工具，适用于网络/IO 操作，避免阻塞
上下文交互	Context 对象提供日志、资源访问、LLM 调用等功能
安全与控制	标签过滤、参数隐藏、错误屏蔽，ToolError 用于强制显示错误
服务器行为	重复工具策略、动态移除工具、legacy JSON 解析（默认禁用）

八、实践建议

1. 类型优先：始终添加类型注解，利用 Pydantic 校验提升鲁棒性
2. 异步分离：IO 密集型任务使用异步工具，CPU 密集型用同步工具
3. 元数据完善：通过 annotations 添加工具特性（只读/幂等），帮助客户端优化交互
4. 错误防御：合理使用 ToolError 和 mask_error_details 平衡调试与安全
5. 标签管理：利用标签实现环境隔离（如开发环境暴露 debug 工具，生产环境隐藏）

通过上述功能，FastMCP 工具系统提供了从简单函数到复杂异步任务的完整解决方案，完美衔接 LLM 与外部系统的交互需求。

FastMCP 资源与模板技术文档详解

一、资源与模板的核心概念

FastMCP 资源（Resources）是客户端可读取的数据实体，而资源模板（Resource Templates）是动态生成资源的参数化定义。两者的核心作用是：

• 资源：提供静态或动态数据的只读访问（如配置文件、日志内容）
• 模板：通过 URI 参数动态生成资源（如按 ID 检索用户数据）

当客户端请求资源 URI 时，FastMCP 会：

1. 匹配资源定义
2. 执行对应的函数（如动态资源）
3. 将结果转换为标准格式返回

二、资源定义与装饰器用法

1. 基础资源定义

from fastmcp import FastMCPmcp = FastMCP(name="DataServer")# 基础字符串资源
@mcp.resource("resource://greeting")
def get_greeting() -> str:"""返回问候语"""return "Hello from FastMCP Resources!"# JSON 格式资源（字典自动序列化）
@mcp.resource("data://config")
def get_config() -> dict:"""返回应用配置"""return {"theme": "dark", "version": "1.2.0"}

• URI：资源唯一标识符（如 resource://greeting）
• 延迟加载：仅在客户端请求时执行函数
• 元数据推断：函数名和文档字符串自动作为资源名称和描述

2. 装饰器参数详解

参数名	类型	作用描述
uri	str	资源唯一 URI（必填）
name	str	自定义资源名称（默认使用函数名）
description	str	自定义描述（默认使用文档字符串）
mime_type	str	内容类型（如 application/json）
tags	set[str]	标签（用于客户端过滤）
enabled	bool	初始化禁用资源（enabled=False）

示例：完整资源定义

@mcp.resource(uri="data://app-status",name="ApplicationStatus",description="当前应用状态",mime_type="application/json",tags={"monitoring"}
)
def get_status() -> dict:return {"status": "ok", "uptime": 3600}

三、资源返回值处理

FastMCP 自动转换返回值为标准格式：

• str → 文本资源（text/plain）
• dict/list → JSON 文本（application/json）
• bytes → Base64 编码（需指定 mime_type）
• None → 空内容

示例：返回二进制图片

from fastmcp.utilities.types import Image
import io
from PIL import Image as PILImage@mcp.resource("image://logo", mime_type="image/png")
def get_logo() -> bytes:img = PILImage.new("RGB", (200, 100), "blue")buffer = io.BytesIO()img.save(buffer, format="PNG")return buffer.getvalue()

四、资源高级功能

1. 动态启用/禁用资源（2.8.0+）

# 初始化禁用资源
@mcp.resource("data://secret", enabled=False)
def get_secret():return "敏感数据"# 运行时控制
config_resource = mcp.get_resource("data://config")
config_resource.disable()  # 禁用资源
config_resource.enable()   # 重新启用

2. 访问 MCP 上下文（2.2.5+）

from fastmcp import Context@mcp.resource("resource://system-info")
async def get_system_info(ctx: Context) -> dict:"""获取带请求 ID 的系统信息"""return {"status": "ok","request_id": ctx.request_id,"client_id": ctx.client_id}

• 上下文提供请求 ID、客户端 ID、日志记录等功能

3. 异步资源（处理 I/O 操作）

import aiofiles@mcp.resource("file:///app/logs/latest.log", mime_type="text/plain")
async def read_log() -> str:"""异步读取日志文件"""try:async with aiofiles.open("/app/logs/latest.log", "r") as f:return await f.read()except FileNotFoundError:return "日志文件未找到"

五、资源类直接注册

除装饰器外，可直接使用资源类注册静态资源：

from fastmcp.resources import FileResource, TextResource, DirectoryResource# 1. 注册文件资源
readme = FileResource(uri="file://README.md",path=Path("./README.md"),mime_type="text/markdown"
)
mcp.add_resource(readme)# 2. 注册文本资源
notice = TextResource(uri="resource://notice",text="系统维护将于周日进行",name="重要通知"
)
mcp.add_resource(notice)# 3. 注册目录列表资源
data_dir = DirectoryResource(uri="resource://data-files",path=Path("./data"),recursive=True  # 包含子目录
)
mcp.add_resource(data_dir)

常见资源类：

• TextResource：纯文本内容
• FileResource：本地文件
• HttpResource：HTTP 远程资源
• DirectoryResource：目录文件列表

六、资源模板（动态参数化资源）

1. 基础模板定义

@mcp.resource("weather://{city}/current")
def get_weather(city: str) -> dict:"""获取城市天气"""return {"city": city,"temp": 22,"condition": "晴朗"}

• URI 中的 {city} 为参数占位符
• 客户端请求 weather://london/current 时，city 参数被赋值为 london

2. 多参数与默认值

@mcp.resource("search://{query}")
def search(query: str, limit: int = 10, sort: str = "relevance") -> dict:"""搜索资源（limit 和 sort 有默认值）"""return {"query": query,"limit": limit,"results": ["结果1", "结果2"]}

• 客户端可只提供 query 参数（如 search://python）
• 可选参数使用默认值

3. 通配符参数（2.2.4+）

@mcp.resource("path://{filepath*}")
def get_path(filepath: str) -> str:"""匹配多级路径（如 path://docs/api/resources）"""return f"路径内容: {filepath}"@mcp.resource("repo://{owner}/{path*}/file.py")
def get_repo_file(owner: str, path: str) -> dict:"""匹配仓库中的文件路径"""return {"owner": owner,"file": f"{path}/file.py"}

• {param*} 匹配多个路径段（含斜杠）
• 适用于文件系统或层级数据访问

七、错误处理与服务器行为

1. 错误处理

from fastmcp.exceptions import ResourceError@mcp.resource("data://{id}")
def get_data(id: str) -> dict:if id == "invalid":raise ResourceError("数据 ID 无效")if id == "secret":raise ValueError("禁止访问敏感数据")  # 会被 mask 处理return {"id": id, "data": "有效内容"}# 服务器配置错误屏蔽
mcp = FastMCP(mask_error_details=True)

• ResourceError 的错误信息始终暴露
• 其他异常在 mask_error_details=True 时会被简化

2. 重复资源处理

mcp = FastMCP(on_duplicate_resources="error")  # 冲突时报错@mcp.resource("data://config")
def v1_config():return {"version": 1}@mcp.resource("data://config")  # 重复注册会抛出异常
def v2_config():return {"version": 2}

• 策略包括："warn"（默认，警告并替换）、"error"（报错）、"replace"（静默替换）、"ignore"（忽略新注册）

八、核心功能总结

功能模块	核心特性
资源定义	@mcp.resource 装饰器，URI 唯一标识，自动类型转换
动态控制	启用/禁用、上下文访问、异步处理
资源类	预定义资源类型（文件、文本、目录），直接注册静态资源
模板参数	URI 占位符、通配符参数、默认值处理，支持多级路径匹配
错误与冲突	自定义错误响应、错误信息屏蔽、重复资源策略配置

资源与模板是 FastMCP 中数据访问的核心组件，通过灵活的定义方式和参数化设计，使 LLM 能够动态获取所需数据，同时保持系统的可维护性和安全性。

FastMCP 提示（Prompts）技术文档详解

一、提示的核心概念与作用

FastMCP 提示（Prompts）是可复用的消息模板，用于指导 LLM 生成结构化响应。其核心价值在于：

• 标准化交互：定义统一的提示格式，确保 LLM 输出一致性
• 参数化设计：通过函数参数动态生成提示内容
• 复用性：跨场景共享提示逻辑，减少重复开发

当客户端调用提示时，流程如下：

1. 匹配提示定义 → 2. 验证参数 → 3. 执行函数生成消息 → 4. 返回至 LLM 生成响应

二、提示定义与装饰器用法

1. 基础提示定义

from fastmcp import FastMCP
from fastmcp.prompts.prompt import Message, PromptMessage, TextContentmcp = FastMCP(name="PromptServer")# 基础字符串提示（自动转为用户消息）
@mcp.prompt
def ask_about_topic(topic: str) -> str:"""生成询问主题的用户消息"""return f"能否解释'{topic}'的概念？"# 自定义消息类型提示
@mcp.prompt
def generate_code_request(language: str, task_description: str) -> PromptMessage:"""生成代码请求消息"""content = f"编写{language}函数实现：{task_description}"return PromptMessage(role="user", content=TextContent(type="text", text=content))

• 名称：默认使用函数名（如 ask_about_topic）
• 参数：函数参数定义提示输入（如 topic: str）
• 元数据：文档字符串自动作为提示描述

2. 装饰器参数详解

参数名	类型	作用描述
name	str	自定义提示名称（覆盖函数名）
description	str	自定义描述（覆盖文档字符串）
tags	set[str]	标签（用于客户端过滤）
enabled	bool	初始化禁用提示（enabled=False）

示例：完整参数配置

@mcp.prompt(name="analyze_data",description="生成带参数的数据分析请求",tags={"data", "analysis"}
)
def data_analysis(data_uri: str = Field(description="数据资源URI"),analysis_type: str = Field(default="summary", description="分析类型")
) -> str:return f"请对{data_uri}的数据进行'{analysis_type}'分析"

三、参数类型与自动转换（2.9.0+ 新特性）

1. 类型注解支持

FastMCP 允许使用 Python 类型注解，自动处理 MCP 字符串参数的转换：

@mcp.prompt
def analyze_data(numbers: list[int],     # 自动转换字符串为整数列表metadata: dict[str, str],  # 转换JSON字符串为字典threshold: float       # 转换字符串为浮点数
) -> str:avg = sum(numbers) / len(numbers)return f"平均值：{avg}，超过阈值：{avg > threshold}"

2. 客户端调用格式

# 客户端需传递字符串格式的JSON
{"numbers": "[1, 2, 3, 4, 5]","metadata": "{\"source\":\"api\",\"version\":\"1.0\"}","threshold": "2.5"
}# 直接调用可使用原生类型（开发测试用）
result = await prompt.render({"numbers": [1, 2, 3],"metadata": {"source": "api"},"threshold": 2.5
})

四、返回值处理

FastMCP 支持多种返回类型，自动转换为 MCP 消息：

• str：转为单条用户消息
• PromptMessage：直接使用自定义消息
• list[PromptMessage/str]：转为消息序列（对话）
• 其他类型：尝试转为字符串后作为消息

示例：多消息返回

from fastmcp.prompts.prompt import Message@mcp.prompt
def roleplay_scenario(character: str, situation: str) -> list[Message]:"""生成角色扮演场景的初始对话"""return [Message(f"我们来角色扮演，你是{character}，场景：{situation}"),Message("好的，我准备好了。接下来发生什么？", role="assistant")]

五、高级功能

1. 动态启用/禁用（2.8.0+）

# 初始化禁用
@mcp.prompt(enabled=False)
def experimental_prompt():return "这是实验性提示"# 运行时控制
holiday_prompt = mcp.get_prompt("seasonal_greeting")
holiday_prompt.disable()  # 禁用提示
holiday_prompt.enable()   # 重新启用

2. 异步提示（处理IO操作）

import aiohttp@mcp.prompt
async def data_driven_prompt(data_id: str) -> str:"""基于远程数据生成提示"""async with aiohttp.ClientSession() as session:resp = await session.get(f"https://api/data/{data_id}")data = await resp.json()return f"分析这些数据：{data['content']}"

3. 访问MCP上下文（2.2.5+）

from fastmcp import Context@mcp.prompt
async def generate_report(report_type: str, ctx: Context) -> str:"""生成带请求ID的报告请求"""return f"请创建{report_type}报告，请求ID：{ctx.request_id}"

六、服务器行为配置

1. 重复提示处理

mcp = FastMCP(on_duplicate_prompts="error")  # 冲突时报错@mcp.prompt
def welcome():return "欢迎使用"@mcp.prompt  # 重复注册会抛出异常
def welcome():return "您好"

• 策略包括："warn"（默认，警告并替换）、"error"（报错）、"replace"（静默替换）、"ignore"（忽略新注册）

七、核心功能总结

功能模块	核心特性
定义方式	@mcp.prompt 装饰器，支持同步/异步函数，类型注解增强
参数处理	自动转换字符串参数为原生类型，生成JSON schema指导LLM输入
返回值类型	支持字符串、消息对象、消息列表，自动转换为MCP标准格式
生命周期控制	动态启用/禁用，支持运行时状态切换
上下文交互	访问请求ID、客户端信息等运行时数据，增强提示动态性

提示（Prompts）是 FastMCP 中衔接 LLM 与应用逻辑的关键组件，通过参数化模板设计，既能保证交互标准化，又能灵活应对复杂场景，尤其适合需要多轮对话或结构化输出的 AI 应用开发。

FastMCP 上下文（Context）技术文档详解

一、Context 的核心概念与作用

FastMCP 上下文（Context）是连接 MCP 功能与应用逻辑的桥梁，提供了在工具、资源、提示等组件中访问 MCP 核心能力的统一接口。其核心作用包括：

• 运行时交互：在函数执行过程中访问服务器功能（如日志、资源）
• 状态传递：携带请求元数据（如请求 ID、客户端标识）
• 能力扩展：支持 LLM 采样、进度报告等高级功能

Context 对象在请求处理期间自动注入，允许组件与 MCP 协议层深度交互，而无需关心底层实现细节。

二、Context 的获取方式

1. 依赖注入（推荐方式）

直接在函数参数中添加 Context 类型注解，FastMCP 会自动注入实例：

from fastmcp import FastMCP, Contextmcp = FastMCP(name="ContextDemo")@mcp.tool
async def process_file(file_uri: str, ctx: Context) -> str:"""处理文件，使用上下文进行日志和资源访问"""await ctx.info(f"开始处理文件: {file_uri}")return "文件处理完成"

2. 依赖函数（适用于嵌套调用）

通过 get_context() 函数在无法修改参数的场景中获取上下文：

from fastmcp.server.dependencies import get_contextasync def utility_function(data: list[float]) -> dict:ctx = get_context()  # 仅在请求处理中有效await ctx.debug(f"处理 {len(data)} 个数据点")return {"processed": len(data)}@mcp.tool
async def analyze_data(dataset: str) -> dict:data = load_data(dataset)return await utility_function(data)

三、Context 的核心能力

1. 日志系统

提供分级日志功能，支持调试、信息、警告和错误日志：

@mcp.tool
async def calculate_average(numbers: list[float], ctx: Context) -> dict:await ctx.info(f"开始计算 {len(numbers)} 个数字的平均值")try:avg = sum(numbers) / len(numbers)await ctx.info(f"计算完成，平均值: {avg}")return {"average": avg}except ZeroDivisionError:await ctx.warning("接收到空数据列表")return {"error": "数据列表为空"}except Exception as e:await ctx.error(f"计算失败: {str(e)}")raise

日志方法列表：

• ctx.debug(message)：调试信息（开发阶段使用）
• ctx.info(message)：正常执行信息
• ctx.warning(message)：非致命警告
• ctx.error(message)：错误信息
• ctx.log(level, message)：自定义级别日志

2. 进度报告

长任务中向客户端反馈进度，提升用户体验：

@mcp.tool
async def process_batch(items: list[str], ctx: Context) -> dict:total = len(items)for i, item in enumerate(items):# 报告进度（0-100%）await ctx.report_progress(progress=i, total=total)await asyncio.sleep(0.1)  # 模拟处理时间await ctx.report_progress(progress=total, total=total)  # 完成return {"processed": total, "results": [i.upper() for i in items]}

关键参数：

• progress：当前进度值（如已处理数量）
• total：总任务量（用于计算百分比）
• 注意：客户端需在请求中提供 progressToken 才能接收进度更新

3. 资源访问

读取服务器注册的资源数据：

@mcp.tool
async def summarize_document(uri: str, ctx: Context) -> str:# 读取资源内容content_list = await ctx.read_resource(uri)if not content_list:return "文档为空"document = content_list[0].content# 简单摘要逻辑words = document.split()await ctx.info(f"文档包含 {len(words)} 个单词")if len(words) > 100:return f"摘要: {' '.join(words[:100])}..."return f"全文: {document}"

方法签名：

ctx.read_resource(uri: str) -> list[ReadResourceContents]

4. LLM 采样（2.0.0+ 新特性）

在工具中调用客户端的 LLM 进行文本生成：

@mcp.tool
async def analyze_sentiment(text: str, ctx: Context) -> dict:# 生成情感分析提示prompt = f"分析以下文本的情感（正面/负面/中性）: {text}"# 调用客户端 LLMresponse = await ctx.sample(prompt,model_preferences="claude-3-sonnet",  # 模型偏好temperature=0.7,max_tokens=50)# 处理结果sentiment = response.text.strip().lower()return {"text": text, "sentiment": sentiment}

高级用法：

@mcp.tool
async def generate_code(concept: str, ctx: Context) -> str:# 复杂提示（系统提示+用户消息）response = await ctx.sample(messages=["你是专业 Python 程序员，提供简洁可运行的代码示例",f"编写演示 '{concept}' 的 Python 代码示例"],temperature=0.5)return f"```python\n{response.text}\n```"

5. 请求信息获取

访问当前请求的元数据：

@mcp.tool
async def get_request_info(ctx: Context) -> dict:return {"request_id": ctx.request_id,       # 请求唯一标识"client_id": ctx.client_id or "未知", # 客户端标识"session_id": ctx.session_id,       # 会话 ID（HTTP 传输）}

四、高级访问能力

1. 服务器与会话访问

@mcp.tool
async def server_info(ctx: Context) -> str:# 访问服务器实例server_name = ctx.fastmcp.name# 底层会话访问（高级场景）session = ctx.sessionrequest_context = ctx.request_contextreturn f"服务器: {server_name}, 会话 ID: {session.session_id}"

2. HTTP 请求访问（2.2.7+ 特性）

@mcp.tool
async def http_request_info(ctx: Context) -> dict:# 获取 HTTP 请求对象（Web 场景）request = ctx.get_http_request()return {"user_agent": request.headers.get("user-agent", "未知"),"client_ip": request.client.host if request.client else "未知","path": request.url.path}

五、Context 的应用场景

1. 调试与监控：在工具中记录关键操作日志，便于问题定位
2. 长任务反馈：文件处理、数据导入等场景中实时显示进度
3. 上下文感知：根据请求来源（客户端 ID）提供个性化响应
4. LLM 协同：工具执行过程中调用 LLM 进行二次处理
5. 资源联动：工具与资源数据动态交互（如读取配置后执行逻辑）

六、核心要点总结

功能模块	核心特性
获取方式	依赖注入（参数注解）与依赖函数（get_context()），自动生命周期管理
日志系统	四级日志分级，支持自定义日志级别，日志随请求上下文传递
进度报告	支持百分比进度显示，需客户端配合 progressToken
LLM 采样	在工具中调用客户端 LLM，支持系统提示、模型偏好等高级参数
请求元数据	包含请求 ID、客户端 ID、会话 ID 等，用于追踪和权限控制
高级访问	服务器实例、HTTP 请求等底层访问，满足复杂场景扩展需求

Context 是 FastMCP 中实现组件与协议层交互的核心机制，通过它可以将工具、资源等功能与 MCP 的日志、进度、LLM 等能力无缝结合，构建更强大的 AI 应用系统。