mcp-tester

MCP 工具测试器

一项全面的技能，用于测试和评估当前 Claude Code 会话中可用的 MCP（Model Context Protocol）服务工具。

使用时机

在以下情况下使用此技能：

• 审核 MCP 服务配置
• 验证工具质量和描述
• 为 MCP 工具生成测试用例
• 检查工具命名约定和参数效率
• 分析不同服务之间的工具冗余
• 评估响应质量和格式效率
• 调试 MCP 集成问题

先决条件

必须在 Claude Code 设置中配置 MCP 服务。如果用户要求测试不存在的工具，请指导他们将 MCP 服务添加到配置中。

工作流

按顺序执行以下阶段，以进行全面测试：

阶段 1：发现

识别当前会话中可用的所有 MCP 工具。

步骤：

1. 列出所有带有 mcp__ 前缀的工具
2. 按服务分组（第二个 __ 之前的命名空间）
3. 生成清单表

输出格式：

## Tool Inventory

| Server | Tool Name | Required Params | Optional Params | Description Preview |
|--------|-----------|-----------------|-----------------|---------------------|
| context7 | resolve-library-id | libraryName, query | - | Resolves package to Context7 ID... |
| context7 | query-docs | libraryId, query | - | Retrieves documentation... |

需报告的指标：

• 服务总数：[数量]
• 工具总数：[数量]
• 各服务的工具数量明细

阶段 2：质量分析

评估每个工具的设计质量。

命名约定分析

检查：

• kebab-case 一致性：使用 get-user，而非 getUser 或 get_user
• 动词优先命名：create-item、list-users、delete-record
• 清晰度：仅凭名称能否理解其用途？
• 命名空间冲突：不同服务之间是否有相似名称

描述质量评分

分数	标准
优秀	用途明确，包含使用情境、示例和输入／输出预期
良好	用途明确，包含一些上下文和基本预期
一般	说明了用途，但缺少上下文或示例
较差	描述含糊、缺失或具有误导性

评估：

• 是否说明了工具的功能？
• 是否说明了何时使用该工具？
• 是否提供了示例场景？
• 是否记录了边缘情况？

参数效率分析

检查：

• 必需参数与可选参数的平衡：必需参数是否确实必要？
• 类型具体程度：在适用的情况下，是否使用 enum 而非通用的 string？
• 默认值：是否提供了合理的默认值？
• 命名清晰度：能否从名称理解参数的用途？
• 令牌开销：估算描述长度对上下文的影响

令牌效率公式：

Efficiency = (Useful information conveyed) / (Token count)

标记描述相对于工具复杂度过于冗长的工具。

严重程度标识

使用以下标识标注发现：

• 🔴 严重：缺少描述、用途不清或架构损坏
• 🟡 警告：描述过于冗长、参数架构低效或命名不清晰
• 🔵 建议：轻微的命名改进、可选增强
• ✅ 优点：设计良好、清晰、高效

分析输出格式：

### Tool: `mcp__server__tool-name`

**Naming**: ✅ Clear verb-first naming
**Description**: 🟡 Warning - Verbose (450 tokens), could be reduced to ~200
**Parameters**: 🔵 Suggestion - Consider enum for `format` param

**Detailed Findings:**
- [Specific observations]

**Recommendations:**
- [Actionable improvements]

阶段 3：测试设计

使用 AAA（Arrange-Act-Assert，准备-执行-断言）模式为每个工具生成测试用例。

测试类别

1. 有效输入（正常路径）

• 仅提供必需参数
• 所有参数均使用有效值
• 有效范围的边界值（最大长度字符串、边界数值）

2. 无效输入（错误处理）

• 缺少必需参数
• 参数类型错误（预期为数字却传入字符串）
• 无效值（负数 ID、格式错误的 URL）
• 格式错误的数据结构

3. 边缘情况

• 空字符串 ""
• 超长字符串（1000 个以上字符）
• 特殊字符和 Unicode
• 类空值概念（null、undefined、None）
• 边界值（0、-1、MAX_INT）
• 仅包含空白字符的字符串

测试用例模板

### Test: [Tool Name] - [Scenario Name]

**Category**: Valid / Invalid / Edge Case

**Arrange**:
- Context: [What setup is needed]
- Preconditions: [What must be true]

