ZenTao MCP Server

# 🧪 ZenTao MCP 服务器完整测试方案 基于 `steviec/mcp-server-tester` 的企业级 MCP 服务器测试解决方案 ## 📋 项目概述 本项目为 ZenTao MCP 服务器提供了一套完整的测试解决方案，包括： - ✅ **工具测试** - 直接API调用的功能测试 - ✅ **LLM评估测试** - 智能体交互的真实场景测试 - ✅ **规范符合性测试** - MCP协议标准合规验证 - ✅ **统一测试** - 集成测试和端到端验证 - ✅ **自动化脚本** - CI/CD集成的测试执行器 ## 🚀 快速开始 ### 1. 安装依赖 ```bash # 安装项目依赖 npm install # 安装MCP测试器 npm install -g @modelcontextprotocol/mcp-server-tester # 安装YAML解析器（用于配置验证） npm install --save-dev js-yaml ``` ### 2. 环境配置 ```bash # 复制环境变量模板 cp .env.example .env # 编辑环境变量 # ZENDTAO_BASE_URL=http://your-zentao-server # ZENDTAO_TOKEN=your-api-token # ANTHROPIC_API_KEY=your-claude-api-key # 用于LLM评估测试 ``` ### 3. 构建项目 ```bash # 构建 TypeScript 代码 npm run build # 验证配置文件 npm run test:validate-configs ``` ## 📁 项目结构 ``` zendao-mcp/ ├── tests/ │ ├── zendao-server-config.json # 服务器配置 │ ├── zendao-tool-tests.yaml # 工具测试配置 │ ├── zendao-eval-tests.yaml # LLM评估测试配置 │ ├── zendao-unified-tests.yaml # 统一测试配置 │ └── test-reports/ # 测试报告目录 ├── scripts/ │ ├── run-mcp-tests.js # 测试执行器 │ └── validate-test-configs.js # 配置验证器 ├── package.json # 项目配置 └── MCP_TESTING_COMPLETE.md # 本文档 ``` ## 🧪 测试类型详解 ### 1. 工具测试 (Tools Testing) **目的**: 验证工具的基本功能、参数验证和错误处理 **特点**: - ⚡ 快速执行（无需API密钥） - 🎯 直接API调用测试 - 🔍 参数验证测试 - ⚠️ 错误处理验证 **运行命令**: ```bash # 基础工具测试 npm run test:mcp:tools # 调试模式（详细输出） npm run test:mcp:debug ``` **测试覆盖**: - ✅ 基础功能测试（列出项目、获取项目详情、列出任务等） - ✅ 参数验证测试（无效参数、边界值等） - ✅ 错误处理测试（不存在的资源、权限错误等） - ✅ 工作流测试（多步骤操作、数据依赖等） - ✅ 批量操作测试（批量创建任务等） ### 2. LLM评估测试 (Evals Testing) **目的**: 验证LLM能够正确理解和使用禅道工具完成实际任务 **特点**: - 🤖 真实LLM交互测试 - 📊 智能评分系统 - 🎯 实际使用场景验证 - 📈 多模型支持 **环境要求**: ```bash export ANTHROPIC_API_KEY=your-claude-api-key ``` **运行命令**: ```bash # LLM评估测试 npm run test:mcp:evals ``` **测试场景**: - ✅ 工具发现和认知测试 - ✅ 项目管理工作流测试 - ✅ 复杂任务处理测试 - ✅ 错误恢复和容错测试 - ✅ 资源规划和优化测试 ### 3. 统一测试 (Unified Testing) **目的**: 集成工具测试和LLM评估测试的完整验证 **特点**: - 🔄 完整测试流程 - 📊 综合测试报告 - 🎯 端到端验证 - 📈 性能和可靠性测试 **运行命令**: ```bash # 统一测试 npm run test:mcp:unified ``` ### 4. 规范符合性测试 (Compliance Testing) **目的**: 验证MCP服务器符合协议规范 **特点**: - 📋 协议标准验证 - 🔍 最佳实践检查 - 📊 合规性评分 - 🚨 问题识别和建议 **运行命令**: ```bash # 合规性测试 npm run test:mcp:compliance ``` ### 5. 完整测试套件 (All Tests) **运行所有测试类型**: ```bash # 运行所有测试 npm run test:mcp # 等价命令 node scripts/run-mcp-tests.js all ``` ## 📊 测试配置详解 ### 服务器配置 (`zendao-server-config.json`) ```json { "mcpServers": { "zendao": { "command": "node", "args": ["dist/index.js"], "env": { "ZENDTAO_BASE_URL": "http://localhost:3000", "ZENDTAO_TOKEN": "test-token-for-testing", "NODE_ENV": "test" } } } } ``` ### 工具测试配置示例 ```yaml tools: expected_tool_list: - 'zendao_list_projects' - 'zendao_get_project' # ... 其他工具 tests: - name: 'List projects with pagination' tool: 'zendao_list_projects' params: page: 1 limit: 10 expect: success: true result: schema: type: object properties: projects: { type: array } total: { type: number } ``` ### LLM评估测试配置示例 ```yaml evals: models: - 'claude-3-5-haiku-latest' - 'claude-3-5-sonnet-latest' tests: - name: 'LLM can manage projects' prompt: | Create a new project called "Mobile App Development" with proper parameters and then list all projects to verify it was created. expected_tool_calls: required: ['zendao_create_project', 'zendao_list_projects'] response_scorers: - type: 'llm-judge' criteria: 'Did the assistant successfully create and verify the project?' threshold: 0.8 ``` ## 🎯 测试最佳实践 ### 1. 开发阶段测试流程 ```bash # 1. 构建项目 npm run build # 2. 验证配置 npm run test:validate-configs # 3. 运行快速工具测试 npm run test:mcp:tools # 4. 调试特定问题 npm run test:mcp:debug ``` ### 2. 发布前测试清单 ```bash # 1. 完整测试套件 npm run test:mcp # 2. 代码覆盖率测试 npm run test:coverage # 3. 规范合规性测试 npm run test:mcp:compliance # 4. 性能测试（如果需要） npm run test:performance ``` ### 3. CI/CD 集成 ```yaml # .github/workflows/test.yml name: MCP Server Tests on: [push, pull_request] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - uses: actions/setup-node@v3 with: node-version: '18' - name: Install dependencies run: npm ci - name: Build project run: npm run build - name: Validate configs run: npm run test:validate-configs - name: Run tools tests run: npm run test:mcp:tools - name: Run compliance tests run: npm run test:mcp:compliance - name: Upload test reports uses: actions/upload-artifact@v3 with: name: test-reports path: test-reports/ ``` ## 📈 测试报告和结果 ### 报告位置 所有测试报告都保存在 `test-reports/` 目录中： ``` test-reports/ ├── mcp-test-tools-2024-01-15T10-30-00-000Z.json ├── mcp-test-evals-2024-01-15T11-00-00-000Z.json ├── mcp-test-compliance-2024-01-15T11-30-00-000Z.json └── ... ``` ### 测试结果解读 #### 工具测试结果 ``` ✅ Tool Discovery: Found 7 tools ✅ List projects successfully ✅ Get project details ❌ Handle invalid parameters ✅ Update task status Results: 24/25 tests passed ``` #### LLM评估测试结果 ``` 🤖 Testing with claude-3-5-haiku-latest ✅ Project discovery workflow ✅ Task creation and management ❌ Complex analysis task: FAILED ✅ Error handling test Results: 6/8 tests passed ``` #### 合规性测试结果 ``` 🏥 MCP SERVER COMPLIANCE 📋 SPECIFICATION COMPLIANCE SUMMARY 🔍 BASE PROTOCOL: 4/5 passed 🔍 SERVER FEATURES: 12/15 passed 📊 OVERALL MCP COMPLIANCE: 85/100 ``` ## 🔧 故障排除 ### 常见问题 #### 1. MCP测试器未安装 ```bash ❌ mcp-server-tester 未安装 ✅ 请运行以下命令安装: npm install -g @modelcontextprotocol/mcp-server-tester ``` **解决方案**: ```bash # 全局安装 npm install -g @modelcontextprotocol/mcp-server-tester # 或使用npx npx @modelcontextprotocol/inspector ``` #### 2. 配置文件验证失败 ```bash ❌ 工具测试配置YAML解析失败 ✅ 检查YAML语法和缩进 ``` **解决方案**: - 使用在线YAML验证器检查语法 - 确保使用正确的缩进（空格，不是Tab） - 检查必需字段是否存在 #### 3. LLM评估测试失败 ```bash ❌ ANTHROPIC_API_KEY 环境变量未设置 ✅ 请设置有效的Claude API密钥 ``` **解决方案**: ```bash export ANTHROPIC_API_KEY=your-api-key-here npm run test:mcp:evals ``` #### 4. 服务器连接失败 ```bash ❌ 无法连接到禅道服务器 ✅ 请检查服务器配置和网络连接 ``` **解决方案**: - 验证 `ZENDTAO_BASE_URL` 和 `ZENDTAO_TOKEN` 配置 - 检查网络连接和防火墙设置 - 确认禅道服务器API可访问 #### 5. 构建失败 ```bash ❌ TypeScript编译错误 ✅ 请检查代码语法和类型定义 ``` **解决方案**: ```bash # 检查TypeScript错误 npm run build # 清理并重新构建 npm run clean && npm run build ``` ### 调试技巧 #### 启用调试模式 ```bash # 工具测试调试 npm run test:mcp:debug # LLM评估测试调试 ANTHROPIC_API_KEY=your-key node scripts/run-mcp-tests.js evals --debug ``` #### 查看详细日志 ```bash # MCP Inspector调试 npx @modelcontextprotocol/inspector node dist/index.js # 启用详细日志 NODE_ENV=development node dist/index.js ``` #### 单独测试特定配置 ```bash # 只运行工具测试 npx mcp-server-tester tools tests/zendao-tool-tests.yaml --server-config tests/zendao-server-config.json # 只运行评估测试 npx mcp-server-tester evals tests/zendao-eval-tests.yaml --server-config tests/zendao-server-config.json ``` ## 📚 参考资源 ### 官方文档 - [MCP服务器测试器文档](https://github.com/steviec/mcp-server-tester) - [MCP协议规范](https://modelcontextprotocol.io/) - [ZenTao API文档](https://www.zentao.net/api/) ### 相关工具 - [MCP Inspector](https://github.com/modelcontextprotocol/inspector) - [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) - [Jest测试框架](https://jestjs.io/) ### 最佳实践指南 - [MCP服务器开发指南](./MCP_TESTING_GUIDE.md) - [TypeScript测试最佳实践](https://basarat.gitbooks.io/testingtypescript/) - [API测试自动化](https://apitesting.com/) ## 🎉 总结 这个完整的测试方案为ZenTao MCP服务器提供了： ### 🛡️ 质量保障 - **全面覆盖**：工具功能、LLM交互、协议合规 - **自动化测试**：CI/CD集成的测试执行 - **详细报告**：可操作的测试结果和改进建议 ### 🚀 开发效率 - **快速反馈**：即时的测试结果和错误定位 - **调试支持**：详细的调试日志和工具 - **配置验证**：自动化的配置文件检查 ### 📊 企业级特性 - **多模型支持**：Claude、GPT等多种LLM测试 - **性能监控**：测试执行时间和资源使用 - **可扩展性**：易于添加新的测试场景 通过这套测试方案，你可以确保ZenTao MCP服务器在各种使用场景下都能稳定可靠地工作，为用户提供最佳的项目管理体验！ --- **立即开始测试**: ```bash # 1. 验证配置 npm run test:validate-configs # 2. 运行完整测试 npm run test:mcp # 3. 查看测试报告 ls test-reports/ ```