ZenTao MCP Server

# ZenTao MCP Server 一个基于 Model Context Protocol (MCP) 的服务器实现，用于让 LLM 能够操作禅道项目管理系统的 API。 ## ✨ 核心功能 ### 🔧 管理功能 - ✅ **项目管理**：获取项目列表、创建项目、查询项目详情 - ✅ **任务管理**：获取任务列表、创建任务、更新任务状态 - ✅ **批量操作**：批量创建任务，提高操作效率 ### 💡 技术特性 - 基于 TypeScript 开发，类型安全 - 智能 LRU 缓存机制，减少 API 调用 - 完善的错误处理和重试机制 - 支持并发控制和速率限制 - 完整的日志系统 --- ## 🚀 快速开始 ### 前置检查 - [ ] 禅道服务器正在运行 (`http://localhost`) - [ ] 你有有效的禅道账号 - [ ] Node.js >= 16.0.0 已安装 ### 安装依赖 ```bash npm install ``` ### 构建项目 ```bash npm run build ``` ### 获取 Token **详细指南**: [`GETTING-TOKEN.md`](GETTING-TOKEN.md) ```bash # 快速获取（推荐） bash fetch-token.sh ``` ### 启动服务器 ```bash # Linux/Mac ./start-mcp.sh # Windows start-mcp.bat ``` **启动成功标志**: ``` [INFO] 启动 ZenTao MCP 服务器... [INFO] 连接验证成功 [INFO] 禅道版本: 开源版 21.7 [INFO] MCP 服务器已启动，等待连接... ``` --- ## 🧪 测试 ### 运行测试 **指南**: [`TEST-REPORTS.md`](TEST-REPORTS.md) ```bash # 运行所有测试 npm test # 分模块测试 npm run test:startup # 启动测试 npm run test:tools # 工具测试 npm run test:errors # 错误处理测试 npm run test:performance # 性能测试 # 生成覆盖率报告 npm run test:coverage ``` ### 测试统计 - **总测试用例**: 31 - **通过率**: 83.9% (26/31) - **完全覆盖的工具**: get_tasks - **缓存系统**: 88.88% 覆盖率 --- ## 📚 文档导航 ### 核心文档 | 文档 | 说明 | |------|------| | `README.md` | 本文档，项目总览 | | `GETTING-TOKEN.md` | Token 获取和管理指南 | | `TEST-REPORTS.md` | 测试报告汇总 | ### MCP 配置 | 文档 | 说明 | |------|------| | `CODEX-MCP-CONFIG.md` | Codex MCP 配置说明 | | `codex-mcp-config-template.json` | 配置文件模板 | ### 项目配置 | 文件 | 说明 | |------|------| | `AGENTS.md` | OpenSpec 指令 | | `CLAUDE.md` | Claude 项目指令 | | `jest.config.js` | Jest 测试配置 | | `.env.example` | 环境变量示例 | | `tsconfig.json` | TypeScript 配置 | --- ## 🛠️ 可用脚本 ### 测试脚本 ```bash bash tests/run-all-tests.sh # 运行所有测试 ``` ### Token 管理 ```bash bash fetch-token.sh # 自动获取 Token ./update-token.sh # 手动更新 Token ./diagnose-token.sh # 诊断 Token 问题 ``` ### 开发脚本 ```bash npm run build # 构建项目 npm run dev # 开发模式运行 npm run test:watch # 监视模式运行测试 npm run test:clean # 清理测试结果 ``` --- ## 🏗️ 项目结构 ``` zendao-mcp/ ├── src/ # 源代码 │ ├── tools/ # MCP 工具实现 │ │ ├── getTasks.ts # ✅ 已测试 │ │ ├── getProjects.ts │ │ ├── createProject.ts │ │ ├── createTask.ts │ │ ├── updateTaskStatus.ts │ │ ├── getProjectById.ts │ │ └── batchCreateTasks.ts │ ├── client.ts # API 客户端 │ ├── config.ts # 配置管理 │ ├── types.ts # 类型定义 │ └── utils/ # 工具函数 │ ├── cache.ts # LRU 缓存 │ └── logger.ts # 日志系统 ├── tests/ # 测试文件 │ ├── *.test.ts # 测试用例 │ ├── helpers/ # 测试辅助 │ └── README.md # 测试指南 ├── dist/ # 构建输出 ├── docs/ # 文档 └── *.md # 项目文档 ``` --- ## 🔌 API 工具 ### ✅ 已验证工具 - **`get_tasks`** - 获取任务列表 - 支持分页：`page`, `limit` - 支持过滤：`projectId`, `status`, `assignedTo` - 缓存：5分钟 TTL，最多100项 ### 🔄 受限工具（需Token） 以下工具代码完整，但需要有效的Token才能测试： - `get_projects` - 获取项目列表 - `get_project_by_id` - 获取项目详情 - `create_project` - 创建项目 - `create_task` - 创建任务 - `update_task_status` - 更新任务状态 - `batch_create_tasks` - 批量创建任务 --- ## 🐛 故障排除 ### Token 问题 **现象**: 401 Unauthorized 错误 **解决**: Token 已过期，重新获取 ```bash bash fetch-token.sh npm run build ``` 详细指南: [`GETTING-TOKEN.md`](GETTING-TOKEN.md) ### 构建失败 **现象**: TypeScript 编译错误 **解决**: ```bash npm run clean npm run build ``` ### 测试失败 **现象**: 测试用例失败 **解决**: 查看 [`TEST-REPORTS.md`](TEST-REPORTS.md) ```bash npm run test:startup # 先运行启动测试 ``` --- ## 📊 质量指标 ### 代码质量 - ✅ TypeScript 类型安全 - ✅ 完整的错误处理 - ✅ 单元测试覆盖 - ✅ 并发安全保证 ### 测试覆盖 - **语句覆盖率**: 38.06% - **分支覆盖率**: 19.14% - **函数覆盖率**: 41.50% - **缓存模块**: 88.88% *目标: 90% 语句覆盖率* ### 性能指标 - ✅ 缓存命中率优化 - ✅ 并发处理 (20 请求) - ✅ 响应时间 < 100ms - ✅ 内存使用合理 --- ## 🤝 贡献指南 ### 提交代码 1. Fork 项目 2. 创建功能分支 3. 编写测试 4. 运行测试: `npm test` 5. 提交 PR ### 代码审查 - [ ] 所有测试通过 - [ ] 代码遵循规范 - [ ] 包含必要注释 - [ ] 更新相关文档 --- ## 📄 许可证 ISC --- ## 🔗 相关链接 - [MCP 协议](https://modelcontextprotocol.io/) - [禅道 API 文档](https://www.zentao.net/book/zentao_help/book/zentao_api.html) - [Jest 测试框架](https://jestjs.io/) - [TypeScript 文档](https://www.typescriptlang.org/) --- **维护者**: Claude Code **版本**: v1.0.0 **最后更新**: 2025-11-02