MCP Server Tester

MCP 服务测试器

⚠️ 正在开发中：此项目仍在积极开发中，尚未经过充分测试。功能可能不完整、存在错误或发生重大变化。请仅在非生产环境中使用，风险自负。

一款功能强大、由配置驱动的 Model Context Protocol（MCP）服务测试工具。本项目提供全面的解决方案，用于验证 MCP 服务、评估其性能并确保其可靠性，这些服务可与 Claude 等 AI 模型集成。

当前状态

此工具正朝着 Alpha 版本迈进，目前提供：

• ✅ 基本配置框架
• ✅ MCP 服务连接和 CLI 支持
• ✅ 使用 Claude AI 生成测试
• ✅ 为测试生成自然语言查询
• ✅ 使用多种规则全面验证响应
• ✅ 以控制台、JSON、HTML 和 Markdown 格式生成报告
• 🚧 扩大测试器的自动化测试覆盖范围
• 🚧 提升生产环境适用性并改进打包

如果你有兴趣参与贡献，欢迎提交问题和拉取请求。

简介

Model Context Protocol（MCP）使 AI 模型能够通过标准化接口访问外部工具和数据源。随着 MCP 服务日趋复杂、重要性不断提高，确保其正常运行变得至关重要。MCP 服务测试器通过以下方式满足这一需求：

• 自动测试 MCP 服务提供的所有工具
• 利用 Claude AI 生成智能且与上下文相关的测试用例
• 根据预期结果和架构验证响应
• 提供详细报告，以找出问题和性能瓶颈

此工具面向 MCP 服务开发者、AI 集成团队和质量保证专业人员，帮助他们确保自己的 MCP 实现稳健、可靠，并正确遵循协议规范。

概念

Model Context Protocol 是一项允许 AI 模型调用外部工具的标准。MCP 服务通过简单的 HTTP 接口提供一个或多个工具。每个工具都描述其名称、参数和响应架构，以便模型安全地调用它。

mcp-server-tester 可自动检查 MCP 服务及其工具是否正常运行：

1. 发现 – 查询服务以获取所有可用工具。
2. 生成测试 – 使用 Claude AI 为每个工具创建真实的测试用例。
3. 执行 – 针对服务运行这些测试。
4. 验证 – 使用可配置的规则检查响应。
5. 报告 – 在控制台中或以 JSON、HTML、Markdown 格式汇总结果。

此工具旨在快速发现预期行为与实际行为之间的差异，以便你在将工具提供给生产环境中的模型之前修复问题。

用途

• 可靠性 – 发现 MCP 服务中的错误或不一致行为。
• 回归测试 – 每当服务发生变化时，都运行相同的一组测试。
• 文档 – 生成的报告会说明每个工具的查询和预期结果。
• 自动化 – 将测试器集成到 CI 流水线中，以确保持续保持质量。

仓库

• GitHub：https://github.com/r-huijts/mcp-server-tester
• 问题：https://github.com/r-huijts/mcp-server-tester/issues
• 许可证：MIT

功能

• 🔍 自动发现任意 MCP 服务中的可用工具
• 🧪 使用 Claude AI 为每个工具生成逼真的测试用例
• ⚡ 执行测试并验证响应
• 📊 提供详细的测试报告
• 🔑 通过配置支持多种连接方式
• 基于配置：通过简单的 JSON 配置定义要测试的 MCP 服务
• 支持多个服务：一次测试多个 MCP 服务
• 全面测试：测试每个服务公开的所有工具
• 自然语言上下文：包含会触发每个工具的用户查询，提供真实场景上下文
• 详细报告：生成控制台、JSON、HTML 或 Markdown 格式的报告
• 安全：将 API 密钥保存在环境变量中，而非配置文件中

前置条件

• Node.js 18 或更高版本
• 用于生成测试用例的 Anthropic API 密钥

安装

由于此项目仍在开发中，请通过克隆仓库进行安装：

# Clone the repository
git clone https://github.com/r-huijts/mcp-server-tester.git
cd mcp-server-tester

# Install dependencies
npm install

# Build the project
npm run build

# Create a symbolic link to use it globally (optional)
npm link

基于配置的用法

MCP Server Tester 完全通过配置文件驱动。这种方式有以下优势：

• 可复用性：只需定义一次服务，即可反复测试
• 版本控制：将测试配置与代码一同提交
• 共享：轻松与团队成员共享服务测试配置

基本用法

# Create a .env file with your Anthropic API key
echo "ANTHROPIC_API_KEY=your-api-key-here" > .env

# Run tests using the configuration
mcp-server-tester

# Use a custom configuration file
mcp-server-tester path/to/my-config.json

配置文件结构

配置文件（mcp-servers.json）控制测试的所有方面：

