# MCP Inspector 集成测试 - 需求文档
> 生成时间：2025-12-04
> 基于项目：Web Analysis MCP
> 技术栈：TypeScript + MCP SDK + Node.js
---
## 项目概况
**技术栈**：TypeScript + MCP SDK + Node.js
**架构模式**：分层架构（工具层/服务层/配置层）
**代码风格**：TypeScript严格模式 + Zod验证 + 模块化设计
---
## 改动点
### 要实现什么
- **核心功能 1**：添加 MCP Inspector 测试配置，支持快速测试所有 MCP 工具
- **核心功能 2**：创建测试用例集合，覆盖所有工具的使用场景
- **核心功能 3**：提供测试指南，方便开发者调试和验证功能
### 与现有功能的关系
- **依赖现有模块**：所有 tools/* 下的工具 - 需要通过 Inspector 测试
- **集成位置**：项目根目录添加测试配置文件
### 新增依赖
- **无新增依赖** - MCP Inspector 是独立的测试工具
---
## 实现方案
### 需要修改的文件
```
package.json # 添加测试脚本
README.md # 添加 MCP Inspector 使用说明
```
### 需要新增的文件
```
.mcp-inspector.json # MCP Inspector 配置文件
tests/inspector/ # Inspector 测试用例目录
├── web-search.test.json # web_search 工具测试
├── fetch-summary.test.json # fetch_and_summarize 工具测试
└── batch-fetch.test.json # batch_fetch 工具测试
docs/testing-with-inspector.md # Inspector 使用指南
```
### 实施步骤
**步骤 1：环境准备**
- [ ] 确保环境变量配置完整
- [ ] 验证 tavily-mcp 服务可访问
**步骤 2：创建 MCP Inspector 配置**
- [ ] 创建 `.mcp-inspector.json` 配置文件
- [ ] 配置 MCP 服务器连接参数
- [ ] 设置测试环境变量
**步骤 3：创建测试用例集合**
- [ ] 创建 web_search 测试用例（包含不同场景）
- [ ] 创建 fetch_and_summarize 测试用例（单URL测试）
- [ ] 创建 batch_fetch 测试用例（批量URL测试）
- [ ] 添加错误场景测试用例
**步骤 4：集成到项目**
- [ ] 在 package.json 添加测试脚本
- [ ] 更新 README.md 添加测试说明
**步骤 5：测试验证**
- [ ] 使用 Inspector 运行所有测试用例
- [ ] 验证每个工具的输出格式
- [ ] 测试错误处理和边界条件
**步骤 6：文档更新**（必须执行）
更新以下文档：
**CHANGELOG.md**（在 `## [Unreleased]` 下添加）：
```markdown
### Added
- **测试**：集成 MCP Inspector 测试框架
- 添加 Inspector 配置和测试用例集合
- 支持所有三个 MCP 工具的自动化测试
- 相关文件：`.mcp-inspector.json`, `tests/inspector/*`
```
**README.md**（新增测试章节）：
```markdown
## 测试
### 使用 MCP Inspector 测试
MCP Inspector 是一个强大的 MCP 服务测试工具，可以快速验证所有工具功能。
#### 安装 Inspector
```bash
npm install -g @modelcontextprotocol/inspector
```
#### 运行测试
```bash
# 运行所有测试用例
npm run test:inspector
# 或直接使用 Inspector
mcp-inspector --config .mcp-inspector.json
```
#### 测试用例
- `web-search`：测试网络搜索功能
- `fetch-summary`：测试单页面抓取和总结
- `batch-fetch`：测试批量页面处理
```
**CLAUDE.md**（添加测试说明）：
```markdown
## 测试
使用 MCP Inspector 进行功能测试：
1. 配置环境变量（参考 Environment Variables）
2. 运行 `npm run test:inspector`
3. Inspector 会自动测试所有工具并提供详细报告
```
**步骤 7：提交代码**（必须执行）
使用 **Bash 工具**执行：
```bash
git add .
git commit -m "feat: 集成 MCP Inspector 测试框架
- 添加 .mcp-inspector.json 配置文件
- 创建完整的测试用例集合覆盖所有工具
- 新增 Inspector 使用指南文档
- 支持 web_search、fetch_and_summarize、batch_fetch 测试
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>"
```
**步骤 8：自我检查**
- [ ] Inspector 配置文件是否正确
- [ ] 所有测试用例是否能正常运行
- [ ] CHANGELOG.md 是否已更新
- [ ] README.md 是否添加了测试说明
- [ ] CLAUDE.md 是否添加了测试指南
- [ ] 所有新增文件是否已提交
---
## 使用方式
### MCP Inspector 配置
```json
{
"servers": {
"web-analysis": {
"command": "npm",
"args": ["run", "dev"],
"env": {
"TAVILY_API_KEY": "${TAVILY_API_KEY}",
"SUMMARY_API_KEY": "${SUMMARY_API_KEY}",
"TAVILY_MCP_PATH": "./node_modules/.bin/tavily-mcp"
}
}
}
}
```
### 测试命令
```bash
# 运行所有测试
npm run test:inspector
# 运行特定测试用例
mcp-inspector --config .mcp-inspector.json --test web-search
```
### 测试用例示例
```json
{
"name": "Web Search Test",
"tool": "web_search",
"arguments": {
"query": "TypeScript MCP development",
"max_results": 5
},
"expect": {
"status": "success",
"has_content": true
}
}
```
---
## 注意事项
**技术风险**：确保测试环境与生产环境配置一致
**测试隔离**：每个测试用例应独立，避免相互依赖
**性能考虑**：测试用例应控制请求频率，避免触发 API 限制
