MCP Python SDK · 附录 A 术语表 · 速查 · 排错

MCP Python SDK · 附录 A 术语表 · 速查 · 排错

章节摘要:这是全书的检索入口,一个你在任何章节卡壳时都可以回头翻的地方。它由三块构成:一是术语表,把全书出现过的核心术语按主题归类,给中英对照与一句话含义,供快速回忆;二是API 与命令速查表,把高频的公开 API(MCPServer 装饰器、Client 方法、传输参数、mode 取值)与命令行(mcp dev / mcp run / mcp install)压缩成可查的表;三是常见报错与排查,把高频报错(连接打不开、能力不声明、协议版本不匹配、引导填写失效、Windows 子进程卡住等)按「报错→原因→排查」三列给出。附录还单独设一节集中处理 v1(FastMCP)→v2(MCPServer)迁移要点——这是网上旧教程最容易误导读者的地方。读完本附录,你将拥有一份随手可查的备忘录。

学习目标

阅读完本附录,你应当能够:

1. 用术语表快速回忆全书任意一个核心概念的中英文名与含义,并定位它首次出现的章节。
2. 用 API 与命令速查表在写代码时快速查到高频装饰器、客户端方法、传输参数、CLI 命令的用法。
3. 用报错排查表按症状定位常见问题的原因与解决方案,覆盖连接、能力、协议版本、引导填写、平台差异等高频坑。
4. 用 v1→v2 迁移要点把存量 FastMCP / 旧 ClientSession 代码改写成 v2 写法,避免被网上旧资料误导。

核心概念速览

整章逻辑可浓缩为一句话:附录是全书的「索引层」——术语表帮你回忆概念,速查表帮你查 API,排错表帮你救急,迁移要点帮你对抗网上旧资料,四者合起来让你在阅读和实战中随时有据可循。

子章节导航

01 术语表:按主题归类的中英对照

把全书术语按五大主题归类——协议与角色(Host/Client/Server/MCP)、三大原语(Tool/Resource/Prompt)、能力与交互(Capability/Elicitation/MRTR/Sampling)、传输(Transport/Streamable HTTP/SSE)、客户端与扩展(Client/ClientSessionGroup/Extension/Middleware)。每条给中文名、英文名、一句话含义、首次出现章节。这份表会随全书写作持续扩充。

02 API 与命令速查表

高频内容压缩成表:服务端装饰器(@mcp.tool / @mcp.resource / @mcp.prompt / @mcp.completion / @mcp.custom_route)及其关键参数;Client 核心方法(call_tool / list_tools / read_resource / get_prompt)的签名与返回;传输参数(stdio 的命令与环境、流式 HTTP 的路径与超时);协议 mode 取值对照;CLI 命令(mcp dev / mcp run / mcp install / mcp version)。

03 常见报错与排查

按高频症状组织的「报错→原因→排查」三列表:连接类(子进程不启动、HTTP 连不上、握手失败)、能力类(工具不出现、能力未声明、补全不工作)、协议版本类(mode 不匹配、legacy 与现代特性冲突)、交互类(引导填写失效、MRTR 卡住、采样不可用)、平台类(Windows 子进程卡住、路径与编码问题)。每条给可直接执行的排查步骤。

04 v1→v2 迁移要点(集中维护)

单独一节,集中处理 v1 旧代码与网上旧教程的命名差异:FastMCP → MCPServer;旧 ClientSession 写法 → 第一类 Client;v1 的引导填写直接发起 → v2 的 Resolve 返回 Elicit + MRTR;采样与根的弃用趋势。给一张「旧写法→新写法」的对照表,让维护存量代码的读者快速迁移。

子章节之间的逻辑关系

本附录是工具性的,四节之间是「查概念 → 查 API → 救急 → 迁移」的查阅路径,可任意跳转:

术语表 (01) ── 概念回忆
   │
   ▼
速查表 (02) ── 写代码时查 API
   │
   ▼
排错 (03)   ── 出问题时救急
   │
   ▼
迁移 (04)   ── 改旧代码时对照
​

术语表是认知入口,速查表是编码入口,排错表是实战入口,迁移要点是存量代码入口。四节覆盖了「读、写、救、迁」四类需求,你可以在任何场景按需跳入。本附录不追求一次写死,会随全书各章连载持续扩充。

前置知识与后续延伸

前置知识:

• 本附录是全书各章概念的总汇,无独立前置;遇到陌生术语时,按术语表指向的章节回查正文。

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

• 本附录是全书的终点,也是后续实战的起点——它在你写代码、排查问题、迁移旧项目时反复被查阅。
• 术语表会随第 1~12 章连载同步扩充,迁移要点会随 v2 演进持续更新。
• 速查表与排错表是日常工作时 bookmark 的对象。