{
  "numTestsPerTool": 3,
  "timeoutMs": 10000,
  "outputFormat": "console",
  "outputPath": "./reports/results.json",
  "verbose": false,
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"],
      "env": {
        "DEBUG": "true"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-github-token-here"
      }
    },
    "dev-server": {
      "command": "node",
      "args": ["/absolute/path/to/your/dev-server.js"],
      "env": {
        "DEBUG": "true",
        "NODE_ENV": "development"
      }
    }
  }
}

默认情况下，该工具会测试 mcpServers 部分中定义的所有服务。如果只想测试特定服务，可以添加可选的 servers 数组：

{
  "servers": ["filesystem", "dev-server"],
  "numTestsPerTool": 3,
  // other settings...
  "mcpServers": {
    // server definitions...
  }
}

配置选项

测试设置

选项	描述	默认值
servers	要测试的特定服务名称的可选数组	mcpServers 中的所有服务
numTestsPerTool	每个工具要生成的测试数量	3
timeoutMs	测试执行超时时间（毫秒）	10000
outputFormat	测试报告格式（json、console、html、markdown）	"console"
outputPath	输出文件路径	undefined
verbose	启用详细日志记录	false

服务定义

mcpServers 部分定义所有可供测试的服务：

属性	描述	必填
command	要运行的可执行文件或命令	是
args	命令行参数数组	是
env	要设置的环境变量	是

服务连接类型

你可以在配置中定义多种类型的 MCP 服务：

NPM 包

"npm-package": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": {}
}

使用相对路径的本地脚本

"python-script": {
  "command": "python",
  "args": ["./servers/custom_server.py"],
  "env": {
    "PORT": "8080"
  }
}

使用绝对路径的本地脚本

适用于测试服务的开发版本：

"dev-server": {
  "command": "node",
  "args": ["/absolute/path/to/your/dev-server.js"],
  "env": {
    "DEBUG": "true",
    "NODE_ENV": "development"
  }
}

Socket 连接

"remote-socket": {
  "command": "nc",
  "args": ["localhost", "3000"],
  "env": {}
}

API 密钥管理

出于安全考虑，Anthropic API 密钥只能通过以下方式之一设置：

1. 环境变量：ANTHROPIC_API_KEY=your-api-key
2. 项目目录中的 .env 文件：

   ANTHROPIC_API_KEY=your-api-key
   

3. 可选择设置 Claude 模型：

   CLAUDE_MODEL=claude-3-opus
   

   如果未提供，工具默认使用 claude-3-7-sonnet-20250219。

重要：切勿将 API 密钥放入配置文件，因为该文件可能会提交到版本控制中。

命令行选项

MCP Server Tester 支持少量命令行选项：

选项	描述
--init 或 -i	创建默认配置文件
--list 或 -l	列出配置中定义的所有服务
--help 或 -h	显示帮助信息
--servers 或 -s	要测试的服务名称列表，以逗号分隔
[config-path]	指定自定义配置文件路径

--servers 选项会覆盖配置文件中的 servers 数组。

测试生成流程

该工具使用 Claude AI 自动为 MCP 服务公开的每个工具生成适当的测试用例：

1. 从服务中发现所有可用工具
2. 对于每个工具，分析：
   • 工具名称和描述
   • 必需和可选参数
   • 参数类型和约束
3. Claude 为每个工具生成多个测试用例：
   • 使用有效输入的正常路径测试
   • 使用边界值的边缘情况测试
   • 使用无效输入的错误情况测试

每个测试用例包括：

• 测试内容的描述
• 输入参数
• 预期结果的判定标准

验证规则类型

验证规则用于检查工具响应的结构和内容。 支持以下规则类型：

• contains – 确保字符串或数组包含给定值
• matches – 检查是否相等或是否匹配正则表达式
• hasProperty – 验证属性是否存在
• equals – 断言某个值与预期值完全一致
• arrayLength – 要求数组具有特定长度
• custom – 调用用户定义的验证函数

测试执行与验证

对于配置中指定的每个服务（如果未指定，则针对所有服务）：

1. 该工具连接到服务
2. 发现所有可用工具
3. 为每个工具生成测试用例
4. 针对服务执行每个测试用例
5. 根据预期结果验证响应
6. 生成结果报告

报告选项

该工具可以生成多种格式的报告，由 outputFormat 配置选项控制：

控制台输出（默认）

直接在终端中显示测试结果。

JSON 报告

在 outputPath 指定的路径创建结构化 JSON 文件。

HTML 报告

在 outputPath 指定的路径生成带可视化内容的 HTML 报告。

Markdown 报告

在 outputPath 指定的路径创建便于移植的 Markdown 文件。

完整示例

基本设置与测试

1. 创建默认配置文件：

   mcp-server-tester --init
   

2. 编辑 mcp-servers.json 文件，添加自己的服务和设置

3. 创建 .env 文件并填入 Anthropic API 密钥：

   echo "ANTHROPIC_API_KEY=your-api-key-here" > .env
   

4. 运行测试：

   mcp-server-tester
   

测试服务的开发版本

要测试 MCP 服务的开发版本：

