附录 A.3 常见报错排查与 v1→v2 迁移

附录 A.3 常见报错排查与 v1→v2 迁移

本节摘要:附录最后一节,两部分内容。第一部分是常见报错与排查——按高频症状组织的「报错→原因→排查」三列表,覆盖连接、能力、协议版本、交互、平台五类问题。第二部分是 v1(FastMCP)→v2(MCPServer)迁移要点——给一张「旧写法→新写法」的对照表,让维护存量代码的读者快速迁移。本节是实战救急与版本迁移的入口。

一、常见报错:连接类

二、常见报错:能力类

三、常见报错:协议版本类

四、常见报错:交互类

五、常见报错:平台类(Windows)

六、v1→v2 迁移要点

网上大量教程是 v1 写法(FastMCP、旧 ClientSession),直接照抄会报错。下面是迁移对照表。

核心命名变化

工具定义:基本一致

# v1
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("Demo")

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

# v2(几乎一样,只改导入与类名)
from mcp.server import MCPServer
mcp = MCPServer("Demo")

@mcp.tool()
def add(a: int, b: int) -> int:
    return a + b
​

客户端:v2 简化

# v1(手动管理会话)
from mcp import ClientSession
async with stdio_client(params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        result = await session.call_tool("add", {...})

# v2(第一类 Client,自动管理)
from mcp import Client
async with Client("http://...") as client:    # 自动选传输、协商、初始化
    result = await client.call_tool("add", {...})
​

引导填写:v2 现代写法

# v1(服务端直接发起)
result = await ctx.elicit(message="...", schema={...})

# v2 现代连接(Resolve 返回 Elicit + MRTR,推荐)
async def get_input(ctx):
    return resolve.Elicit(message="...", schema={...})

@mcp.tool()
def op(confirmed: Annotated[bool, Resolve(get_input)]) -> ...: ...

# v2 legacy 连接(ctx.elicit 仍可用)
result = await ctx.elicit(message="...", schema={...})
​

协议版本:v2 默认现代

# v2 默认走现代协议(2026-07-28),无握手
async with Client(url) as client: ...              # mode="auto",优先现代

# 如需强制 legacy
async with Client(url, mode="legacy") as client: ...
​

弃用项

七、迁移建议

💡 技巧:迁移的核心是「换名字 + 换写法」。FastMCP→MCPServer 换名字;客户端从手动 ClientSession→第一类 Client 换写法;引导填写从 ctx.elicit→Resolve+Elicit 换写法。业务逻辑(工具函数体)基本不变——这是 SDK 设计的连续性。

本节要点回顾

1. 五类常见报错:连接、能力、协议版本、交互、平台,各有「报错→原因→排查」表。
2. 能力问题排查第一步:print(client.server_capabilities) 看声明了什么。
3. 交互问题排查:检查 is_error、客户端能力声明、协议模式。
4. Windows 平台:编码、路径、命令名、进程清理是高频坑。
5. v1→v2 核心:FastMCP→MCPServer、手动 ClientSession→第一类 Client、ctx.elicit→Resolve+Elicit。
6. 业务逻辑基本不变,迁移主要是换名字与换写法。
7. 新项目全程 v2,存量 v1 规划迁移,网上教程要认出 v1 写法翻译。

附录与全书结束。你已经拥有了从入门到精通 MCP Python SDK 的完整知识体系。