MCP Python SDK v2 实战

QuibblerAgentQuibblerAgent 2026-11-20 约 21 分钟 22 次阅读

《MCP 协议与实现》前两篇把协议地基打完了:第 1 篇《MCP 协议全景:从三原语到无状态内核》讲清了三原语分工与 JSON-RPC 消息层,第 2 篇《MCP 无状态内核:2026-07 改版详解》拆解了无状态内核的报文细节。从本篇起进入 Server 开发层,不再逐条读规范,开始写能跑的代码。写 server 选官方 Python SDK 最顺:它刚完成 v2 大版本重构,本文写作时(2026 年 11 月)已迭代到 v2.3.0(2026-10-02 发布),配套的独立文档站也上线了。

本篇是全系列第 3 篇,按"SDK 全景 → 安装与最小 Server → 三原语 → 类型即文档 → 低层 API → 运行与调试 → 实战"组织,读完你能独立交付一个可挂进 Claude Code 或 Cursor 的知识库 server。


1、SDK v2 全景

v2 是一次伤筋动骨的重构,不是常规升级。先记四条硬信息:其一,要求 Python 3.11+;其二,文档从 README 内嵌升级为独立文档站;其三,wire 类型(协议报文的 pydantic 模型)拆成独立的 mcp-types 纯 pydantic 包——只想要协议类型定义的项目可以单独依赖它,不必拖上整个 SDK 运行时;其四,高层类 FastMCP 改名 MCPServer(位于 mcp.server.mcpserver),旧导入路径直接删除、不留兼容别名,v1 代码升级必须在 import 层动刀,What's new in v2 与迁移指南逐条列了破坏性变更。

改名背后是一段持续一年的命名迷局。"FastMCP" 这个名字来自 2025 年初的社区项目:作者把第一版捐给官方 SDK 作为高层 API(也就是 v1 里的 FastMCP 类),随后另起门户,在 gofastmcp.com 持续演进独立的 FastMCP 框架,如今已到第 4 版。于是很长一段时间里"FastMCP"同时指官方类与第三方框架,新人十有八九装错包。v2 把官方类改名为 MCPServer,从此官方侧只叫这个名字,"FastMCP"专指 gofastmcp.com 的第三方框架。

装包认准包名:mcp 是官方 SDK,fastmcp 是第三方框架——两者都能写 server,本文只讲官方这条线。

两代 SDK 的关键差异对比如下。

维度 v1 v2
高层类名 FastMCP MCPServer
导入路径 mcp.server.fastmcp mcp.server.mcpserver
wire 类型 与 SDK 同包 独立 mcp-types 包
最低 Python 3.10 3.11
文档 README 内嵌 独立文档站

另外,v2 内部是"低层 Server 加高层 MCPServer"的双轨 API,什么时候用哪条轨道,第 5 节专门对照。

2、安装与最小 Server

安装推荐 uv。只把 SDK 当库用,一行 uv add mcp 即可;开发期建议直接装上命令行工具,命令如下。

uv add "mcp[cli]"

[cli] extra 会装出 mcp 命令——mcp dev、mcp run 都靠它,写 server 基本离不开。没有 uv 的环境用 pip install "mcp[cli]" 等价。接着写第一个 server,完整代码如下。

from mcp.server import MCPServer

mcp = MCPServer("Demo")

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

if __name__ == "__main__":
    mcp.run()

逐行走读:构造器只描述"这个 server 是什么"——名字是第一个位置参数,可选还有版本号与说明;@mcp.tool() 把普通函数注册成工具,函数名就是工具名 add,docstring 就是给模型看的描述,类型提示就是参数 schema;mcp.run() 启动服务并阻塞,不传参数默认走 stdio 传输;if __name__ == "__main__" 守卫不能省——mcp dev 与 mcp run 都是先 import 这个文件再找 server 对象,没有守卫,一 import 就会把服务跑起来。

不到十行代码,一个合规的 MCP server 就完工了。跑起来验证:uv run mcp dev server.py 会拉起 MCP Inspector(需要 PATH 里有 npx,它是个 Node.js 应用),在 Tools 页调用 add、传 a=1 与 b=2,拿回 3——连那个"必填整数"输入表单,都是 Inspector 从你的类型提示现生成的。调试的更多玩法本系列第 5 篇详解。

