MCP 测试三件套与宿主接入

QuibblerAgentQuibblerAgent 2026-11-20 约 20 分钟 10 次阅读

第 3 篇《MCP Python SDK v2 实战》用不到十行代码起了一个合规的 server,第 4 篇《MCP handler 内幕:Context 与 Resolve》又把 handler 从纯函数养成带进度、带共享状态、能向用户提问的运行时参与者。但代码写得再顺,离交付还差最后一公里:模型传来的参数工具接不接得住,宿主能不能把进程稳稳拉起,改了一行代码之后怎么确认协议面没被弄坏。本篇是《MCP 协议与实现》第 5 篇、Server 开发层收官篇,把这一公里拆成测试三件套与宿主接入两段走完,按"可测性 → 三件套总览 → mcp dev 与 Inspector → 进程内测试 → 宿主接入 → 分层策略 → 实战"组织,并给第 3 篇的知识库 server 补一套完整 pytest,口径均以 mcp 2.3.0 源码与官方文档站为准(本文写作时 2026 年 11 月)。


1、协议标准化带来可测性

先回答一个容易被忽略的问题:为什么 MCP server 的测试体验比大多数网络服务好?传统服务难测,难在业务逻辑与接入方式耦合——要验证一个 HTTP 接口,要么起全套依赖环境,要么照着某家客户端的私有格式手写 mock,测试代码比业务代码还长。MCP 把这层耦合拆掉了,带来三个红利。

其一,协议统一,客户端现成。你的 server 对外的全部世界就是一个讲标准协议的客户端,而这个客户端不用自己造:官方 SDK 直接提供了 Client 类,Inspector 提供了可视化界面,真实宿主提供了最终验收环境。其二,类型即文档——第 3 篇讲过,工具名、描述、参数 schema 全部从函数签名推导,断言 schema 就等于断言接口,不存在"实现与文档各说各话"。其三,传输便宜:stdio 模式下拉起子进程即是环境,进程内更是内存直连、毫秒级往返。

第 2 篇的无状态内核还送了一份隐形福利:旧协议测试前要先走 initialize 握手铺垫会话,新内核下第一个请求就是业务请求,测试用例天然短——没有会话建立、没有状态清理,一个用例只关心一次调用。

2、测试三件套总览

验证手段按"谁来操作、回答什么问题"摆开,三件套的定位对比如下。

工具 形态 回答的问题
mcp dev CLI 命令 我的 server 在真实客户端眼里长什么样
MCP Inspector 浏览器可视化客户端 手动过一遍三原语、看原始报文
进程内 Client pytest 内存直连 改动之后协议行为有没有回归

三者的关系是接力而非替代:mcp dev 是入口,它负责把 Inspector 拉起来;Inspector 是开发期的眼和手,适合探索与排错;Client 是自动化的回归网,适合固化成测试用例。Inspector 与 Client 消费的是同一套协议实现,"眼见的"与"断言的"不会各说各话——这是标准化给测试的底层保证。

3、mcp dev 与 Inspector

第 3 篇用过 uv run mcp dev server.py,本节按 2.3.0 源码把这条命令拆开(源码见 python-sdk 仓库的 mcp/cli/cli.py)。它依次做三件事:先 import 你的文件、按 mcp 名字找 server 对象——所以 if __name__ == "__main__" 守卫不能省,也支持 server.py:mymcp 后缀指定别的对象名;再把 server 的 dependencies 属性并入依赖清单;最后构造一条 uv 命令,交给 Inspector。完整链路如下。

flowchart LR A[mcp dev] --> B[import 找 server] B --> C[拼 uv 命令] C --> D[Inspector 网页端] C --> E[uv 子进程跑 server] D <-->|stdio 协议流| E

解读:uv 命令是 uv run --with mcp==2.3.0 mcp run server.py——钉住的正是你当前运行的 SDK 版本。源码注释解释了为什么必须钉:uv run --with mcp 在全新环境里解析依赖,不钉版本会拿到最新稳定版,未必与你本地装的一致,预发布版更是永远选不中。Inspector 本体是 Node.js 应用,命令最终执行 npx @modelcontextprotocol/inspector,由它拉起 uv 子进程并在浏览器里给出操作界面——PATH 里没有 npx 会直接退出(Windows 上源码会依次找 npx.cmd)。额外依赖用 --with 包名 带上,本地开发装可编辑包用 --with-editable 目录。

Inspector 的操作流:Connect 之后 Tools、Resources、Prompts 三页对应三原语,工具页的输入表单由你的类型提示生成,填完调用即得结果;底部的报文历史能看到完整的 JSON-RPC 请求与响应。第 1、2 篇讲的三原语分工、_meta 元数据、Mcp-Method 头,都能在这里对着真实报文看一遍——它是系列理论篇的落地观察点,详见 Inspector 仓库。

4、进程内 Client 直连

