AI导哈

MCP协议合规测试工具

用于验证MCP服务器是否符合官方规范的自动化测试工具，支持stdio和HTTP传输协议。

  • by cahlan
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 cahlan/mcp-test

使用说明

mcp试验

MCP服务器的协议合规性测试。

MCP生态系统有数百台服务器。直到现在，还没有人知道它们是否真的遵循了规范。

mcp-test 对任何MCP服务器运行24次自动合规性检查，验证初始化握手、版本协商、工具/资源/提示模式、错误处理和JSON-RPC正确性——所有这些都是针对 MCP官方规范支持两者 标准 和 流式HTTP 运输。

快速开始

# Test a stdio server
npx @cahlan/mcp-test run --server "node my-server.js"

# Test an HTTP server (Streamable HTTP transport)
npx @cahlan/mcp-test run --url http://localhost:3000

就是这样，一个命令。适用于任何MCP服务器——stdio或HTTP。

它看起来像什么

mcp-test v0.1.0 — Protocol Compliance Suite
Testing: node my-server.js
────────────────────────────────────────────────────────────

  Lifecycle
    ✓ lifecycle-001    Initialize handshake completes successfully
    ✓ lifecycle-002    Server accepts initialized notification
    ✓ lifecycle-003    Server response contains valid serverInfo
    ✓ lifecycle-004    Server responds to ping after initialization

  Versioning
    ✓ version-001      Server returns a valid protocol version
    ✓ version-002      Server capabilities object is well-formed

  Tools
    ✓ tools-001        tools/list returns valid tool array
    ✓ tools-002        Tool inputSchema is valid JSON Schema
    ✓ tools-003        tools/call returns valid content result
    ✓ tools-004        tools/call with unknown tool returns error
    ─ tools-005        tools/list supports cursor-based pagination  skipped

  ...

────────────────────────────────────────────────────────────
Results: 20 passed · 4 skipped
Compliance Score: 100% (critical: 100% · major: 100%)

默认情况下，只显示故障。使用 -v 查看上面的完整视图。

安装

# Run directly with npx (no install needed)
npx @cahlan/mcp-test run --server "node my-server.js"
npx @cahlan/mcp-test run --url http://localhost:3000

# Or install globally
npm install -g mcp-test
mcp-test run --server "python my_server.py"
mcp-test run --url http://localhost:3000

用法

运行合规性测试

# Basic usage — stdio transport
mcp-test run --server "node dist/server.js"

# HTTP transport (Streamable HTTP)
mcp-test run --url http://localhost:3000

# Show all tests (not just failures)
mcp-test run --server "node dist/server.js" --verbose

# TAP output for CI systems
mcp-test run --server "node dist/server.js" --output tap

# JSON output for programmatic use
mcp-test run --server "node dist/server.js" --output json

# Only test specific categories
mcp-test run --server "node dist/server.js" --filter tools
mcp-test run --server "node dist/server.js" --filter lifecycle

# Fail CI if any major or higher test fails
mcp-test run --server "node dist/server.js" --fail-on major

# Custom timeout per test
mcp-test run --server "node dist/server.js" --timeout 10000

列出可用测试

mcp-test list
mcp-test list --filter errors

它检查什么

7个类别的24个测试：

类别 测试 它验证了什么
生命周期 4 初始化握手， initialized 通知、服务器信息结构、ping
版本控制 2 协议版本格式（YYYY-MM-DD），能力对象结构
工具 5 tools/list 数组、inputSchema验证、， tools/call 内容、未知工具错误、分页
资源 5 resources/list 阵列， resources/read 内容、无效URI错误、分页、模板
提示 3 prompts/list 阵列， prompts/get 消息，分页
错误 3 未知方法错误、格式错误的请求处理、错误响应结构
JSON-RPC 2 响应ID匹配，并发请求处理

严重程度级别

  • 🔴 关键的 --必须符合要求。没有这些，服务器就坏了。
  • 🟡 主要的 --必须/应该的要求。对互操作性很重要。
  • 🟢 次要的 --应该/可能的要求。很高兴有。

智能跳过

测试不适用时会自动跳过：

  • 如果服务器未声明，则跳过工具测试 tools 能力
  • 如果服务器未声明，则跳过资源测试 resources 能力
  • 如果服务器没有返回，则跳过分页测试 nextCursor

运输

mcp-test 支持两种MCP传输机制：

stdio（默认）

将服务器作为子进程生成，并通过stdin/stdout进行通信：

npx @cahlan/mcp-test run --server "node my-server.js"
npx @cahlan/mcp-test run --server "python my_server.py"

流式HTTP

连接到正在运行的MCP HTTP服务器。先启动服务器，然后指向 mcp-test 在它：

npx @cahlan/mcp-test run --url http://localhost:3000

该工具将把JSON-RPC请求POST到 {url}/mcp 遵循 MCP流式HTTP传输规范.特点：

  • 自动SSE和纯JSON响应处理
  • 会话管理通过 mcp-session-id 头球
  • 关闭时通过HTTP DELETE终止会话

注： --server 和 --url 是相互排斥的——使用其中之一。

CI集成

GitHub操作

将此添加到您的MCP服务器仓库中：

# .github/workflows/mcp-compliance.yml
name: MCP Protocol Compliance

on:
  push:
    branches: [main]
  pull_request:

jobs:
  compliance:
    name: MCP Compliance Check
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run build
      - name: Run MCP compliance tests
        run: npx @cahlan/mcp-test@latest run --server "node dist/server.js" --output tap --fail-on critical

TAP输出

使用 --output tap 为了 龙头 大多数CI系统本机支持的格式：

TAP version 14
1..24
ok 1 - lifecycle-001 Initialize handshake completes successfully
ok 2 - lifecycle-002 Server accepts initialized notification
not ok 3 - tools-001 tools/list returns valid tool array
  ---
  message: tools/list result must contain a "tools" array
  severity: critical
  ...
# Tests: 24, Passed: 20, Failed: 1, Errors: 0, Skipped: 3
# Compliance Score: 95%

退出代码

代码 含义
0 所有测试均已通过（在配置时 --fail-on 严重程度）
1 一个或多个测试失败，达到或超过 --fail-on 阈值
2 致命错误（服务器无法启动、参数错误等）

合规性得分

合规性得分是以下百分比 关键+专业 通过的测试（跳过的测试不计算在内）。即使跳过次要测试，服务器也可以获得100%的分数。

Compliance Score: 92% (critical: 100% · major: 83%)

在您的服务器中发现错误？

检查 MCP规范 对于权威要求。每个测试都链接到相关的规范部分。

我们发现的常见问题：

  • tools/list返回对象而不是数组 — { tools: { myTool: ... } } 而不是 { tools: [...] }
  • 错误代码是字符串 --JSON-RPC需要整数错误代码(-32601，不 "NOT_FOUND")
  • 缺失 jsonrpc: "2.0" 在回应中 --每条JSON-RPC消息都必须包含此字段
  • Ping响应ID不匹配 --响应ID必须与请求ID完全匹配

徽章

显示您的服务器符合要求：

[![MCP Compliance](https://img.shields.io/badge/MCP-compliant-green)](https://github.com/cahlan/mcp-test)

贡献

发现了一个我们没有测试的规格要求？ 打开一个问题.

许可证

麻省理工学院

相关 MCP