mcp-tester

用于测试客户端对 */list_changed 通知及其他协议功能一致性的仪表化 MCP 服务器。

为什么需要它

PR mcaps-microsoft/msx-mcp#321 提出了通过 notifications/tools/list_changed 实现动态工具呈现。该 PR 被关闭，理由是“Copilot CLI 在会话开始时缓存了 tools/list 并忽略了 notifications/tools/list_changed”——但从未进行过任何仪表化实验来证实或反驳这一点。

本仓库提供了用于测试该声明（以及任何 MCP 客户端对 list_changed 的一致性）的工具，并提供真实证据。

它能做什么

1. 探测 MCP 服务器 (src/server.ts) —— 一个自仪表化的 MCP 服务器，记录其 stdio 管道上的每一条 JSON-RPC 消息。它公开了 alpha 状态的工具、资源和提示词，以及触发工具，这些工具可以将它们切换到 beta 状态并发送相应的 */list_changed 通知。

2. 自动化客户端驱动程序 (src/driver.ts) —— 一个基于 SDK 的 MCP Client，驱动服务器完成完整的变更周期。这是对照组：它证明了当两个端点都遵守规范时协议是有效的。任何偏离此行为的客户端都被证明是不一致的。

3. 日志分析器 (src/analyze.ts) —— 读取 JSONL 日志并生成一个 Markdown 证据表，回答特定问题：客户端是否收到了通知？它是否重新获取了数据？它能调用新项目吗？它还能调用已删除的项目吗？

4. 人工协议 (PROTOCOL.md) —— 针对 Copilot CLI 或任何其他 MCP 客户端运行相同测试的分步说明。

快速开始

git clone https://github.com/ericchansen/mcp-tester.git
cd mcp-tester
npm install
npm run build

运行自动化对照组（SDK 客户端）

npm run driver -- --domain all

这将启动探测服务器，运行工具、资源和提示词的完整变更协议，并报告结果。你应该看到所有三个领域都通过了完全一致性测试。

分析日志

npm run analyze -- path/to/log.jsonl --domain tools

测试你自己的 MCP 客户端

请参阅 PROTOCOL.md 获取针对此探测器测试 Copilot CLI 或任何其他 MCP 客户端的分步说明。

仓库布局

mcp-tester/
|-- README.md          # This file
|-- PROTOCOL.md        # Human-driven test procedure
|-- LICENSE            # MIT
|-- package.json
|-- tsconfig.json
|-- src/
|   |-- server.ts      # Probe MCP server (stdio)
|   |-- logger.ts      # JSONL stdio tap + log writer
|   |-- analyze.ts     # CLI: parses log -> markdown evidence table
|   +-- driver.ts      # CLI: spawns server, drives it via SDK Client
+-- results/
    +-- copilot-cli/
        +-- .gitkeep   # Committed experiment results go here

探测器的工作原理

初始状态 (Alpha)

外加五个永久工具：mcptester_mutate_tools、mcptester_mutate_resources、mcptester_mutate_prompts、mcptester_status。

变更后 (Beta)

当调用 mcptester_mutate_* 工具时：

1. Alpha 项目被移除（通过 SDK handle.remove()）

2. Beta 项目被注册

3. SDK 自动发送相应的 notifications/*/list_changed

4. debouncedNotificationMethods 将移除和注册合并为一个单一通知

日志记录

每一条 JSON-RPC 消息（入站和出站）都会被记录到 JSONL 文件中。记录器通过在 SDK 传输之前安装的 Transform 流来接入 process.stdin 和 process.stdout，因此它可以在不干扰协议的情况下看到每一个字节。

限制

• 仅限 stdio 传输 —— 暂不支持 HTTP/SSE 测试

• 仅限三个 list_changed 流程 —— 未来计划测试采样、启发、根目录、进度、补全等功能

• 单服务器测试 —— 一次测试一个 MCP 服务器连接

许可证

MIT