运行 mcp-for-beginners 低层 MCP 服务端 Python 示例:环境搭建、源码解析与端到端调用验证
运行 mcp-for-beginners 低层 MCP 服务端 Python 示例:环境搭建、源码解析与端到端调用验证
本篇技术指南围绕 mcp-for-beginners 课程第三章「10-advanced」章节附带的 Python 示例展开,带你从零完成虚拟环境搭建、MCP 官方 Python SDK 安装、客户端脚本运行,并基于示例源码(client.py、server.py)逐步剖析低层(low-level)MCP 服务端的工具注册、输入校验与调用链路。读完本文,你将掌握一套可复制、可扩展的低层服务端开发与本地联调流程,并理解工具列表(tools/list)与工具调用(tools/call)两大协议能力在 Python 端的真实实现。
示例概览与代码结构
本示例位于仓库的 03-GettingStarted/10-advanced/code/python 目录下,英文说明见 code/python/README.md,本文对应的翻译版本见 translations/de/03-GettingStarted/10-advanced/code/python/README.md。整个示例由四个文件构成:
python/
--| client.py # MCP 客户端:通过 stdio 连接服务端,列出并调用工具
--| server.py # 低层服务端:注册 list_tools / call_tool 两个请求处理器
--| tools/
----| __init__.py # 工具注册表:把各个工具汇总成字典
----| add.py # add 工具定义:名称、描述、输入模型与执行函数
----| schema.py # Pydantic 输入模型:AddInputModel
其中客户端 client.py 与服务端 server.py 位于同一目录,客户端通过标准输入输出(stdio)通道直接拉起并连接 server.py,因此运行顺序为:先搭好环境、装好依赖,再执行 python client.py,由客户端负责启动子进程服务端并完成握手。
第一步:准备 Python 虚拟环境
原文档要求先建立独立的虚拟环境,避免与系统级 Python 包互相污染:
python -m venv venv
source ./venv/bin/activate
python -m venv venv 会在当前目录生成名为 venv 的虚拟环境目录;第二条命令激活它,此后 python 与 pip 都指向虚拟环境内的解释器。在 Windows 上激活命令略有差异,可使用 venv\Scripts\activate 代替 source ./venv/bin/activate。
第二步:安装 MCP 官方 Python SDK
激活环境后安装依赖:
pip install "mcp[cli]"
该命令安装 MCP 官方 Python SDK(pip 包名为 mcp),[cli] 是 extras 标记,用于一并安装命令行辅助工具依赖。安装完成后,Python 代码即可导入 mcp 包中的 ClientSession、Server、types 等模块——这些正是下面源码解析中会用到的核心组件。
第三步:运行客户端并验证输出
依赖装好后,在示例目录下直接执行:
python client.py
原文档给出了预期输出:
Available tools: ['add']
Result of add tool: meta=None content=[TextContent(type='text', text='8.0', annotations=None, meta=None)] structuredContent=None isError=False
这段输出包含两个关键信号,可据此判断示例是否跑通:
Available tools: ['add']:客户端成功初始化会话并调用tools/list,服务端回列出了注册的工具add;Result of add tool: ...:客户端以{"a": 5, "b": 3}调用add工具,服务端返回TextContent(type='text', text='8.0'),isError=False表示调用成功,structuredContent=None表示未附带结构化内容。
由于 add 的输入模型 a、b 均为 float 类型(见 tools/schema.py),5 与 3 相加的结果以 8.0 而非 8 的形式返回。需要说明的是,输出中的字段顺序与 SDK 版本有关,不同版本下字段排列可能略有差异,但核心信息(工具名列表、text='8.0'、isError=False)应当一致。
客户端源码解析:stdio 通道与会话生命周期
运行 python client.py 时实际发生了什么?逐段看 client.py:
# Create server parameters for stdio connection
server_params = StdioServerParameters(
command="python", # Using uv to run the server
args=["server.py"] # We're already in snippets dir
)
客户端先用 StdioServerParameters 描述要启动的子进程:命令为 python,参数为 server.py(源码注释同时提示,也可以改用 uv 这类更快的运行时来启动服务端)。随后定义异步入口 run():
async def run():
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as session:
# Initialize the connection
await session.initialize()
tools = await session.list_tools()
print(f"Available tools: {[t.name for t in tools.tools]}")
result = await session.call_tool("add", { "a": 5, "b": 3 })
print(f"Result of add tool: {result}")
这里展示了 MCP 客户端的三步标准流程(client.py):
- 建立通道:
stdio_client(server_params)启动python server.py子进程,并返回一对读写流; - 初始化会话:
ClientSession(read, write)包装通道,await session.initialize()完成协议握手; - 协议交互:
session.list_tools()发出tools/list请求,session.call_tool("add", {...})发出tools/call请求。
最后的 main() 通过 asyncio.run(run()) 驱动整个异步流程。也就是说,示例采用 stdio 传输,客户端与服务端是同一台机器上的父子进程,通信内容通过标准输入输出传递——这正是 MCP 本地通信的推荐方式,相关内容可进一步参考 05-stdio-server 章节。
服务端源码解析:低层 Server 的两个处理器
服务端 server.py 是本示例的精华所在。它没有使用 FastMCP 这样逐个注册工具的高层 API,而是直接使用低层 Server:
from mcp.server.lowlevel import NotificationOptions, Server
from mcp.server.models import InitializationOptions
from tools import tools
server = Server("example-server")
低层服务端的特点(与高层 API 的对比详见 10-advanced 章节教程):不再为每个工具写一段注册代码,而是每种能力只维护两个请求处理器——一个负责「列出所有工具」,一个负责「处理任意工具调用」。本示例中两个处理器分别如下。
列出工具的处理器
@server.list_tools()
async def handle_list_tools() -> list[types.Tool]:
"""List available tools."""
vm_tools = []
for tool in tools.values():
print(f"Registered tool: {tool['name']}")
vm_tools.append(
types.Tool(
name=tool["name"],
description=tool["description"],
inputSchema=convert_to_json(tool["input_schema"]),
)
)
return vm_tools
(server.py)该函数遍历 tools 注册表中的每个工具,将其 name、description 与 inputSchema 组装成符合协议返回类型的 types.Tool。这里出现了一个关键转换函数 convert_to_json:
def convert_to_json(model_cls: type) -> dict:
schema = model_cls.schema()
properties = {}
required = schema.get("required", [])
for prop, details in schema.get("properties", {}).items():
properties[prop] = {"type": details.get("type", "string")}
return {
"type": "object",
"properties": properties,
"required": required
}
(server.py)它的作用是把 Pydantic 模型描述转换成协议要求的 JSON Schema 形式(type/properties/required 结构),这样客户端与 LLM 才能理解 add 工具需要哪些参数。
处理工具调用的处理器
@server.call_tool()
async def handle_call_tool(
name: str, arguments: dict[str, str] | None
) -> list[types.TextContent]:
# tools is a dictionary with tool names as keys
if name not in tools:
raise ValueError(f"Unknown tool: {name}")
tool = tools[name]
result = "default"
try:
result = await tool"handler"
except Exception as e:
raise ValueError(f"Error calling tool {name}: {str(e)}")
return [
types.TextContent(type="text", text=str(result))
]
(server.py)调用链一目了然:按 name 查字典找到工具定义 → 执行其 handler → 把结果包装成 TextContent 返回。未注册的工具名会直接抛出 ValueError("Unknown tool: ..."),参数校验失败的异常也会被捕获并转为带工具名的错误信息。
服务端启动与初始化选项
async def run():
"""Run the server with lifespan management."""
async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
await server.run(
read_stream,
write_stream,
InitializationOptions(
server_name="example-server",
server_version="0.1.0",
capabilities=server.get_capabilities(
notification_options=NotificationOptions(),
experimental_capabilities={},
),
),
)
(server.py)stdio_server() 上下文管理器提供读写流,server.run(...) 挂载 InitializationOptions(服务名 example-server、版本 0.1.0)后开始循环处理协议消息,直到客户端断开。运行该文件时会先打印 Starting server...,随后进入事件循环。
工具注册与 Pydantic 输入校验
低层架构把「工具」从服务端文件中剥离出来,每个工具独占一个目录,这正是可扩展性的来源。本示例的 add 工具拆成了三个文件:
1. 输入模型(tools/schema.py)
from pydantic import BaseModel
class AddInputModel(BaseModel):
a: float
b: float
用 Pydantic 声明工具入参:两个必填浮点字段 a、b。
2. 工具定义(tools/add.py)
from .schema import AddInputModel
async def add_handler(args) -> float:
try:
# Validate input using Pydantic model
input_model = AddInputModel(**args)
except Exception as e:
raise ValueError(f"Invalid input: {str(e)}")
"""Handler function for the add tool."""
return float(input_model.a) + float(input_model.b)
add = {
"name": "add",
"description": "Adds two numbers",
"input_schema": AddInputModel,
"handler": add_handler
}
注意校验发生的时机:add_handler 内部先用 AddInputModel(**args) 尝试把客户端传来的参数字典解析成模型——参数缺失或类型错误会抛异常并转为 ValueError;解析成功后才执行 float(input_model.a) + float(input_model.b)。也就是说,参数校验既可以在服务端统一处理器里做,也可以像本例这样下沉到具体工具的 handler 中完成(tools/add.py),两种位置均可,取决于你的架构取舍。
3. 工具注册表(tools/init.py)
from .add import add
tools = {
add["name"] : add
}
把 add 字典以工具名为键放进 tools 字典。日后新增工具时,只需在 tools/ 下新建目录与文件、再在此处追加一行——服务端 server.py 无需任何改动,因为两个处理器天然遍历整张注册表。这正是 10-advanced 章节教程 强调的分层架构:server.py 只负责接线,每个功能(工具、资源、提示词)各归其位。
为什么采用低层服务器:从示例看架构收益
本示例是 10-advanced 章节 的配套代码,其价值在于演示低层服务端相对高层 API 的架构优势。章节教程对比了两类写法:
- 高层(常规)服务端:如 Python 的
FastMCP("Demo")+@mcp.tool()装饰器,逐个显式注册每个工具、资源、提示词,代码简单但全部挤在服务端文件中; - 低层服务端:每种能力只维护「列出」与「调用」两个处理器,工具的
name、description、inputSchema与执行逻辑可以整体外移到tools/目录,服务端文件始终保持精简。
章节教程给出了可直接落地的目录组织建议(10-advanced/README.md):
app
--| tools
----| add
----| substract
--| resources
----| products
----| schemas
--| prompts
----| product-description
本示例正是这种思想的 Python 实现。章节还指出,低层服务端才能访问某些高级能力(章节提到后续会涉及的 Elicitation 与在 MCP 2026-07-28 规范中已弃用的 legacy Sampling 特性),这也是选择低层架构的另一个现实理由。
跨语言对照:TypeScript 版本速览
同一示例在仓库中还有 TypeScript 实现(code/typescript),便于对照理解。其运行流程为:
npm install # 安装依赖
npm run build # 编译 TS -> build/
npm start # 启动服务端
TypeScript 端用 Zod(而非 Pydantic)定义 MathInputSchema = z.object({ a: z.number(), b: z.number() }),并通过 zod-to-json-schema 生成协议所需的 inputSchema,同时提供 setRequestHandler(ListToolsRequestSchema, ...) 与 setRequestHandler(CallToolRequestSchema, ...) 两个请求处理器——与 Python 端 @server.list_tools()、@server.call_tool() 一一对应。TypeScript 示例还额外给出了用 npx @modelcontextprotocol/inspector 以 CLI 模式测试 tools/list、tools/call、未知工具名与非法参数的完整命令与预期输出,可作为 Python 端验证时的参考。
常见问题与排查
- 命令找不到(command not found):确认已先执行虚拟环境激活命令;Windows 用户改用
venv\Scripts\activate。 - 依赖未安装:确认安装命令是
pip install "mcp[cli]"(注意引号,避免 shell 把[cli]当作通配符)。 - 输出与文档不一致:预期输出来自仓库当前版本的 SDK 行为;若 SDK 版本不同,字段顺序或展示形式可能变化,核心判断依据是
Available tools: ['add']与text='8.0'、isError=False。 - 调用未注册工具:
handle_call_tool会抛出Unknown tool: ...,可在服务端新增工具并在 tools/init.py 注册后重试。
总结与下一步
通过本示例,你已经掌握了 MCP Python 低层服务端的完整闭环:从 pip install "mcp<a href="https://link.gitcode.com/i/0a5c0f8afaa59b6fdcc6abdc13286cb7" target="_blank">cli]" 的环境准备,到 python client.py 触发 tools/list 与 tools/call 的端到端调用,再到服务端「两个处理器 + 工具注册表 + Pydantic 校验」的可扩展架构。课程建议的后续练习是:自行向 tools/ 目录追加更多工具(以及资源、提示词),并观察服务端文件是否无需改动——这正是低层架构的扩展性验证。接下来可进入下一章节 [11-simple-auth 简单鉴权,为你的服务端加上 Basic Auth、JWT 与 RBAC 能力。