1. 使用绝对路径为开发服务添加配置：

{
  "mcpServers": {
    "my-dev-server": {
      "command": "node",
      "args": ["/path/to/your/project/dist/server.js"],
      "env": {
        "DEBUG": "true",
        "NODE_ENV": "development"
      }
    }
  }
}

2. 运行测试：

mcp-server-tester

测试多种不同配置

你可以为不同的测试场景维护不同的配置文件：

# Create different config files for different environments
cp mcp-servers.json config-dev.json
cp mcp-servers.json config-prod.json

# Edit each file with appropriate settings

# Run tests with specific config
mcp-server-tester ./config-dev.json
mcp-server-tester ./config-prod.json

故障排除

连接问题

如果连接 MCP 服务时遇到问题：

1. 检查 mcp-servers.json 文件中的服务配置
2. 检查服务是否支持 MCP 协议
3. 尝试为速度较慢的服务增加 timeoutMs
4. 将 verbose: true 设为启用详细日志记录
5. 使用环境变量 DEBUG=true 检查服务进程启动情况

API 密钥问题

如果遇到 API 密钥问题：

1. 确认 Anthropic API 密钥有效
2. 确保已在环境或 .env 文件中正确设置 API 密钥
3. 检查 API 密钥中是否含有空格或多余字符
4. 确认 .env 文件位于正确的位置（项目根目录）

工具执行失败

如果工具执行失败：

1. 确保服务正确实现了 MCP 协议
2. 检查服务日志中的错误
3. 确认工具参数有效
4. 如果工具执行时间较长，请增加超时时间

Node.js 弃用警告

punycode 模块弃用警告

如果遇到此警告：

(node:71439) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.

这是 Node.js 发出的无害警告，表示某个内部模块已弃用。它不会影响 MCP Server Tester 的功能。此警告来自某个依赖项，后续更新会解决此问题。

解决方案：

1. 忽略此警告——它不会影响功能
2. 屏蔽警告——使用 NODE_NO_WARNINGS=1 环境变量运行：

   NODE_NO_WARNINGS=1 mcp-server-tester
   

3. 使用 npm 脚本——附带的 npm 脚本已屏蔽此类警告：

   npm start
   

开发

设置开发环境：

# Clone the repository
git clone https://github.com/r-huijts/mcp-server-tester.git
cd mcp-server-tester

# Install dependencies (including dev dependencies)
npm install
# Run the Jest test suite
npm test
# Lint the code for style issues
npm run lint

# Create your .env file
cp .env.example .env
# Edit .env and add your API key

# Run the tool in development mode
npm run dev

代码结构

规范的测试生成器位于 src/test-generator/TestGenerator.ts。 为避免混淆，已移除 src/generator/TestGenerator.ts 等旧文件。所有导入都应引用 src/test-generator/ 下的模块。

打包与分发

该项目可以发布为 npm 包，以便于安装。

# Compile TypeScript sources
npm run build

# Create a tarball of the package
npm pack

# Publish to npm (requires npm credentials)
npm publish

发布的包仅包含 dist 文件夹的内容和必要的文档。执行 npm publish 时会自动运行构建步骤。

许可证

本项目采用 MIT 许可证。

安装（快速开始）

1. 安装 Node.js 18 或更高版本。
2. 克隆代码库并安装依赖项：

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

3. 可选择全局链接此包，以便在系统范围内使用 mcp-server-tester 命令：

npm link

配置概览

所有行为均由 JSON 配置文件控制（默认为 mcp-servers.json）。该配置列出要测试的 MCP 服务，并定义超时时间和报告格式等选项。

使用 --init 创建文件，或复制提供的示例：

mcp-server-tester --init
# or
cp mcp-servers.json.example mcp-servers.json

编辑文件以添加服务。最简示例如下：

{
  "numTestsPerTool": 2,
  "timeoutMs": 10000,
  "outputFormat": "console",
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"],
      "env": { "DEBUG": "true" }
    }
  }
}

将 Anthropic API 密钥放入 .env 文件，或将其导出为 ANTHROPIC_API_KEY：

ANTHROPIC_API_KEY=your-api-key

运行测试

配置和环境变量就绪后，运行：

mcp-server-tester

使用 mcp-server-tester path/to/config.json 指定其他配置，或使用 --servers filesystem,github 仅测试指定的服务。

了解结果

默认情况下，结果会显示在控制台中。你也可以生成结构化报告：

• JSON——便于后续处理的机器可读数据。
• HTML——易于浏览且包含可折叠部分的摘要。
• Markdown——适用于代码审查的可分享格式。

报告会列出每个工具、用于调用该工具的自然语言查询、响应是否符合验证规则，以及任何失败的详细信息。

基本故障排查

• 连接问题——检查服务路径，并在需要时增大 timeoutMs。
• API 密钥问题——确保已设置 ANTHROPIC_API_KEY，且没有多余空格。
• 工具失败——检查服务日志，并确保实现遵循 MCP 规范。