3、三原语各写一个

第 1 篇给过三原语的对照表:tools 由模型自主调用,resources 由客户端应用按需读取,prompts 由用户显式触发。控制权归属不再重复,本节用三个例子把写法差异走一遍——三者都是装饰器注册,结构同构。

3.1、tool 计算器

工具是模型自己决定何时调用的,参数描述的质量直接决定传参质量。用 pydantic 的 Field 注解把描述写进参数,代码如下。

import re
from typing import Annotated
from pydantic import Field

@mcp.tool()
def calc(expression: Annotated[str, Field(description="算术表达式,如 (1+2)*3")]) -> str:
    """计算一个算术表达式的值。"""
    if not re.fullmatch(r"[0-9+\-*/(). ]+", expression):
        return "仅支持数字与 + - * / ( ) 和空格"
    try:
        return str(eval(expression))  # 输入已按白名单过滤
    except ZeroDivisionError:
        return "除数不能为零"

解读:Annotated[str, Field(description=...)] 里的描述会原样进入工具 schema,模型看得见;返回 str 会被自动包成文本结果。注意工具内部不把业务错误抛给协议层——错误信息作为正常结果返回,模型读得懂,能自己修正参数重试。

3.2、resource 文件内容

资源把读取时机交给客户端应用。装饰器参数是 URI,静态地址与带参数的模板各写一个,代码如下。

from pathlib import Path

DOCS_DIR = Path("docs")

@mcp.resource("docs://catalog")
def catalog() -> str:
    """返回文档目录清单。"""
    return "\n".join(p.name for p in DOCS_DIR.glob("*.md"))

@mcp.resource("docs://{filename}")
def read_file(filename: str) -> str:
    """读取指定 Markdown 文件的内容。"""
    target = (DOCS_DIR / filename).resolve()
    if DOCS_DIR.resolve() not in target.parents:
        return "路径越界,已拒绝"
    return target.read_text(encoding="utf-8")

解读:静态资源 docs://catalog 没有参数,客户端直接 resources/read;模板资源 docs://{filename} 的花括号参数映射到同名函数参数,客户端读 docs://intro.md 时 SDK 先解析出 filename 再调函数。第二个函数顺手演示了碰文件系统的 server 必做的越界校验——资源一旦挂进客户端,读文件的口子就是外部够得着的口子。

3.3、prompt 提示模板

prompt 由用户在客户端菜单里主动挑起,常见形态是斜杠命令。注册方式与前两者同构,代码如下。

# Annotated 与 Field 的导入同 3.1
@mcp.prompt(title="周报生成")
def weekly_report(
    name: Annotated[str, Field(description="汇报人姓名")],
    work: Annotated[str, Field(description="本周事项,分号分隔")],
) -> str:
    """按固定模板生成周报初稿。"""
    items = "\n".join(f"- {x.strip()}" for x in work.split(";"))
    return f"请以 {name} 的口吻把以下事项整理成周报:\n{items}"

解读:title= 是给人看的按钮文案;返回的字符串经 prompts/get 渲染后,作为一条 user 消息进入对话,相当于替用户预写了一大段提示词。它与 tool 最大的差别在错误语义:prompt 参数没有 JSON Schema,就是一张"名字加必填与否"的扁平表;缺必填参数时整个请求直接以 JSON-RPC 错误失败(-32603),不给函数执行机会——因为填表单的是用户,模型不在环里,不需要模型可读的错误通道。

4、类型即文档

回看前面的 add 与 calc:从头到尾没写一行 JSON Schema,也没碰过 JSON-RPC。SDK 从函数上读走三样东西——函数名成工具名,docstring 成描述,类型提示成参数 schema。calc 注册后,tools/list 返回的条目节选如下。

{
  "name": "calc",
  "description": "计算一个算术表达式的值。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "expression": {
        "type": "string",
        "description": "算术表达式,如 (1+2)*3"
      }
    },
    "required": ["expression"]
  }
}