**Act**:
```json
{
  "param1": "value1",
  "param2": "value2"
}

断言：

• 预期行为：[应发生什么]
• 预期响应格式：[结构]
• 预期错误（如果无效）：[错误类型／消息]

#### Test Generation Guidelines

For each tool, generate at minimum:
1. 1 happy path test with minimal params
2. 1 happy path test with all params
3. 1 missing required param test
4. 1 wrong type test
5. 1 edge case test (empty/boundary)

### Phase 4: Test Execution

Execute generated tests and capture results.

#### Read-Only Tools
Execute immediately without confirmation:
- Tools that fetch/query data
- Tools that list/search resources
- Tools that analyze/inspect

#### Mutating Tools
**ALWAYS ask for confirmation before testing:**

```markdown
⚠️ **Mutating Tool Detected**

Tool: `mcp__server__create-item`
Operation: Creates new item in external system

**Test Parameters:**
```json
{
  "name": "test-item-12345",
  "type": "test"
}

潜在影响：

• 将在外部系统中创建新项目
• 可能会触发 Webhook 或通知
• 可能需要手动清理项目

继续此测试吗？（是／否／跳过）

Mutating operations include:
- `create`, `write`, `post`, `add`, `insert`
- `update`, `edit`, `modify`, `patch`, `put`
- `delete`, `remove`, `destroy`, `clear`
- `send`, `publish`, `trigger`, `execute`

#### Response Capture

For each test, capture:
- Full response content (truncate if > 2000 chars)
- Response time (if perceivable delay)
- Error messages and codes
- Unexpected warnings or notices

### Phase 5: Rating & Feedback

Rate each tool's test results and provide actionable feedback.

#### Rating Criteria

| Rating | Symbol | Criteria |
|--------|--------|----------|
| **Worked** | ✅ | Response matches expected format, no errors, useful output |
| **Partially Worked** | 🟡 | Response returned but incomplete, warnings present, or unexpected format |
| **Failed** | ❌ | Error returned, timeout, or completely wrong behavior |

#### Quality Assessment Dimensions

1. **Response Completeness** (High/Medium/Low)
   - Does it return all expected data?
   - Are there missing fields?

2. **Response Efficiency** (High/Medium/Low)
   - Token usage vs. value provided
   - Unnecessary verbosity in response?

3. **Error Handling** (Clear/Vague/Missing)
   - Are error messages helpful?
   - Do they indicate how to fix the issue?

4. **Format Consistency** (Consistent/Inconsistent)
   - Does response format match description?
   - Is format consistent across calls?

#### Feedback Template

```markdown
## Tool: `mcp__server__tool-name`

### Test Results Summary
| Test | Category | Rating | Notes |
|------|----------|--------|-------|
| Minimal params | Valid | ✅ Worked | Response in 200ms |
| All params | Valid | ✅ Worked | - |
| Missing required | Invalid | 🟡 Partial | Error unclear |
| Wrong type | Invalid | ❌ Failed | No error, silent fail |
| Empty string | Edge | ✅ Worked | Handled gracefully |

### Overall Rating: 🟡 Partially Worked (4/5 tests passed)

### Quality Assessment
- **Completeness**: High - Returns all documented fields
- **Efficiency**: Medium - Response includes redundant metadata
- **Error Handling**: Vague - Errors don't indicate fix
- **Consistency**: Consistent

### Critical Issues
🔴 Silent failure on wrong type - should return validation error

### Improvement Suggestions
1. Add input validation with descriptive error messages
2. Remove redundant `metadata.internal_id` from response (saves ~50 tokens)
3. Consider pagination for list responses

阶段 6：跨工具分析

整体分析这组工具。

冗余检测

检查：

• 功能重叠的工具
• 不同服务中的类似操作
• 名称不同但能力重复的工具

输出格式：

## Redundancy Findings

| Tool A | Tool B | Overlap | Recommendation |
|--------|--------|---------|----------------|
| mcp__a__get-user | mcp__b__fetch-user | 90% same function | Consolidate to single tool |
| mcp__a__list-all | mcp__a__search | Search can replace list | Deprecate list-all |

整合机会

识别可以进行以下处理的工具：

• 合并：将类似工具合并为一个带模式参数的工具
• 批处理：将单个操作整合为批量操作
• 简化：将复杂工具拆分为专注于特定功能的工具

缺失的能力

指出工具覆盖方面的空缺：

• CRUD 操作不完整（支持创建但不支持删除）
• 读取操作不支持筛选
• 没有针对单个操作的批量替代方案

效率建议

## Efficiency Recommendations

### High Impact
1. **Reduce description verbosity** - 3 tools have descriptions >500 tokens
   - Potential savings: ~800 tokens total

### Medium Impact
2. **Add enum constraints** - 5 parameters accept free text but have limited valid values
   - Improves: Validation, documentation, autocomplete

### Low Impact
3. **Standardize naming** - Mix of `get-X` and `fetch-X` patterns
   - Improves: Consistency, discoverability

