# MCP Server 契约测试器（stdio + WebSocket 双传输 · JSON Schema 2020-12 工具 schema 校验）

对 Model Context Protocol 服务器做端到端契约验证：JSON-RPC 2.0 握手与版本协商、capabilities 交换、tools/list 输入 schema 的 object 根类型与 2020-12 草案编译校验、resources 读写、prompts 获取、ping、未知方法 -32601 语义、sampling/createMessage 往返与 stdio 换行分帧纪律；默认内置参考服务器离线自测，亦可对你的 stdio 命令或 ws:// 端点实测。

> 标准页面: https://elysiatools.com/zh/tools/model-context-protocol-mcp-server-tool-schema-stdio-websocket-transport-contract-tester

- **分类:** AI Tools

- **关键词:** MCP, Model Context Protocol, 契约测试, JSON-RPC, stdio, WebSocket, 工具 schema, 能力协商, sampling, 合规报告

## 概述

协议依据（initialize 纪元，2024-11-05 … 2025-11-25）：initialize 请求携带 protocolVersion、client capabilities 与 clientInfo；服务器回 serverInfo + capabilities；客户端随后必须发送 notifications/initialized 通知。stdio 官方绑定 = 换行分隔的 JSON-RPC（禁内嵌换行、日志走 stderr、stdout 不得出现非 MCP 内容）；WebSocket 属规范 §自定义传输 —— 每 JSON-RPC 消息一个文本帧。规范要求每个工具 inputSchema 根节点为 type:object 的 JSON Schema，本工具用 Ajv 2020-12 对每个 schema 编译校验。sampling 是服务器→客户端请求：客户端声明 sampling capability 后，服务器可发 sampling/createMessage（messages[] + maxTokens），本测试器自动应答并验证其结构。2026-07-28 规范改为无状态核心（服务器不再主动发请求），本工具主测经典 initialize 纪元并在报告中注明。默认模式内置一台完全合规的参考服务器，经进程内 stdio 流对 + 真实 127.0.0.1 TCP WebSocket 回环双传输离线自测，结果确定可复现。

## 输入项

- **测试模式** (select)
- **服务器命令（stdio 模式）** (text): npx -y @modelcontextprotocol/server-everything
- **WebSocket 地址（ws:// 或 wss://）** (text): ws://127.0.0.1:3001/mcp
- **请求的协议版本** (select)
- **请求超时（毫秒）** (number): 5000
- **校验工具输入 schema（JSON Schema 2020-12）** (checkbox)

## 适用场景

- 本地开发自定义 MCP 服务器（stdio 命令行或 WebSocket 端点）并在接入宿主客户端前验证协议合规性与分帧纪律。
- 为 MCP 服务编写或重构工具 definitions 时，需要通过 Ajv 严格校验 inputSchema 根节点类型与 JSON Schema 2020-12 规范兼容性。
- 在持续集成流程中自动化验证不同协议修订版（如 2024-11-05、2025-06-18）的版本协商、ping 心跳与 -32601 错误码语义。

## 工作原理

- 选择测试模式（内置离线参考服务器、stdio 子进程命令或 WebSocket 端点地址），并配置目标协议版本与超时参数。
- 测试器发起连接并执行 JSON-RPC 2.0 initialize 握手请求，协商 protocolVersion，交换 capabilities 并按序发送 initialized 通知。
- 批量向服务端发送 tools/list、resources/read、prompts/get、ping 及未知方法探测指令，并使用 Ajv 编译验证每个工具的 inputSchema。
- 模拟处理服务端发起的 sampling/createMessage 双向抽样请求，检验传输分帧规范，最终输出包含得分矩阵的 HTML 合规报告。

## 使用案例

- 排查 Node.js 或 Python MCP 服务的 stdio 分帧异常，确保 stderr 与 stdout 输出隔离且无多余换行。
- 验证独立 WebSocket MCP 服务的端点连通性、心跳机制与 tools/resources/prompts 清单的契约正确性。
- 校验支持 sampling 能力的 MCP 服务端在触发 sampling/createMessage 时的数据结构与双向应答流程。

## 常见问题

### 工具支持哪些 MCP 传输协议？

支持 stdio（换行分隔的子进程标准输入输出）和 WebSocket（ws:// 或 wss:// 每消息单文本帧）两种传输模式。