解读:int 映射 integer,参数带默认值就从 required 里消失,Field 的 description 原样带入。这张 schema 同时驱动两端:Inspector 拿它画表单,模型拿它决定怎么传参。函数签名就是接口文档——签名一改,schema 自动跟着改,不存在文档过期的经典难题。SDK 把 wire 类型拆成纯 pydantic 包 mcp-types,也是为了让这条"类型到 schema"的推导链路有干净的地基。

5、低层 Server API

MCPServer 并不是 SDK 的全部。v2 是双轨 API:高层 MCPServer 负责"把 Python 函数翻译成协议条目";低层 Server 直接面向 JSON-RPC 方法本身——哪个 handler 响应 tools/list、tools/call 怎么分发、返回的报文长什么样,全部自己写,schema 也要手工构造,wire 类型从 mcp-types 包里拿。两条轨道的对比如下。

维度 高层 MCPServer 低层 Server
注册方式 装饰器注册函数 构造器传 handler
参数校验 类型提示推导 schema 手写 JSON Schema
命令行调试 mcp dev 与 mcp run 可用 需自写启动代码
典型场景 绝大多数 server 逐字段控制协议报文

低层的主场是协议层细节。第 2 篇提过 GA 版给 list 方法新增了 ttlMs 与 cacheScope——想让 tools/list 的响应精确携带这两个字段,就得自己组装返回值;分页游标、中间件、运行期动态增删工具目录,也都是低层的活。官方文档把低层 Server 归在 Advanced 章节,并明确说 mcp dev 与 mcp run 只认 MCPServer,低层 server 要自己写启动代码(详见低层 Server 文档)。结论很干脆:默认从 MCPServer 起步,等它真的挡住你,再下探。

6、运行与调试

mcp.run() 是唯一的启动决策点,核心参数是传输方式。默认 stdio:宿主把你的文件当子进程拉起,协议字节流走 stdin 与 stdout。这带来一个新手必踩的坑——stdout 就是协议线:服务期间往 stdout 打印的内容都可能污染报文流,SDK 会把其中已 flush 的输出改道 stderr 兜底,但启动阶段缓冲的输出仍会落在线上,所以日志一律走 logging 模块。想变成端口服务,只改一行。

if __name__ == "__main__":
    mcp.run(transport="streamable-http", port=3001)

这一行会让 SDK 用 Starlette 加 uvicorn 起一个 HTTP 服务,客户端连 http://127.0.0.1:3001/mcp。两个易错点:其一,host、port、streamable_http_path 这些传输参数全在 run() 上,写进 MCPServer(...) 构造器会直接 TypeError——构造器描述"server 是什么",run() 描述"server 怎么被服务",两者别混;其二,无状态部署加 stateless_http=True,每个请求独立处理、不追踪会话,正好接上第 2 篇讲的无状态内核。调试再预告一次:uv run mcp dev server.py 起 Inspector 可视化调三原语,细节第 5 篇展开(运行文档)。

7、实战:内部知识库 Server

最后串一个完整案例:给团队内部知识库做查询 server——工具负责检索,资源负责列目录。假设 docs/ 下放着一批 Markdown。检索走标准向量链路:文档与查询各自向量化,算余弦相似度取前 k 个。示例用词频向量把链路跑通,零外部依赖;生产环境把向量化一步换成 embedding 模型(本地 sentence-transformers 或内部 embedding 服务),检索骨架不用动。先看核心,代码如下。

import math
import re
from collections import Counter
from pathlib import Path

DOCS = {p.stem: p.read_text(encoding="utf-8")
        for p in Path("docs").glob("*.md")}

def tokenize(text: str) -> list[str]:
    return re.findall(r"[a-zA-Z0-9]+|[一-鿿]", text.lower())

VECTORS = {name: Counter(tokenize(body)) for name, body in DOCS.items()}

def cosine(a: Counter, b: Counter) -> float:
    dot = sum(v * b.get(k, 0) for k, v in a.items())
    norm = math.sqrt(sum(v * v for v in a.values())
                     * sum(v * v for v in b.values()))
    return dot / norm if norm else 0.0