输出报告模板

完成所有阶段后生成此报告：

# MCP Tool Test Report

**Generated**: [timestamp]
**Session ID**: [if available]

---

## Executive Summary

| Metric | Value |
|--------|-------|
| Servers Tested | [N] |
| Tools Tested | [N] |
| Tests Executed | [N] |
| Pass Rate | [X]% |

### Results Overview
- ✅ **Passed**: [X] tools
- 🟡 **Partial**: [Y] tools
- ❌ **Failed**: [Z] tools

### Key Findings
- 🔴 [N] critical issues requiring immediate attention
- 🟡 [N] warnings to address
- 🔵 [N] suggestions for improvement

---

## Tool Inventory

[Phase 1 output]

---

## Quality Analysis

[Phase 2 output for each tool]

---

## Test Results

[Phase 5 output for each tool]

---

## Cross-Tool Analysis

[Phase 6 output]

---

## Recommendations

### 🔴 Critical (Must Address)
1. [Issue] - [Tool] - [Impact] - [Fix]

### 🟡 Warning (Should Address)
1. [Issue] - [Tool] - [Impact] - [Fix]

### 🔵 Suggestions (Consider)
1. [Improvement] - [Tool] - [Benefit]

---

*Report generated by mcp-tester skill*

常见陷阱

本节记录了测试 MCP 工具时遇到的真实故障模式和反模式。这些问题不易察觉，往往要经过反复试错才能发现。

测试覆盖不完整（缺少边界情况和错误路径）

问题： 测试使用正常情况的输入时可以通过，但在生产环境中遇到边界情况或错误条件时会失败。缺少错误路径测试会导致工具可靠性方面的盲点。

应避免的反模式：

• ❌ 只使用最低限度的必需参数进行测试——工具可能会因可选参数而出错
• ❌ 只测试成功路径——错误处理同样重要
• ❌ 只使用符合实际情况的数据——不符合实际情况的值可以暴露架构验证方面的漏洞
• ❌ 不测试边界条件（最大长度字符串、零、负数、空集合）
• ❌ 跳过 Unicode／特殊字符测试——这通常能揭示编码问题

模式：全面测试矩阵

For each tool, test:
✅ Happy path: minimal params
✅ Happy path: all params  
✅ Missing required param (each required param tested separately)
✅ Wrong param type (string to number, number to boolean, etc.)
✅ Invalid enum value (param expects ['active', 'inactive'], test 'disabled')
✅ Empty string / null-like values
✅ Very long strings (1000+ chars, 10K+ chars)
✅ Special characters: !@#$%^&*()_+-={}[]|:;"'<>?,./~`
✅ Unicode: emoji, CJK, RTL text
✅ Boundary values: 0, -1, MAX_INT, Float edge cases
✅ Malformed data: incomplete JSON, null objects, circular references

**影响：**测试覆盖不完整 → 工具在使用真实数据时会失败

---

模拟依赖的行为不正确（测试数据不符合实际情况）

问题： 使用模拟数据的测试可以通过，但调用真实 MCP 服务时会失败。模拟行为与实际服务行为不符，例如超时、错误格式、响应大小等。

应避免的反模式：

• ❌ 模拟响应过小（模拟仅返回 10 个条目，而真实 API 返回 1000 多个）
• ❌ 以非标准格式模拟错误响应（真实服务返回不同的错误结构）
• ❌ 假定模拟响应会立即返回——真实服务存在延迟
• ❌ 模拟成功情况，而真实服务实际需要身份验证
• ❌ 模拟时不遵守速率限制
• ❌ 模拟返回 null／空响应，而真实服务返回验证错误

模式：符合实际情况的模拟行为

