使用说明

MCP服务器测试仪

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

一个强大的、配置驱动的测试工具，用于模型上下文协议（MCP）服务器。该项目为验证、基准测试和确保与Claude等人工智能模型集成的MCP服务器的可靠性提供了一个全面的解决方案。

当前状态

该工具正在向alpha版本迈进，目前提供：

✅ 基本配置框架
✅ MCP服务器连接和CLI支持
✅ 使用Claude AI生成测试
✅ 测试的自然语言查询生成
✅ 具有多种规则的全面响应验证
✅ 以控制台、JSON、HTML和Markdown格式生成报告
🚧 测试仪的自动化测试覆盖范围更广
🚧 生产硬化和包装改进

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

引言

模型上下文协议（MCP）使AI模型能够通过标准化的接口访问外部工具和数据源。随着MCP服务器的复杂性和重要性的增加，确保其正确的功能变得至关重要。MCP服务器测试仪通过以下方式满足了这一需求：

自动化测试 适用于MCP服务器公开的所有工具
利用Claude AI 生成智能、上下文相关的测试用例
正在验证响应 对照预期结果和模式
提供详细报告 识别问题和性能瓶颈

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

概念

模型上下文协议是一个允许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
许可证: 麻省理工学院

特性

🔍 自动从任何MCP服务器发现可用工具
🧪 使用Claude AI为每个工具生成逼真的测试用例
⚡ 执行测试并验证响应
📊 提供详细的测试报告
🔑 通过配置支持多种连接方式
基于配置：用于定义要测试的MCP服务器的简单JSON配置
多服务器支持：一次测试多个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服务器测试仪设计为完全通过配置文件驱动。这种方法有几个优点：

可重复使用性：定义服务器一次，反复测试
版本控制：在代码旁边检查测试配置
共享：轻松与团队成员共享服务器测试配置

基本用法

# 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`)	“控制台”
`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报告

在中指定的路径处创建结构化JSON文件 outputPath.

HTML报告

在中指定的路径上生成具有可视化效果的HTML报告 outputPath.

Markdown报告

在中指定的路径处创建可移植的Markdown文件 outputPath.

完整示例

基本设置和测试

创建默认配置文件：
```
mcp-server-tester --init
```
编辑 mcp-servers.json 文件以添加您自己的服务器和设置
创建一个 .env 使用您的Anthropic API密钥文件：
```
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

测试多种不同的配置

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

# 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服务器时遇到问题：

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

API关键问题

如果您遇到API关键问题：

验证您的Anthropic API密钥是否有效
确保在环境或.env文件中正确设置了API密钥
检查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
```

发展

设置开发环境：

# 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 被执行。

许可证

该项目根据麻省理工学院许可证。

安装（快速启动）

安装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
# 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 仅测试某些服务器。

了解结果

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

对象符号 –用于进一步处理的机器可读数据。
超文本标记语言 –使用可折叠的部分轻松浏览摘要。
降价 –适合代码审查的可共享格式。

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

故障排除基础知识

连接问题 –验证服务器路径并增加 timeoutMs 如果需要的话。
API关键问题 –确保 ANTHROPIC_API_KEY 设置为没有额外空格。
工具故障 –检查服务器日志，确保您的实现符合MCP规范。