MCP服务器测试器

Name: MCP服务器测试器
Author: r-huijts

作者：r-huijts9 星标更新：2025-05-23

安装使用来源：spider==github.com

项目介绍

MCP Server Tester

⚠️ 进行中: 此项目正在积极开发中，尚未经过彻底测试。功能可能不完整、存在错误或有重大变化。仅在非生产环境中使用，并自行承担风险。

一个强大的、基于配置的测试工具，用于Model Context Protocol (MCP)服务器。此项目提供了一个全面的解决方案，用于验证、基准测试和确保与Claude等AI模型集成的MCP服务器的可靠性。

当前状态

该工具正朝着alpha版本发布迈进，目前提供了以下功能：

✅ 基本配置框架
✅ MCP服务器连接和CLI支持
✅ 使用Claude AI生成测试
✅ 生成用于测试的自然语言查询
✅ 使用多个规则进行综合响应验证
✅ 在控制台、JSON、HTML和Markdown格式下生成报告
🚧 更广泛的自动化测试覆盖范围
🚧 生产环境加固和打包改进

如果您有兴趣贡献，请随时打开问题并提交拉取请求。

简介

Model Context Protocol (MCP)允许AI模型通过标准化接口访问外部工具和数据源。随着MCP服务器复杂性和重要性的增加，确保其正确功能变得至关重要。MCP Server Tester通过以下方式解决了这一需求：

自动化测试 所有由MCP服务器暴露的工具
利用Claude AI 生成智能且上下文相关的测试用例
验证响应 对比预期结果和模式
提供详细报告 以识别问题和性能瓶颈

此工具设计用于MCP服务器开发者、AI集成团队以及需要确保其MCP实现稳健、可靠并正确遵循协议规范的质量保证专业人员。

概念

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

mcp-server-tester自动化了检查MCP服务器及其工具是否正常工作的过程：

发现 – 查询服务器获取所有可用工具。
测试生成 – 使用Claude AI为每个工具创建现实的测试案例。
执行 – 将这些测试运行到服务器上。
验证 – 使用可配置规则验证响应。
报告 – 在控制台或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密钥

安装

由于该项目仍在开发中，安装是通过克隆仓库完成的：

# 克隆仓库
git clone https://github.com/r-huijts/mcp-server-tester.git
cd mcp-server-tester

# 安装依赖项
npm install

# 构建项目
npm run build

# 创建全局符号链接（可选）
npm link

基于配置的使用

MCP Server Tester完全通过配置文件驱动设计。这种方法提供了几个优点：

可重用性: 一次定义服务器，多次测试
版本控制: 将测试配置与代码一起签入
共享: 轻松与团队成员分享服务器测试配置

基本使用

# 创建一个包含您的Anthropic API密钥的.env文件
echo "ANTHROPIC_API_KEY=your-api-key-here" > .env

# 使用配置运行测试
mcp-server-tester

# 使用自定义配置文件
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,
  // 其他设置...
  "mcpServers": {
    // 服务器定义...
  }
}

配置选项

测试设置

选项	描述	默认值
`servers`	可选的特定服务器名称数组	`mcpServers` 中的所有服务器
`numTestsPerTool`	每个工具生成的测试数量	3
`timeoutMs`	测试执行超时时间（毫秒）	10000
`outputFormat`	测试报告格式（`json`、`console`、`html`、`markdown`）	"console"
`outputPath`	输出文件路径	未定义
`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"
  }
}

套接字连接

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

API密钥管理

出于安全原因，您的Anthropic API密钥应仅以以下方式之一设置：

环境变量：ANTHROPIC_API_KEY=your-api-key
项目目录中的.env文件：
```
ANTHROPIC_API_KEY=your-api-key
```
可选设置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服务器暴露的每个工具生成适当的测试案例：

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

每个测试案例包括：

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

验证规则类型

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

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

测试执行和验证

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

工具连接到服务器
它发现所有可用工具
它为每个工具生成测试案例
它将每个测试案例执行到服务器
它将响应与预期结果进行验证
它生成结果报告

报告选项

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

控制台输出（默认）

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

JSON报告

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

HTML报告

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

Markdown报告

在 outputPath 指定的路径创建便携的Markdown文件。

完整示例

基本设置和测试

创建默认配置文件：
```
mcp-server-tester --init
```
编辑 mcp-servers.json 文件以添加自己的服务器和设置
创建包含您的Anthropic API密钥的.env文件：
```
echo "ANTHROPIC_API_KEY=your-api-key-here" > .env
```
运行测试：
```
mcp-server-tester
```

测试您的服务器的开发版本

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

添加具有绝对路径的开发服务器配置：

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

运行测试：

mcp-server-tester

测试多种不同配置

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

# 为不同的环境创建不同的配置文件
cp mcp-servers.json config-dev.json
cp mcp-servers.json config-prod.json

# 编辑每个文件以包含适当的设置

# 使用特定配置运行测试
mcp-server-tester ./config-dev.json
mcp-server-tester ./config-prod.json

故障排除

连接问题

如果您遇到连接到MCP服务器的问题：

验证 mcp-servers.json 文件中的服务器配置
检查服务器是否支持MCP协议
尝试增加 timeoutMs 以适应较慢的服务器
通过设置 verbose: true 启用详细日志记录
使用环境变量 DEBUG=true 检查服务器进程启动

API密钥问题

如果您遇到API密钥问题：

验证您的Anthropic API密钥是否有效
确保API密钥正确设置在环境或.env文件中
检查API密钥是否有空格或其他额外字符
确认.env文件位于正确的位置（项目根目录）

工具执行失败

如果工具执行失败：

确保您的服务器正确实现了MCP协议
检查服务器日志中的错误
验证工具参数是否有效
如果工具执行时间较长，请增加超时时间

Node.js弃用警告

`punycode`模块弃用警告

如果您遇到此警告：

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

这是Node.js关于内部模块被弃用的无害警告。它不影响MCP Server Tester的功能。警告来自其中一个依赖项，并将在未来的更新中解决。

解决方案：

忽略警告 - 它不影响功能
抑制警告 - 使用 NODE_NO_WARNINGS=1 环境变量运行：
```
NODE_NO_WARNINGS=1 mcp-server-tester
```
使用npm脚本 - 包含的npm脚本已经抑制了这些警告：
```
npm start
```

开发

要设置开发环境：

# 克隆仓库
git clone https://github.com/r-huijts/mcp-server-tester.git
cd mcp-server-tester

# 安装依赖项（包括开发依赖项）
npm install
# 运行Jest测试套件
npm test
# 检查代码风格问题
npm run lint

# 创建您的.env文件
cp .env.example .env
# 编辑.env并添加您的API密钥

# 在开发模式下运行工具
npm run dev

代码结构

主要的测试生成器位于 src/test-generator/TestGenerator.ts。旧文件如 src/generator/TestGenerator.ts 已删除以避免混淆。所有导入应引用 src/test-generator/ 下的模块。

打包和分发

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

# 编译TypeScript源代码
npm run build

# 创建包的tarball
npm pack

# 发布到npm（需要npm凭证）
npm publish

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

许可证

此项目根据MIT许可证授权。

安装（快速开始）

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

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

可选地将包全局链接，使 mcp-server-tester 命令在整个系统中可用：

npm link

配置概述

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

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

mcp-server-tester --init
# 或
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