MCP Python SDK · 第 1 章 环境准备与首次跑通

MCP Python SDK · 第 1 章 环境准备与首次跑通

章节摘要:学一个 SDK 最怕在「装环境」上耗光耐心。本章的目标只有一个——让你在 5 分钟内写出第一个 MCP 服务端,并亲手调通一次工具调用。我们会先讲清 v2 版的安装方式(注意 mcp 与 mcp[cli] 的差别),再用一个最小服务端(一个工具加一个资源模板)让你看到三个装饰器如何替代手写 JSON Schema;然后用 SDK 自带的第一类 Client 在内存里直接连上它、调一次工具,验证「我没写一行协议,模型却已经能用了」;最后引入 MCP 检查器(Inspector)这个可视化调试工具,让你在图形界面里逐个原语地体验。读完本章,你将拥有一切后续学习所需的「跑得起来的代码」。

学习目标

阅读完本章,你应当能够:

1. 用正确的命令安装 MCP Python SDK 的 v2 版,并说清 mcp 与 mcp[cli] 两个安装选项的差别。
2. 写出一个包含一个工具、一个资源模板的最小服务端,并用 @mcp.tool()、@mcp.resource(uri) 装饰器完成注册。
3. 用 SDK 自带的第一类 Client 在内存里连上自己的服务端,调用工具并打印结果,验证端到端可用。
4. 启动 MCP 检查器(Inspector),在浏览器里可视化地查看工具列表、调用工具、读取资源。
5. 识别 v1(FastMCP)与 v2(MCPServer)的命名差异,避免被网上旧教程误导。

核心概念速览

整章逻辑可浓缩为一句话:MCP Python SDK 把「写一个让模型可调用的服务」压到了「写一个带类型注解的函数」的程度——你甚至不用启动一个真正的网络服务,内存连接就能验证一切。

子章节导航

01 版本要求与安装方式

讲清 Python 版本要求(3.10+),以及 mcp 与 mcp[cli] 两个安装选项的差别——后者多装一个命令行工具,能启动可视化检查器、注册到 Claude Desktop。顺带点明 v2 的现状:pip install mcp 默认装的就是 v2,旧版需另作约束。

02 最小可运行服务端:三大装饰器初体验

用一个「两数相加」工具加一个「问候」资源模板,展示 MCPServer 的构造与 @mcp.tool()、@mcp.resource(uri) 两个装饰器的用法。重点体会「类型注解即契约」——你不写一行 JSON Schema,SDK 替你生成。

03 内存客户端验证:不写一行协议就调通

引入第一类 Client,演示 async with Client(mcp) as client: 如何用内存连接连上刚才的服务端,然后 client.call_tool(...) 调用工具、client.read_resource(...) 读取资源。这是后续每一章的测试骨架。

04 用 MCP 检查器可视化调试

启动检查器(Inspector),在浏览器里逐个原语地查看工具表单、调用工具、读取资源模板。讲清它如何用 stdio 传输跑你的服务端文件,以及为什么它是开发期最顺手的调试工具。

子章节之间的逻辑关系

本章遵循「装好 → 写出 → 验证 → 可视化」的递进路径,每一步都为下一步建立信心:

安装 (01)   ── 装对版本,分清两个安装选项
   │
   ▼
最小服务端 (02) ── 三个装饰器,看到「类型即契约」
   │
   ▼
内存客户端 (03) ── 不写协议就调通,建立「真的能用」的信心
   │
   ▼
检查器 (04)  ── 图形界面逐原语体验,为后续调试打基础
   │
   ▼
第 2 章:从「能用」上升到「理解为什么这样设计」
​

这四节是一条信心链:不先装对版本,后续无从谈起;不写出最小服务端,看不到 SDK 的核心价值;不用客户端验证,「能用」就只是一句空话;而检查器把抽象的协议变成可见的界面,让你在后续章节遇到问题时知道去哪调试。

前置知识与后续延伸

前置知识:

• 会用命令行执行 Python 脚本
• 了解 pip 或 uv 等包管理工具的基本用法
• 对 Python 类型注解(如 a: int)与异步(async / await)有基本认识

本章为后续章节奠定的基础:

• 最小服务端是第 3 章(三大原语)的展开起点
• 内存客户端(Client(mcp))是全书所有示例的测试骨架,第 9 章会专门讲透
• 「类型注解即契约」的直觉是第 4 章(工具契约)的核心命题
• 检查器是后续每一章动手验证的常用工具