FastMCP 是一个用 Python 构建 Model Context Protocol（MCP）服务器的框架，用于向 Claude 等大语言模型暴露工具、资源和提示。该技能提供经过生产验证的模式、错误预防与部署策略，帮助构建健壮的 MCP 服务器。
一、快速开始 安装： pip install fastmcp
或
uv pip install fastmcp
最小服务器示例（FastMCP 实例必须位于模块层级，以便 FastMCP Cloud 使用）： from fastmcp import FastMCP mcp = FastMCP("My Server")
@mcp.tool() async def hello(name: str) -> str: """Say hello to someone.""" return f"Hello, {name}!"
if name == "main": mcp.run()
运行方式：
本地开发
python server.py
使用 FastMCP CLI
fastmcp dev server.py
HTTP 模式
python server.py --transport http --port 8000
二、版本更新要点 v2.14.x（2025 年 12 月）：
- v2.14.2：MCP SDK 固定为 <2.x 以保持兼容；Supabase provider 新增 auth_route 参数；修复 outputSchema $ref 解析、OAuth Proxy 校验、OpenAPI 3.1 支持等问题。
- v2.14.1：Sampling with Tools（SEP-1577），ctx.sample() 现可接受 tools 以支持智能体工作流；AnthropicSamplingHandler 从实验性提升为正式；新增 ctx.sample_step() 用于单次 LLM 调用并返回 SampleStep；新增 Python 3.13 支持。
- v2.14.0：后台任务（SEP-1686），协议原生后台任务用于长时间运行操作；在异步装饰器上添加 task=True；支持 MCP 2025-11-25 规范；SEP-1699 SSE 轮询与事件可恢复性；SEP-1330 多选枚举 elicitation schema；SEP-1034 elicitation schema 默认值。
- v2.14.0 破坏性变更：移除 BearerAuthProvider 模块（改用 JWTVerifier 或 OAuthProxy）；移除 Context.get_http_request() 方法；移除 fastmcp.Image 顶层导入（改用 from fastmcp.utilities import Image）；移除 enable_docket、enable_tasks 设置（始终启用）；移除 run_streamable_http_async()、sse_app()、streamable_http_app()、run_sse_async() 方法；移除装饰器的 dependencies 参数；取消 output_schema=False 支持；弃用 FASTMCP_SERVER_ 环境变量前缀。
v3.0.0（Beta，2026 年 1 月）：重大破坏性变更，为完整架构重构。
- Provider 架构：所有组件通过 Provider 获取。FileSystemProvider 从目录发现被装饰函数并支持热重载；SkillsProvider 将 agent 技能文件暴露为 MCP 资源；OpenAPIProvider 从 OpenAPI 规范自动生成；ProxyProvider 代理到远程 MCP 服务器。
- Transforms（组件中间件）：无需修改源码即可修改组件，包括 Namespace、重命名、按版本过滤、ResourcesAsTools（将资源暴露为工具）、PromptsAsTools（将提示暴露为工具）。
- 组件版本化：@mcp.tool(version="2.0")，客户端默认看到最高版本，也可请求特定版本。
- 会话作用域状态：通过 ctx.set_state / ctx.get_state 在会话间持久化状态。
- 其他特性：--reload 开发自动重启标志；同步函数自动线程池调度；工具超时；OpenTelemetry 追踪；组件授权 @tool(auth=require_scopes("admin"))。
- 迁移：未准备好可固定 v2（requirements.txt 中写 fastmcp<3）；多数服务器只需更新导入即可兼容 v2.x 与 v3.0。
三、核心概念
- 工具（Tools）：LLM 可调用的函数。最佳实践包括清晰命名、完整 docstring（LLM 会读取）、强类型提示（Pydantic 校验）、结构化返回、错误处理。I/O 操作建议使用 async。
- 资源（Resources）：向 LLM 暴露数据。URI 方案可用 data://、file://、resource://、info://、api:// 或自定义。模板参数名必须与函数参数名一致。
- 提示（Prompts）：带参数的预配置提示。
- Context 功能：注入 Context 参数（需类型提示）以使用高级功能，包括 Elicitation（请求用户输入）、Progress Tracking（进度跟踪）、Sampling（从工具内调用 LLM）。
四、后台任务（v2.14.0+） 用于长时间运行操作，在不阻塞客户端的情况下报告进度，使用 Docket 任务调度器（v2.14.0+ 始终启用）。任务状态：pending → running → completed / failed / cancelled。适用场景：超过 30 秒的操作（LLM 超时风险）、带逐项状态更新的批处理、执行中可能需要用户输入的操作、长时间运行的 API 调用或数据处理。已知限制（v2.14.x）：后台任务轮询期间 ctx.report_progress() 的 statusMessage 不会转发给客户端（GitHub Issue #2904），进度消息出现在服务器日志但不在客户端 UI；临时方案是改用官方 MCP SDK（mcp>=1.10.0）；修复待 PR #2906。注意：任务通过 Docket 调度器执行，无法通过代理执行任务（会报错）。
五、带工具的 Sampling（v2.14.1+） 服务器可向 ctx.sample() 传入工具，用于 LLM 在采样期间可调用工具的智能体工作流。可配置 AnthropicSamplingHandler（Claude 模型）或 OpenAISamplingHandler（GPT 模型）。ctx.sample_step() 返回 SampleStep 供检查。已知限制：当客户端连接单个服务器时 ctx.sample() 可用，但客户端配置多个服务器时会失败并报 "Sampling not supported" 错误；不含 sampling 的工具正常。（社区来源发现）
六、存储后端 基于 py-key-value-aio，用于 OAuth 令牌、响应缓存、持久状态。可用后端：Memory（默认，临时、快速、仅开发）、Disk（持久，使用 FernetEncryptionWrapper 加密，平台感知，Mac/Windows 默认）、Redis（分布式、生产、多实例），以及 DynamoDB、MongoDB、Elasticsearch、Memcached、RocksDB、Valkey。平台默认：Mac/Windows 使用 Disk，Linux 使用 Memory，可通过 storage 参数覆盖。
七、服务器生命周期 v2.13.0 破坏性变更：生命周期行为从每会话改为每服务器实例。资源初始化/清理每服务器一次（而非每会话），对数据库连接、API 客户端至关重要。ASGI 集成（FastAPI/Starlette）时必须传入 lifespan。状态管理通过 context.fastmcp_context.set_state / get_state。
八、中间件系统 8 种内置类型：TimingMiddleware、ResponseCachingMiddleware、LoggingMiddleware、RateLimitingMiddleware、ErrorHandlingMiddleware、ToolInjectionMiddleware、PromptToolMiddleware、ResourceToolMiddleware。执行顺序很重要：ErrorHandlingMiddleware（捕获错误）→ TimingMiddleware（计时）→ LoggingMiddleware（记录请求）→ RateLimitingMiddleware（检查限流）→ ResponseCachingMiddleware（检查缓存）→ 工具/资源处理器。支持自定义中间件，钩子层级为 on_message（全部）→ on_request/on_notification → on_call_tool/on_read_resource/on_get_prompt → on_list_*（列表操作）。
九、服务器组合 两种策略：import_server() 为静态快照，导入时一次性复制，变更不传播，速度快（无运行时委托），适用于最终确定的组件包；mount() 为动态链接，运行时实时链接，变更立即可见，运行时委托（较慢），适用于模块化运行时组合。支持标签过滤（include_tags / exclude_tags）。资源前缀格式：Path（v2.4.0 起默认）resource://prefix/path；Protocol（旧版）prefix+resource://path。
十、OAuth 与认证 4 种认证模式：Token 校验（JWTVerifier，校验外部令牌）、外部身份提供方（RemoteAuthProvider，OAuth 2.0/OIDC 配合 DCR）、OAuth 代理（OAuthProxy，桥接到不支持 DCR 的提供方，如 GitHub、Google、Azure、AWS、Discord、Facebook）、完整 OAuth（OAuthProvider，完整授权服务器）。OAuth Proxy 生产示例中需配置 jwt_signing_key、client_storage（加密存储）、上游授权/令牌端点、上游客户端 ID 与密钥等。
（注：资料在 OAuth Proxy 示例的 enable_consent_s 处截断，后续内容暂未提供。）