运行 mcp-for-beginners 低层 MCP 服务端 Python 示例:环境搭建、源码解析与端到端调用验证

原创2026-10-10 20:36:471,401 阅读
文章标签:教程示例工程MCP 服务MCP Clients人工智能

运行 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):

  1. 建立通道:stdio_client(server_params) 启动 python server.py 子进程,并返回一对读写流;
  2. 初始化会话:ClientSession(read, write) 包装通道,await session.initialize() 完成协议握手;
  3. 协议交互: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 能力。

登录后查看全文
mcp-for-beginners