技能使用指南

fastmcp-server（FastMCP3.0开发技能）Skill 是什么？

fastmcp-server 技能是面向 FastMCP 3.0 的完整开发指南，覆盖工具、资源、上下文、认证授权、中间件与提供者等 30 个参考文件，帮你用 Python 快速搭建生产级 MCP 服务器并完成 2.x 升级。零依赖、MIT 协议，安装即用，让 AI 按权威资料写代码，少踩版本坑。

FastMCP3.0服务器开发技能Skillfastmcp-server
8 个章节 约 18 分钟阅读 AI 智能生成

FastMCP3.0服务器开发技能Skill：用 Python 快速构建生产级 MCP 服务器

  • 它是什么：一个面向 FastMCP 3.0 的完整开发参考技能，覆盖工具、资源、上下文、认证、授权、中间件、提供者与部署等 7 大类、30 个参考文件。
  • 解决什么痛点：FastMCP 从 2.x 到 3.0 有较多变化，认证、中间件、提供者等高级用法资料分散，AI 助手容易写出过时代码，这个技能把权威知识打包给模型。
  • 核心能力：以 @mcp.tool、@mcp.resource、@mcp.prompt 装饰器为核心的 Pythonic 写法，配合 Context、Depends()、BearerAuthProvider 等能力快速搭建生产级 MCP 服务。
  • 适合谁用：要把 AI 模型与内部工具、数据打通的 Python 后端工程师、AI 应用开发者、平台架构师，以及正在做 2.x → 3.0 升级的维护者。
  • 使用门槛：技能本身依赖项为空（dependencies: []），MIT 协议，安装后即可在对话中直接调用，无需额外配置。

该技能叫什么？如何一键安装 AI 技能提升开发效率？

技能基本信息

项目 内容
中文名 FastMCP3.0服务器开发技能Skill
英文名 fastmcp-server
技能 ID 12203
版本 1.0.0
作者 FastMCP 社区
许可证 MIT
标签 FastMCP、MCP、Python、AI、工具、服务器、认证、提供者

它到底解决什么问题

MCP（模型上下文协议）已经成为把大模型连接到外部工具和数据的通用方式，而 FastMCP 是其中最流行的 Pythonic 框架之一。但真实开发中常见三类困境：一是框架版本迭代快，网上流传的示例大量停留在 FastMCP 2.x 写法；二是认证、授权、中间件、提供者这些"生产必备"能力分散在多篇文档里，难以系统掌握；三是开发者向通用 AI 助手提问时，模型容易凭空编造 API 名称或参数。

这个技能本质上是一份结构化、可被 AI 直接检索的 FastMCP 3.0 权威知识包：它把工具与资源、上下文与依赖注入、认证、授权、中间件、提供者、高级功能等内容拆成 30 个参考文件，按目录组织在 references/ 下，让 AI 在回答时能"查着资料写代码"，而不是凭记忆猜 API。

一键安装的通用思路与步骤

  1. 确认前提：你使用的是一个支持 AI 技能（Skill）机制的客户端或开发环境；本地具备 Python 运行环境，便于验证生成的代码。若需要运行 FastMCP 本身，通常通过 pip 安装 fastmcp 包（具体安装方式与可选依赖以官方说明为准）。
  2. 找到安装入口：在你所用平台的技能市场 / 插件中心中搜索技能名 fastmcp-server 或技能 ID 12203，点击安装即可。不同平台的入口位置不同，具体路径以官方说明为准。
  3. 验证是否生效：安装后在对话中提出一个针对性问题，例如"用 FastMCP 3.0 写一个带 @mcp.tool 的加法服务器，并说明如何用 SSE 传输启动"。如果回答中出现 from fastmcp import FastMCP、@mcp.tool 装饰器以及 mcp.run(transport="sse", host="0.0.0.0", port=8000) 这类 3.0 写法，并主动引用技能内的参考资料，就说明技能已生效。
  4. 养成引用习惯：提问时明确说"请按 fastmcp-server 技能中的 references 目录规范回答"，可以让模型更稳定地走查阅路径，而不是自由发挥。

这种"把领域知识打包成技能、按需调用"的方式，最大的效率价值在于：你不需要每次重新解释框架版本、项目结构与最佳实践，模型一开始就站在正确的知识底座上。

