Zero MCP Tesk Kit Engine

mcptest——ZeroMCP测试套件引擎

MCP（模型上下文协议）服务器通用测试工具包。验证任何符合MCP的服务器，无论其实现语言、运行时或框架如何。

概述

mcptest 是一个独立的Rust二进制文件，接受JSON测试定义并生成结构化的JSON结果。它是ZeroMCP背后的核心引擎。TestKit——特定于语言的DSL（C#、Node.js、Python、Go）将所有正确性决策委托给此引擎。

特性

• 协议验证 --握手、会话生命周期、JSON-RPC帧结构、错误代码
• 模式验证 --工具输入和输出的JSON模式合规性
• 决定论验证 --使用完整JSONPath进行多运行比较 ignore_paths 支持
• 错误路径验证 --未知的工具、格式错误的参数、预期的错误代码
• 工具元数据验证 --检查所有工具是否具有名称、描述和有效的inputSchema
• 自动错误路径测试 --自动测试未知的刀具拒绝和格式错误的参数处理
• 测试生成 --脚手架存根或来自实时服务器的已知良好基线
• 录制和回放 --捕获用于脱机CI和调试的会话
• 基线差异 --检测版本之间的模式漂移

安装

来源

cargo install --path .

需求

• 锈1.85+（2024年版）
• 在带有MSVC的Windows上： dlltool.exe 来自MinGW的必须在PATH上

用法

运行测试

mcptest run --file tests.json --server http://localhost:8000/mcp

使用高级验证运行

mcptest run --file tests.json --server http://localhost:8000/mcp \
  --validate-protocol --validate-metadata --auto-error-tests

录制会话

mcptest run --file tests.json --server http://localhost:8000/mcp \
  --record session.json

重播录制的会话（脱机）

mcptest run --file tests.json --replay session.json

生成脚手架

mcptest generate --scaffold --server http://localhost:8000/mcp --out tests.json

生成已知的良好基线

mcptest generate --known-good --server http://localhost:8000/mcp \
  --params search:'{"query":"hello"}' --out baseline.json

检测架构漂移

mcptest diff --baseline baseline.json --server http://localhost:8000/mcp

测试定义格式

{
  "$schema": "https://zeromcp.dev/schemas/testkit.v1.json",
  "version": "1",
  "server": "http://localhost:8000/mcp",
  "tests": [
    {
      "tool": "search",
      "params": { "query": "hello" },
      "expect": {
        "schema_valid": true,
        "deterministic": true,
        "ignore_paths": ["$.result.timestamp"]
      }
    }
  ],
  "config": {
    "timeout_ms": 30000,
    "determinism_runs": 3,
    "validate_protocol": true,
    "validate_metadata": true,
    "auto_error_tests": true
  }
}

结果格式

{
  "status": "passed",
  "results": [
    {
      "tool": "search",
      "passed": true,
      "schema_valid": true,
      "deterministic": true,
      "errors": [],
      "elapsed_ms": 42
    }
  ],
  "elapsed_ms": 100
}

CI/CD

该存储库包括GitHub Actions工作流 .github/workflows/:

发布工件

当你发布GitHub版本时（例如标签 v0.2.0)，管道产生：

其他管道消耗

选项1-GitHub发布资产 （建议用于版本化版本）：

- name: Download mcptest
  run: |
    gh release download v0.2.0 \
      --repo ZeroMcp/ZeroMcp.TeskKitEngine \
      --pattern "mcptest-*-x86_64-unknown-linux-gnu.tar.gz"
    tar xzf mcptest-*.tar.gz

选项2——工作流工件 （用于按运行ID使用最新版本）：

- uses: actions/download-artifact@v4
  with:
    name: mcptest-x86_64-unknown-linux-gnu
    repository: ZeroMcp/ZeroMcp.TeskKitEngine
    run-id: ${{ needs.detect.outputs.engine_run_id }}
    github-token: ${{ secrets.ORG_GITHUB_TOKEN }}

选项3——组合捆绑 （一个工件中的所有平台）：

- uses: actions/download-artifact@v4
  with:
    name: mcptest-all
    repository: ZeroMcp/ZeroMcp.TeskKitEngine
    run-id: ${{ needs.detect.outputs.engine_run_id }}
    github-token: ${{ secrets.ORG_GITHUB_TOKEN }}

跨仓库工件下载需要一个GitHub令牌 actions:read 引擎存储库上的范围。

CI退出代码

运输

验证器

建筑

CLI (clap)
  └── Engine
       ├── Test Definition Parser (JSON Schema validated)
       ├── Transport Layer (stdio, HTTP+SSE, recording middleware)
       ├── MCP Protocol Client (JSON-RPC 2.0)
       │    └── Session State Machine
       ├── Validators (schema, determinism, protocol, error path, metadata)
       ├── Test Generator (scaffold, known-good)
       ├── Recorder / Replay (session capture + offline testing)
       └── Diff Engine (baseline comparison)

许可证

麻省理工学院