When mocking MCP tool responses:
✅ Return realistic response sizes (don't shrink large responses to 1-2 items)
✅ Match actual error response format (test against real API error docs)
✅ Add realistic latency (~100-500ms for network calls)
✅ Include rate limit headers/indicators in mock
✅ Mock pagination correctly (include next_page token, limits)
✅ Match response schema exactly, including optional fields that are usually present
✅ Test against actual MCP server output when possible (don't guess schema)

不匹配示例：

// ❌ Mock (too clean)
{ "users": [{ "id": 1, "name": "Alice" }] }

// ✅ Real API (includes metadata, nulls, pagination)
{
  "data": [{ "id": 1, "name": "Alice", "email": null, "tags": [] }],
  "meta": { "total": 5000, "page": 1, "limit": 50, "next": "cursor-xyz" },
  "timing": { "ms": 234 }
}

**影响：**使用模拟的测试在本地可以通过，但连接真实 MCP 服务时会失败

---

异步时序问题（竞态条件与超时）

问题： 单独运行测试时可以通过，但并行运行时会间歇性失败。设置／清理过程中的竞态条件、无法成立的超时假设，或完成顺序不可预测的异步操作都可能导致此问题。

应避免的反模式：

• ❌ 假定工具会在固定的超时时间内响应（例如，“所有工具都能在 1 秒内响应”）
• ❌ 未进行适当隔离就并行运行测试
• ❌ 未在断言前等待异步操作完成
• ❌ 未适当重置 MCP 服务连接，就在测试间重复使用
• ❌ 假定并发测试运行时会按特定顺序执行
• ❌ 未使用实际延迟进行测试就设置任意超时值
• ❌ 未处理服务预热时间（首次请求比后续请求更慢）

模式：稳健的异步测试

✅ Set timeouts per tool (measure real response times first)
✅ Use proper async/await or .then() chains — no unhandled promises
✅ Isolate tests: each test gets fresh MCP server connection if possible
✅ Add explicit setup/teardown phases with proper waiting
✅ For concurrent tests: use semaphores/locks to prevent interference
✅ Test with real latency: add 100-500ms overhead to account for network
✅ Run tests multiple times to catch intermittent failures
✅ Use flake detection: run failing tests 5x to confirm it's not timing

竞态条件示例：

// ❌ No await - assertion runs before operation completes
const test = () => {
  callMCPTool({ param: "value" });
  assert(responseReceived); // Fails! Call still pending
};

// ✅ Proper await
const test = async () => {
  const response = await callMCPTool({ param: "value" });
  assert(response.success); // Now it's safe to assert
};

**影响：**测试时而通过、时而失败，导致对测试结果缺乏信心

---

工具架构验证缺口（接受无效参数）

问题： 工具接受了本应被架构验证拒绝的无效参数值。MCP 架构验证不完整，导致无效输入传递到服务端，并在后续引发难以理解的错误。

应避免的反模式：

• ❌ 未测试必需参数验证（缺少必需参数时应报错）
• ❌ 假设枚举验证有效（测试是否会拒绝无效的枚举值）
• ❌ 未检查类型强制转换（工具可能会接受字符串 "123"，而要求的类型是数字 123）
• ❌ 跳过长度/模式验证（字符串可以是 1 个字符，也可以是 10K 个字符？）
• ❌ 未测试嵌套对象架构（子对象中的必需字段）
• ❌ 假设应拒绝 null 时会拒绝（反之亦然）
• ❌ 未检查互斥约束（参数 A 和 B 不能同时存在）

模式：全面的架构测试

For each parameter:
✅ Test missing (should fail if required)
✅ Test wrong type (if expects number, pass string)
✅ Test enum validation (if expects ['a','b','c'], test 'd')
✅ Test length constraints (min/max length for strings)
✅ Test pattern/format validation (regex patterns, URLs, emails)
✅ Test numeric bounds (min/max for numbers, negative values)
✅ Test nested object structure (all required fields present?)
✅ Test null vs undefined behavior
✅ Test special characters in string params
✅ Validate response schema (returned data matches documented format)

验证缺口示例：

// Tool spec says: name (required, string, max 255 chars)
// Test reveals:
callMCPTool({ name: 123 }) // ❌ Accepted! Should reject (not a string)
callMCPTool({ name: "a".repeat(1000) }) // ❌ Accepted! Should reject (>255 chars)
callMCPTool({ }) // ❌ Accepted! Should reject (required param missing)

**影响：**工具接受无效请求 → MCP 服务返回令人困惑的错误，难以调试根本原因

---

集成测试失败（服务端/客户端不匹配）

问题： 工具在针对模拟对象的单元测试中运行正常，但在针对真实 MCP 服务的集成测试中失败。工具架构与服务端预期不符、响应格式不同，或端点已更改。

应避免的反模式：

• ❌ 只使用模拟对象进行单元测试——跳过集成测试
• ❌ 单独测试工具，不调用实际的 MCP 服务
• ❌ MCP 服务 API 更改后未更新测试
• ❌ 假设向后兼容——新的服务端版本会导致旧测试数据失效
• ❌ 未在集成测试中测试身份验证/授权
• ❌ 跳过权限/范围验证（工具规范要求权限 X）
• ❌ 集成测试只测试成功场景——不测试错误场景

模式：集成测试

Separate unit tests (mocks) from integration tests (real server):

✅ Unit tests: test schema validation, parameter handling, response parsing
✅ Integration tests: call actual MCP server with real credentials/permissions
✅ Version your integration tests: document which server version they test
✅ Test error paths in integration: wrong credentials, missing permissions, server errors
✅ Validate response against schema in integration tests
✅ Test server downtime handling (timeouts, retries)
✅ Test against multiple server versions if applicable
✅ Use test fixtures: real-world data from actual server responses

不匹配示例：

// Unit test passes
callMCPTool({ userId: 123 }) // ✅ Mock returns { user: { id: 123 } }

// Integration test fails  
callMCPTool({ userId: 123 }) // ❌ Real server expects { user_id: 123 } (different key!)

**影响：**测试在本地通过，但在 CI/生产环境中针对真实 MCP 服务时失败

---

预防策略

完成工具测试前，请使用此清单：

• 已测试所有参数：必需、可选、类型错误、无效值、边界值
• 已覆盖边缘情况：空值、超大值、Unicode、特殊字符
• 已测试错误路径：所有可能的错误条件
• 模拟对象与实际情况一致：响应大小、格式、延迟、错误
• 已正确等待异步操作：无竞态条件
• 超时时间合理：基于实际测量，而非猜测
• 已测试架构验证：适当地拒绝无效输入
• 已包含集成测试：针对真实 MCP 服务进行测试
• 已验证版本兼容性：工具可与当前服务端版本配合使用
• 已多次运行测试：确认没有不稳定或计时问题

---

示例

示例 1：测试所有可用工具

用户：“测试我的所有 MCP 工具”

响应流程：

1. 发现 3 个服务，共有 8 个工具
2. 提供清单表格以供确认
3. 分析质量（发现 2 个警告、1 条建议）
4. 生成 40 个测试用例（每个工具 5 个）
5. 识别出 2 个会修改数据的工具，并征求确认
6. 执行测试并记录结果
7. 评分：6 个通过、1 个部分通过、1 个失败
8. 分析工具间情况：发现 1 项冗余
9. 生成完整报告

示例 2：测试特定服务

用户：“只测试 context7 MCP 工具”

响应流程：

1. 筛选出 context7 服务（2 个工具）
2. 深入分析这两个工具
3. 生成 10 个测试用例
4. 没有会修改数据的工具——全部执行
5. 生成重点报告

示例 3：仅进行质量审计

用户：“审查我的 MCP 工具描述，不运行测试”

响应流程：

1. 发现阶段
2. 全面质量分析
3. 跳过测试执行
4. 提供侧重质量的报告，并给出改进建议

示例 4：缺少 MCP 服务

用户：“测试 notion MCP 工具”

回复：

I don't see any Notion MCP tools in the current session.

To add a Notion MCP server:

1. Install the server:
   ```bash
   npm install -g @notionhq/notion-mcp-server

2. 添加到你的 Claude Code MCP 配置中（~/.claude/mcp_settings.json）：

   {
     "mcpServers": {
       "notion": {
         "command": "notion-mcp-server",
         "env": {
           "NOTION_API_KEY": "your-api-key"
         }
       }
     }
   }
   

3. 重启 Claude Code 以加载新服务

需要我帮你配置吗？

## Error Recovery

If a test fails or times out:
1. Log the failure with available details
2. Continue testing remaining tools
3. Include failure in final report
4. Suggest debugging steps for failed tools

## MCP Inspector: Standalone Testing

For testing outside of Claude Code sessions, use the MCP Inspector:

```bash
# Launch MCP Inspector UI (browser-based)
npx @modelcontextprotocol/inspector

# Test a specific stdio server
npx @modelcontextprotocol/inspector stdio node /path/to/server.js

# Test a specific HTTP server
npx @modelcontextprotocol/inspector http http://localhost:3000/mcp

# With environment variables
MCP_API_KEY=your-key npx @modelcontextprotocol/inspector stdio node server.js

MCP Inspector 提供：

• 交互式工具调用界面
• 架构验证显示
• 请求/响应检查
• 服务功能发现

调试 MCP 连接问题

# Check if MCP server process starts correctly
node dist/index.js  # Should hang waiting for input (stdio) or log port (HTTP)

# Test stdio protocol manually
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | node dist/index.js

# Check server logs (stderr for stdio servers)
node dist/index.js 2>server.log &
# Then interact, then cat server.log

# For HTTP servers
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

局限性

• 无法测试当前会话中未配置的 MCP 工具
• 不会直接向 MCP 服务 URL 发送 HTTP 请求
• 无法测试需要在流程中途进行交互式身份验证的工具
• 响应时间测量为近似值（基于感知到的延迟）
• 测试服务启动问题和协议合规性需要 MCP Inspector