该技能的主要功能和特点

  • 工具（Tools）：用 @mcp.tool 装饰器把普通 Python 函数变成 LLM 可执行能力，支持 Pydantic 参数验证、异步函数、自定义返回类型以及 readOnlyHint、destructiveHint 等注解，让模型知道哪些操作"只读安全"、哪些"有破坏性"。
  • 资源与资源模板：资源用固定 URI 标识（如 data://config），模板用参数化 URI（如 users://{user_id}/profile），支持 MIME 类型、注解与通配符参数，适合暴露配置、文件、数据库记录等静态或动态数据源。
  • 提示（Prompts）：用 @mcp.prompt 定义可复用的提示模板，例如把"代码审查"沉淀成一个带 code、language 参数的提示，供客户端直接调用。
  • 上下文与进度反馈：Context 对象让工具内部可以写日志（ctx.info）、上报进度（ctx.report_progress）、读取资源（ctx.read_resource）、请求 LLM 采样、向用户征求结构化输入，让长任务不再"黑箱"。
  • 依赖注入：通过 Depends() 把 HTTP 请求、访问令牌、自定义依赖注入到工具/资源函数中，并支持基于生成器的清理模式，代码更干净、更易测试。
  • 认证能力完整：涵盖令牌验证（JWT、JWKS、内省、静态密钥、自定义）、远程 OAuth 委托、OAuth 代理（含 PKCE）、OIDC 代理（自动发现）以及完整的内置 OAuth 服务器。示例中的 BearerAuthProvider 只需配置 jwks_uri、audience、issuer 即可启用。
  • 授权与中间件：支持基于范围和角色的访问控制；中间件可拦截和修改请求/响应，内置了速率限制、错误处理、日志记录、响应大小限制等常用中间件，也支持用 @mcp.middleware 写自定义逻辑。
  • 提供者（Providers）：LocalProvider（默认，基于装饰器）、FileSystemProvider（从磁盘 Python 文件加载组件）、SkillsProvider（打包分发组件捆绑）以及自定义提供者，决定了"组件从哪里来"，便于做多项目复用。
  • 生产级高级功能：分页、采样、存储后端（内存 / 文件 / Redis）、OpenTelemetry 分布式追踪、组件版本化与按版本范围过滤、生命周期钩子、自定义图标等。
  • 工程化与可迁移：技能自带从 FastMCP 2.x 迁移到 3.0 的升级指南，配有安装、快速上手、服务器、上下文、功能、认证、授权、提供者等完整目录结构，便于按需深挖。
  • 轻量与零依赖：技能的 dependencies 为空数组，不需要额外安装第三方包即可加载，不污染开发环境。

和"直接搜索引擎 + 通用代码补全"相比，它的差异化在于版本确定性（明确面向 3.0）与结构完整性（从写第一个工具到上线鉴权、遥测一应俱全），避免"能跑 demo、上不了生产"的典型断层。

如何使用该技能？

第 1 步：安装并确认技能可用

在技能市场搜索 fastmcp-server 或技能 ID 12203 完成安装（入口以官方说明为准），随后用一个最小问题验证技能是否被正确加载。

第 2 步：用自然语言描述目标，明确要求查阅技能资料

输入示例：

我要用 FastMCP 3.0 写一个员工信息查询服务器，包含一个 get_employee 工具（参数为员工 ID）和一个 employees://{emp_id}/profile 资源模板，并且工具执行时要有日志和进度上报。请按 fastmcp-server 技能里的工具、资源、上下文章节给出完整代码。

第 3 步：拿到骨架代码并直接运行

技能内的核心写法大致如下，可作为生成结果的对照基准：

from fastmcp import FastMCP, Context

mcp = FastMCP("EmployeeServer")

@mcp.tool
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b

@mcp.resource("employees://{emp_id}/profile")
def get_employee_profile(emp_id: str) -> dict:
    """Get an employee's profile by ID"""
    return fetch_employee(emp_id)

@mcp.tool
def process_data(uri: str, ctx: Context) -> str:
    """Process data with logging and progress"""
    ctx.info(f"Processing {uri}")
    ctx.report_progress(0, 100)
    data = ctx.read_resource(uri)
    ctx.report_progress(100, 100)
    return f"Processed: {data}"