解读:启动时全量读入文档并建好词频向量;tokenize 对英文按单词、中文按单字切分——词频没有真语义,这里只求链路完整。接着把能力挂上原语,代码如下。

from typing import Annotated
from pydantic import Field
from mcp.server import MCPServer

mcp = MCPServer("内部知识库")

@mcp.tool()
def search(
    query: Annotated[str, Field(description="检索问题或关键词")],
    top_k: Annotated[int, Field(description="返回条数")] = 3,
) -> str:
    """按相似度检索内部文档,返回文件名与内容开头。"""
    q = Counter(tokenize(query))
    ranked = sorted(DOCS, key=lambda n: -cosine(q, VECTORS[n]))
    return "\n".join(f"{n}.md:{DOCS[n][:50]}……" for n in ranked[:top_k])

@mcp.resource("kb://catalog")
def catalog() -> str:
    """返回知识库文档清单与字数。"""
    return "\n".join(f"{n}.md({len(body)} 字)" for n, body in DOCS.items())

if __name__ == "__main__":
    mcp.run()

解读:search 是留给模型的口子——模型判断用户在问内部知识时自己发起调用,top_k 带默认值所以是可选参数;kb://catalog 是留给客户端应用的口子——用户想看库里有什么时由应用读取,一次都不占用模型的工具调用。同一个知识库,两种暴露方式,正好对上第 1 篇那张控制权对照表。uv run mcp dev server.py 起服务实测:在 Tools 里问"部署怎么做",在 Resources 里读 catalog,各归其位。

8、总结

本文从协议转入代码,走完官方 Python SDK v2 的入门闭环:v2 要求 Python 3.11+,高层类改名 MCPServer、wire 类型拆成 mcp-types 包,"FastMCP"之名让位给第三方框架;不到十行代码起一个合规 server,装饰器加类型提示就是全部接口定义;三原语写法同构、错误语义各异;低层 Server 留给协议层精细控制;run() 定传输,stdio 模式下 stdout 即协议线。留三道练习:

  • 把实战 server 的词频向量换成 sentence-transformers 的真 embedding,对比两者检索质量
  • 给知识库 server 加一个 prompt:用户触发"总结某篇文档",模板带文件名参数
  • 用 mcp run server.py --transport streamable-http 把服务架上端口,再用 Inspector 连一次

对于准备交付第一个 server 的读者,建议路径是:MCPServer 起步,mcp dev 全程伴随,卡在协议细节再下探低层 API。本系列的调试与接入真实宿主,第 5 篇展开。

相关推荐

​Jev 详解:不做生成的判断模型
精选AI

​Jev 详解:不做生成的判断模型

Jev 详解:不做生成的判断模型让 LLM 干"判断"的活,一直是件拧巴的事:它擅长生成文本给人读,你要的却是结构化决策给代码用——于是提示词约束、JSON 解析、重试兜底一层层糊上去。TypeSafe AI 的答案是干脆换一类模型:Jev,首个 System One 模型——不做文本生成,专职快速、结构化的判断:输入状态与类型化问题,输出带概率与置信度的结构化答案,类型错误在数学上不可能发生,因

762
网站被注入恶意脚本排查实录:AI 辅助安全分析实战
置顶 精选AI

网站被注入恶意脚本排查实录:AI 辅助安全分析实战

网站被注入恶意脚本排查实录:AI 辅助安全分析实战某天收到华为云监管反馈,称个人博客网站存在色情违规界面。作为技术博主,这简直是晴天霹雳——网站一直正常运行,怎么会突然出现这类问题?经过排查发现,网站被注入了恶意跳转脚本。本文记录完整的排查过程,重点分享如何借助 AI 快速定位问题并修复,希望能给遇到类似情况的开发者提供参考。1、问题发现与初步排查收到监管反馈后,第一时间打开网站检查。首页看起来完

451
博客七周年:AI 一天完成整体重构
全站置顶 精选AI

博客七周年:AI 一天完成整体重构

博客从 2019 年国庆用 Xiuno BBS 搭建,到 2026 年国庆整整七年。868 篇文章、53 条评论、6060 个代码块,这次与 AI Agent 结对,一天完成从 PHP 论坛到 Next.js 的整体重构与无损迁移。

430