### 为什么工具 schema 校验必须使用 JSON Schema 2020-12？

MCP 规范要求每个工具的 inputSchema 必须是合法的 JSON Schema 且根节点为 object 类型，测试器通过 Ajv 2020-12 确保其符合规范。

### 参考服务器自测模式有什么作用？

该模式无需依赖外部网络或命令，在内存与回环 TCP 中对内置合规参考服务器运行 34 项全量测试，用于快速确认基准行为与离线演示。

### 遇到不存在的方法时，测试器期望服务器返回什么？

根据 JSON-RPC 2.0 规范，服务器必须返回错误码为 -32601（Method not found）的标准错误响应。

### 服务端发生握手异常或超时时会怎样？

测试器不会异常崩溃，而是将连接或握手失败标记为测试未通过项，并在生成的合规报告中详细展示失败原因。

## 相关工具

- [CSV 转数据库迁移规划器](https://elysiatools.com/zh/tools/csv-to-database-migration-planner): 根据 CSV 数据推断关系型 schema，并为 PostgreSQL、MySQL、SQLite 或 SQL Server 生成建表和 ALTER 迁移计划
- [ECharts 主题 Token 抽取器](https://elysiatools.com/zh/tools/echarts-theme-token-extractor): 从 ECharts 主题 JSON 抽取设计 token——颜色、数字、字号与字符串——并直接导出到你的设计系统。粘贴一个主题对象（即通过 echarts.init(dom, themeName) 注册的那种），工具遍历每个叶子节点，为每个颜色（可选地将命名色/rgb 规范化为 hex）、间距数字、字号与字符串打标，然后输出干净的 CSS 变量、Tailwind theme.extend 配置、Style Dictionary tokens.json 或 SCSS 变量。在 ECharts 可视化主题与 Figma/CSS/Tailwind 设计 token 之间架桥，无需逐个手抄。
- [图片调色板转设计令牌](https://elysiatools.com/zh/tools/image-to-design-tokens): 从图片中用 k-means 聚类提取主色，导出为 CSS 变量 / SCSS 变量 / Tailwind 配置 / JSON 设计令牌，并自动为每个颜色生成命名色阶
- [JWK 生成与解析器](https://elysiatools.com/zh/tools/jwk-generator): 生成 RSA、EC（P-256/P-384/P-521/secp256k1）与 OKP（Ed25519/Ed448/X25519/X448）的 JSON Web Key，或解析已有 JWK 以查看参数、指纹与元信息
- [OCR PDF 转结构化 JSON 桥](https://elysiatools.com/zh/tools/ocr-pdf-to-structured-json-bridge): 按几何结构抽取 PDF 文本层（y 坐标分行、列间隙识表、字号识标题、冒号键值对），然后逐字段填入用户提供的 JSON Schema——标签按归一化键名匹配、值按声明类型归一化，并用 ajv 校验。
- [JSON键提取器](https://elysiatools.com/zh/tools/json-key-extractor): 从JSON对象中提取所有键，支持多种输出格式。非常适合分析JSON结构、生成文档和理解复杂的嵌套对象。
- [CSV 生成 JSON-LD](https://elysiatools.com/zh/tools/json-ld-generator-from-csv): 把 CSV 或 Excel 行数据转换为适用于 Article、Product、Event 的 Schema.org JSON-LD，方便 SEO 团队直接验证
- [LLM 工具调用 JSON Schema 构建器](https://elysiatools.com/zh/tools/llm-tool-calling-json-schema-builder): 一次定义 LLM 工具，同时生成 OpenAI、Anthropic、Gemini 三家经过校验的函数调用 payload。

## 示例

- [聊天记录 JSON 示例](https://elysiatools.com/zh/samples/chat-transcript-json): 多角色聊天记录的 JSON 示例
- [富媒体 JSON 示例](https://elysiatools.com/zh/samples/rich-media-json): 常见富文本编辑器（TipTap、Quill、Slate）的 JSON 示例
- [Terraform Plan JSON 样本](https://elysiatools.com/zh/samples/terraform-plan-json-samples): 用于依赖可视化和变更审查的 Terraform plan JSON 文件样本，贴近 terraform show -json 输出结构
- [JSON 示例](https://elysiatools.com/zh/samples/json): JSON（JavaScript 对象表示法）格式示例，从简单到复杂结构