if __name__ == "__main__":
    mcp.run(transport="sse", host="0.0.0.0", port=8000)

第 4 步：按需求叠加认证与中间件

输入示例：

这个服务器要对外网开放，请用 JWT 校验接入，只允许 mcp:read 范围的调用者访问只读工具，并加上速率限制中间件。给出认证配置和授权方案。

预期输出：一段以 BearerAuthProvider(jwks_uri=..., audience=..., issuer=...) 构造认证对象、并传入 FastMCP("SecureServer", auth=auth) 的代码，再配合中间件与范围校验的说明。

第 5 步：处理长任务与生产化细节

继续追问进度上报、后台任务、分页、存储后端、OpenTelemetry 埋点、组件版本化等，技能会按 references/features/ 中的分类给出对应做法。

第 6 步：迁移与回归

若你手上是 FastMCP 2.x 项目，直接说"按技能中的 upgrade-guide 帮我列出从 2.x 到 3.0 的改动点和改造清单"，可以得到一份可执行的迁移路径，而不是零散猜测。

输出说明：该技能输出的是代码 + 解释性文档的组合，通常会包含目录说明（例如"详见 references/authentication/token-verification.md"）、可直接粘贴运行的示例，以及针对边界情况的提示。最终仍需在本地跑通测试，尤其是认证与授权部分，务必自行验证。

同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
fastmcp-server（本技能） 面向 FastMCP 3.0 的结构化开发知识技能 工具/资源/提示、上下文、依赖注入、认证授权、中间件、提供者、遥测、升级指南共 30 个参考文件 低：技能零依赖，安装后在对话中调用；需 Python 环境验证代码 从零搭建 MCP 服务器、加鉴权、从 2.x 升级 优势是版本明确、体系完整、可直接驱动 AI 产出代码；不足是仅覆盖 FastMCP 生态，其他框架需另找方案
查阅 FastMCP 官方文档 + 通用 AI 助手 传统"人查文档 + AI 补全" 文档权威但需要人工筛选，AI 回答依赖训练数据 中：需要自己判断版本、拼装上下文 简单工具函数、快速试错 优势是信息源原始；不足是版本混淆风险高，高级主题（OAuth 代理、自定义提供者）容易得到过时或臆造的答案
官方 MCP Python SDK 直接开发 底层协议实现方案 提供协议层原语，灵活度高 较高：需自行处理协议细节、路由、校验 需要深度定制协议行为、非 FastMCP 风格项目 优势是可控性最强；不足是样板代码多，认证、中间件等能力需自建
通用 Agent/工具编排框架封装 把函数注册为"工具"供模型调用 工具注册、调用链、部分内置追踪 中：需学习框架自身抽象 已有框架技术栈、希望复用其生态 优势是生态成熟；不足是与 MCP 协议标准不完全等价，跨客户端互通性和鉴权模型需要额外适配

结论上，如果你确定用 Python + MCP 标准协议做服务器，本技能是启动成本最低、知识密度最高的路径；如果你要做协议层深度改造，则应以官方 SDK 为主、本技能为辅。

该技能的典型应用场景与实际体验情况

场景一：后端工程师把内部系统"接入 AI"

角色：某 SaaS 公司 Python 后端工程师。痛点：产品经理想让 AI 助手直接查订单、查工单，但团队没有 MCP 开发经验，不确定工具如何声明、参数如何校验、异常如何返回。使用方式：安装技能后直接描述"订单查询 + 工单创建两个工具，含只读/破坏性注解"，让模型按技能资料产出可运行骨架。实际体验：上手难度低，生成的代码结构规范、注解齐全；注意事项是业务鉴权逻辑仍需自己实现，技能提供的是框架层能力而非业务规则。

场景二：给桌面 AI 客户端接入本地数据能力

角色：效率工具开发者。痛点：想让自己的 MCP 服务器暴露本地配置文件与项目目录，需要资源模板和通配符参数。使用方式：向技能询问"data://config 与 users://{id}/profile 的区别，以及 MIME 类型如何声明"，并生成资源模板代码。实际体验：对资源与模板的边界解释清楚，URI 设计与通配符用法一次到位；注意模板参数类型要显式标注，否则客户端调用时容易报参数不匹配。