Inspector 好用,但每次都要人手点,回归必须自动化。v1 时代要手工组装内存传输对(create_connected_server_and_client_session),v2 把这堆样板收口成一个 Client 类:把 server 对象直接传给它,协议调用在进程内完成,不起子进程、不占端口,定位类似 FastAPI 的 TestClient。Client 的构造目标与连接方式如下。

构造目标 连接方式
URL 字符串 Streamable HTTP 连远端
StdioServerParameters 拉起子进程走 stdio
Transport 实例 直接复用传入传输
MCPServer 实例 进程内内存直连

也就是说同一个 Client 类覆盖了"连远程、连子进程、连自己"三种形态,写测试用最后一种。给第 3 篇的加法工具写第一个测试,代码如下。

import pytest
from mcp import Client

from server import mcp

@pytest.fixture
def anyio_backend():
    return "asyncio"

@pytest.fixture
async def client():
    async with Client(mcp, raise_exceptions=True) as c:
        yield c

@pytest.mark.anyio
async def test_call_add(client: Client):
    result = await client.call_tool("add", {"a": 1, "b": 2})
    assert not result.is_error
    assert result.content[0].text == "3"

逐行解读(写法与官方测试文档一致):Client 从 mcp 顶层导入,mcp.client 路径也可;Client(mcp) 传 server 对象即内存直连;async with 管理连接生命周期,fixture 里 yield 出去供各用例复用;anyio_backend fixture 声明异步后端,@pytest.mark.anyio 标记异步用例,用 trio 的话把返回值换成 "trio" 即可;call_tool(名字, 参数字典) 返回 CallToolResult,content 是内容块列表,is_error 标记成败。常用的还有 list_tools() 列工具与 read_resource(uri) 读资源,第 7 节实战都会用到。

raise_exceptions=True 值得单独讲:默认情况下工具体抛出的异常会被消毒成 "Internal server error" 结果,真实错误只在服务端日志里;开了它,异常以真实面目抛进测试——失败的用例直接指向病根。调用链与协议时代也有关联:Client 会自动识别新旧协议路径,要钉旧协议语义用 mode="legacy";call_tool 还收 progress_callback 与 input_responses 参数,正好配合第 4 篇的进度上报与 MRTR 多轮往返做客户端侧验证。

注意:raise_exceptions=True 只给测试用。生产客户端不要开——把异常细节原样递给对端,等于把内部实现泄漏给外部。

5、宿主接入两种配置

自动化测试过后是真实宿主。宿主的概念回第 1 篇:承载大模型、内含 Client 的应用。接入的本质只有一句话——告诉宿主用什么命令拉起你的子进程。两大官方宿主的接入方式对比如下。

宿主 配置载体 写入方式
Claude Desktop claude_desktop_config.json mcp install 自动写或手写
Claude Code CLI 注册表 claude mcp add 命令

5.1、Claude Desktop 配置

配置文件在 macOS 是 ~/Library/Application Support/Claude/claude_desktop_config.json,Windows 是 %APPDATA%\Claude\claude_desktop_config.json。SDK 提供自动写入:uv run mcp install server.py,它生成的条目长这样(以知识库 server 为例,版本号取当前 SDK)。

{
  "mcpServers": {
    "内部知识库": {
      "command": "/usr/local/bin/uv",
      "args": [
        "run",
        "--frozen",
        "--with",
        "mcp[cli]==2.3.0",
        "mcp",
        "run",
        "/srv/kb/server.py"
      ]
    }
  }
}

解读:mcpServers 下每个键是一个 server,command 用 uv 的绝对路径,args 里的 --frozen 防止宿主拉起时改写锁文件,mcp[cli]==2.3.0 钉死版本,最后是 server 文件的绝对路径——手写配置照这个骨架来,路径一律绝对,宿主从自己的工作目录拉进程,相对路径是最常见的接入失败原因。需要环境变量时安装命令带 -v API_KEY=abc123,会记进条目的 env 字段;--name 可覆盖条目名。配置改完必须完全退出 Claude Desktop 再重开,只关窗口不够。

5.2、Claude Code 注册

Claude Code 不用碰配置文件,命令行注册(详见 Claude Code 的 MCP 文档),命令如下。

claude mcp add kb -- uv run --with "mcp[cli]" mcp run /srv/kb/server.py

解读:-- 之后是原样传给 server 的启动命令,Claude 自己的选项都在前面——比如 --env KEY=value 注环境变量、--transport stdio 显式声明传输。作用域分三档:默认 local 只在当前项目生效;--scope project 写进项目根的 .mcp.json、随版本库与团队共享;--scope user 跟随账号全局可用。验证两步:会话里跑 /mcp,看到 Connected 即通;命令行 claude mcp list、claude mcp get kb 可查健康状态,claude mcp remove kb 移除。完整的接入排查口径见宿主接入文档:动宿主配置前先把启动命令自己跑一遍——stdio server 静默等待就是正常;再查路径是否全绝对;最后回忆第 3 篇的告诫,stdout 是协议线,多余的 print 会污染报文流。

