FastMCP 2.x 快速入门教程

FastMCP 2.x 是 MCP（Model Context Protocol）生态里少见的「把协议细节收起来、把开发体验露出来」的框架。这份资料围绕它展开，从最基础的 server 定义，一路走到 FastMCP Cloud 上的部署，配套有可直接对照的源码与章节笔记。对已经写过一两个 MCP demo、但卡在「怎么组织成能交付的项目」这一步的开发者来说，它的价值不在视频本身，而在你能拿它当参照物，边看边改自己的代码。

技术栈与运行环境

课程主体是 Python，核心依赖就是 FastMCP 2.x 本身。它用装饰器把 tool、resource、prompt 三类 MCP 原语映射成普通函数，写法接近 Flask / FastAPI 那种轻量风格，所以如果你写过任何一个 Python Web 框架，迁移成本很低。传输层涉及 stdio 与 HTTP/SSE 两种模式，前者用于本地宿主（如各类 MCP 客户端）直连，后者面向远程调用与云端部署。资料里对这两个模式分别给了可运行的配置，不是只讲概念。

需要留意版本边界：2.x 相比 1.x 在 API 命名、上下文对象、认证接入上有调整，网上大量旧示例直接抄会报错。这份资料以 2.x 为准，适合拿来校正你手里那些过时的片段。

项目结构与代码组织方式

MCP 项目最容易写散的地方在于：工具函数、资源、配置、启动入口混在一个文件里，几十行之后就难以维护。课程给出的组织方式是把 server 实例的创建、原语注册、传输配置分层放置，tool 与 resource 各自独立成模块，通过统一入口组装。这种拆分不是为了好看，而是因为 MCP server 往往要同时暴露多个能力，宿主端对返回结构又有严格约束，分层后调试时能快速定位是哪个原语出的问题。

配套源码里能看到类型标注、返回值的序列化处理、异常如何转成 MCP 能识别的错误响应。这些细节在纯概念讲解里通常被跳过，但恰恰是实际部署时最常踩的坑。

可复用的几个模块

• 工具注册与参数校验：把函数签名转成 MCP 的输入 schema，是理解协议落地方式的最佳切入口，可以直接复用到自己的 server。
• 上下文与状态传递：请求级别的 context 怎么拿到、能拿到什么，决定了你能不能写出带会话状态的服务。
• 认证与鉴权接入：面向远程部署时，谁可以调用哪个 tool，这部分在本地 stdio 模式下不涉及，但上云必须处理。
• 部署配置：从本地运行到 FastMCP Cloud，环境变量、入口命令、传输方式的差异，是这份资料里最偏工程的一段。

把这四块拆开单独看，每一块都可以脱离课程放进你自己的项目骨架里。

建议的自学路径

不要按「看完再动手」的节奏走。更有效的做法是：先跑通最小的单 tool server，确认本地宿主能正常调用；然后照着资料把 resource 和 prompt 补上，观察协议层面的差异；接着引入认证，切到 HTTP/SSE 模式在本地模拟远程调用；最后再走一遍 Cloud 部署流程。每完成一步就回看对应章节，比对源码里的写法与自己的差异。

章节笔记适合在两次学习之间做复盘，尤其是 API 命名和配置项这类容易记混的内容。学完之后建议自己写一个真实用途的小 server，比如把某个内部脚本包装成 tool，这比复刻示例更能暴露问题。

适合谁，不适合谁

适合已经了解 MCP 是什么、需要一个可落地工程参考的开发者；也适合想把已有 Python 函数快速暴露给 MCP 宿主的人。不适合完全没接触过 Python 异步与装饰器写法、指望从零讲起语法的读者——这份资料的重心在框架使用与部署，不在语言基础。

当作对照实践的参考手册，比当作线性视频课来刷，收益更高。