MCP 服务器

MCP Server Tester

用于模型上下文协议 (MCP) 服务器的自动化测试工具 - 正在进行中

r-huijts

开发者工具

访问服务器

README

MCP 服务器测试器

⚠️ 开发中: 此项目正在积极开发中，尚未经过全面测试。功能可能不完整、包含错误或发生重大更改。仅在非生产环境中自行承担风险使用。

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

当前状态

该工具处于早期开发阶段，具有以下功能：

✅ 实现了基本配置框架
✅ MCP 服务器连接能力
✅ 使用 Claude AI 生成测试
✅ 用于测试的自然语言查询生成
✅ 多种格式的报告生成
🚧 综合测试验证（进行中）
🚧 附加报告选项（进行中）
❌ 工具本身的完整测试覆盖率
❌ 生产环境强化

如果您有兴趣贡献，请随时提出问题并提交 pull request。

介绍

Model Context Protocol (MCP) 使 AI 模型能够通过标准化接口访问外部工具和数据源。随着 MCP 服务器的复杂性和重要性不断提高，确保其正确的功能变得至关重要。MCP 服务器测试器通过以下方式解决此需求：

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

此工具专为 MCP 服务器开发人员、AI 集成团队和质量保证专业人员设计，他们需要确保其 MCP 实现是健壮的、可靠的，并且正确遵循协议规范。

仓库

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 格式生成报告
安全: 将 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 服务器测试器旨在完全通过配置文件驱动。这种方法提供了几个优点：

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

基本用法

# 创建一个包含 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`)	"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 密钥应仅通过以下方式之一设置：

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

重要提示: 永远不要将 API 密钥放在配置文件中，因为它可能会被提交到版本控制。

命令行选项

MCP 服务器测试器支持最少的命令行选项：

选项	描述
`--init` 或 `-i`	创建一个默认配置文件
`--list` 或 `-l`	列出配置中定义的所有服务器
`--help` 或 `-h`	显示帮助信息
`[config-path]`	指定自定义配置文件路径

测试生成过程

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

它从服务器发现所有可用的工具
对于每个工具，它分析：
- 工具名称和描述
- 必需和可选参数
- 参数类型和约束
Claude 为每个工具生成多个测试用例：
- 具有有效输入的 Happy path 测试
- 具有边界值的 Edge case 测试
- 具有无效输入的 Error case 测试

每个测试用例包括：

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

测试执行和验证

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

该工具连接到服务器
它发现所有可用的工具
它为每个工具生成测试用例
它针对服务器执行每个测试用例
它根据预期结果验证响应
它生成结果报告

报告选项

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

控制台输出（默认）

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

JSON 报告

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

HTML 报告

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

完整示例

基本设置和测试

创建一个默认配置文件：
```
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 服务器测试器的功能。该警告来自其中一个依赖项，将在未来的更新中解决。

解决方案：

忽略警告 - 它不影响功能
禁止警告 - 使用 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

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

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

许可证

MIT