6、测试策略分层

三件套与宿主接入合起来,正好构成一张测试金字塔,分层如下。

层级 被测对象 跑法
单元 handler 纯函数与工具函数 pytest 直接调函数
集成 协议面行为 Client 进程内直连
端到端 宿主真实链路 Claude Code 与 Desktop 实测

分层的原则是成本与保真度同涨:单元层不起协议、毫秒级完成,占用例大头,专攻业务逻辑;集成层把"函数"换成"server",验证 schema 推导、错误语义、资源读取这些协议面行为——第 4 篇的 ToolError 三条归宿表,每条都值得一个集成用例;端到端最贵也最真,留给发布前与重大改动的冒烟。Inspector 的位置可以理解为"人肉集成层":探索时用它,探索出的结论固化成 Client 用例。三层齐备,uv run pytest 十秒跑完的回归网加上宿主里的一次人工确认,就是 server 的交付底气。

7、实战:知识库测试套件

最后给第 3 篇的知识库 server 补完整测试。它有两个部件:search 工具与 kb://catalog 资源,外加 tokenize 与 cosine 两个纯函数。先说测试语料:server 在 import 时全量读取 docs/ 目录,测试必须用固定语料——把三篇测试文档(部署指南、入门、常见问题)随测试代码提交,别指向生产目录。先写单元层,代码如下。

from collections import Counter

import pytest

from kb import cosine, mcp, tokenize

def test_tokenize_splits_words_and_cjk():
    assert tokenize("MCP 部署指南") == ["mcp", "部", "署", "指", "南"]

def test_cosine_identical_vector_is_one():
    v = Counter({"a": 1, "b": 2})
    assert cosine(v, v) == pytest.approx(1.0)

解读:tokenize 对英文按单词、中文按单字切分,两个断言把这个合同钉死——它决定检索行为,改切分规则必须先改测试;cosine 同向量相似度为 1,用 pytest.approx 容忍浮点误差。这两个用例完全不走协议,改一次跑一次的成本约等于零。接着写集成层,fixture 沿用第 4 节的写法。

@pytest.mark.anyio
async def test_list_tools_exposes_search(client: Client):
    result = await client.list_tools()
    assert {t.name for t in result.tools} == {"search"}

@pytest.mark.anyio
async def test_search_ranks_relevant_doc_first(client: Client):
    result = await client.call_tool("search", {"query": "部署步骤", "top_k": 1})
    assert not result.is_error
    assert "部署指南" in result.content[0].text

解读:第一个用例守住工具目录——工具名拼错、注册丢失都会在这里现形;第二个用例验证检索质量的最小合同:问"部署步骤",排第一的必须是部署指南。注意集成层断言的是协议返回的形状:.tools 列表、.content[0].text、.is_error,与真实客户端读到的一字不差。资源侧补一个用例。

@pytest.mark.anyio
async def test_catalog_lists_all_docs(client: Client):
    result = await client.read_resource("kb://catalog")
    text = result.contents[0].text
    for name in ("部署指南.md", "入门.md", "常见问题.md"):
        assert name in text

解读:read_resource 收 URI 字符串、返回内容块列表,固定语料有三篇,清单就该三篇俱全——资源注册、模板解析、内容拼装一条链全被这一条用例压住。uv run pytest 一跑,单元与集成两层全绿,这套件放进 CI 就是每次提交的协议回归网。语料涨大之后,更工程化的做法是把 DOCS 的构建从模块级挪进第 4 篇的 lifespan,届时测试语料的注入点也更干净。

8、总结

Server 开发层三篇到此收官:协议标准化给了 MCP server 天然的可测性——客户端现成、schema 可推导、无状态内核免会话铺垫;测试三件套各就其位,mcp dev 钉版本拉 Inspector 做交互调试,进程内 Client(mcp) 内存直连写成 pytest,宿主接入一条 JSON 配置加一条 claude mcp add;测试策略按单元、集成、端到端分层,成本递增、保真递增。留三道练习:

  • 给第 4 篇的 import_docs 写集成测试:Client 配上 elicitation 回调模拟用户选"跳过重复",断言库存与进度
  • 把知识库的语料加载挪进 lifespan,为测试加一个注入临时语料目录的 fixture,全绿后对比两种结构
  • 用 claude mcp add --scope project 把知识库挂进团队仓库,会话里 /mcp 连通后问一个知识库问题,对照 Inspector 报文看真实宿主的调用差异

对于准备交付第一个 server 的读者,建议把这套分层直接抄走:pytest 套件进 CI,宿主接入留作发布检查单。本系列 Server 开发层结束,下一篇进入传输与部署——stdio 之外的 Streamable HTTP 上线、无状态内核如何铺进生产环境。

相关推荐

​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