场景三：面向公网的远程 MCP 服务加认证

角色：平台架构师 / 安全负责人。痛点：服务要开放给第三方客户端，必须做 JWT 校验与范围授权，还要限流。使用方式：让技能给出 BearerAuthProvider 配置、范围校验方案与速率限制中间件组合。实际体验：这是该技能价值最突出的部分——令牌验证、OAuth 代理、OIDC 代理、完整 OAuth 服务器四条路径讲得比较分明，能帮助团队做架构取舍；注意事项是 JWKS 地址、audience、issuer 必须与真实身份提供方一致，务必在测试环境先跑通再上线。

场景四：老项目从 FastMCP 2.x 升级到 3.0

角色：维护既有 MCP 服务的开发者。痛点：升级后部分写法失效，团队不清楚改动范围。使用方式：要求技能按升级指南输出改动清单与改造顺序。实际体验：能得到结构化的迁移路径，减少"边改边踩坑"的时间；注意升级后要重点回归认证、中间件和组件注册方式这三块，因为它们变化最集中。

该技能能为用户带来的价值

  • 压缩学习曲线：把 30 个参考文件的知识压缩成"提问即得"的对话式教学，新手可以在一个下午完成从"不知道 MCP 是什么"到"跑通一个带工具的服务器"的跨越。
  • 显著降低试错成本：版本确定性是最直接的价值。面向 3.0 的写法规避了 2.x 遗留写法带来的返工，按经验估算，仅"查清正确 API 与参数"这一项，单次开发即可节省数小时检索与调试时间。
  • 让 AI 产出更可靠：把权威资料作为技能挂载给模型，等同于给 AI 配了一本"随查随用"的手册，能明显减少虚构 API、错误装饰器名称等幻觉问题。
  • 覆盖从原型到生产的全链路：工具、资源、上下文只是起点，认证、授权、中间件、存储、遥测、版本控制才是上线门槛。一个技能打通全链路，避免"demo 很美、上线很难"。
  • 长期可维护性收益：技能内的目录结构与命名规范本身就是一套工程约定，团队可以据此形成统一的代码组织方式，新人接手成本更低。
  • 零成本接入：MIT 协议、dependencies 为空，不引入额外依赖与授权风险，个人开发者与商业团队都可放心使用。

常见问题 FAQ

Q1：这个技能怎么安装？需要额外装什么依赖吗？

在支持技能机制的平台中搜索技能名 fastmcp-server 或技能 ID 12203 即可安装，具体入口与操作步骤以官方说明为准。技能本身依赖项为空数组、采用 MIT 协议，不需要额外安装依赖。若要在本地真正运行生成的服务器，通常需要通过 pip 安装 fastmcp 包，具体安装方式与可选依赖以官方说明为准。

Q2：使用这个技能收费吗？

技能信息中标注为 MIT 许可证、作者为 FastMCP 社区，属于开放许可的技能包。至于你所在平台本身是否收费、有无调用额度限制，取决于平台策略，以官方说明为准。

Q3：它适合谁用？完全不懂 MCP 的新手能用吗？

适合三类人：一是准备用 Python 搭建 MCP 服务器的后端与 AI 应用开发者；二是需要给服务加认证、限流、可观测性的平台与安全同学；三是正在把项目从 FastMCP 2.x 迁移到 3.0 的维护者。新手也能用，但建议先具备基础的 Python 与 HTTP 认证概念，否则对 OAuth 代理、JWKS 这类内容的理解会打折扣。

Q4：它和我直接问通用 AI 助手写 FastMCP 代码有什么区别？

差别主要在两点：版本与结构。通用助手容易混用不同版本的 API，遇到认证、中间件、提供者等冷门主题时更易臆造；本技能把 3.0 的知识按 7 大类、30 个参考文件组织好，模型可以"查着写"。建议提问时明确要求"按 fastmcp-server 技能的参考资料回答"，效果更稳定。

Q5：生成的代码能直接上生产吗？

可以作为高质量起点，但不建议直接上线。技能提供的是框架用法与最佳实践，业务校验、密钥管理、日志脱敏、压测与安全评审仍需团队自行完成。尤其是认证与授权部分，务必在测试环境完整验证 JWKS 地址、audience、issuer 与范围规则后再对外开放。