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````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````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`
### 构建失败
**现象**: TypeScript 编译错误
**解决**:```bash
npm run clean
npm run build
测试失败
现象: 测试用例失败
解决: 查看 `TEST-REPORTS.md`bash
npm run test:startup # 先运行启动测试
📊 质量指标
代码质量
- ✅ TypeScript 类型安全
- ✅ 完整的错误处理
- ✅ 单元测试覆盖
- ✅ 并发安全保证
测试覆盖
- 语句覆盖率: 38.06%
- 分支覆盖率: 19.14%
- 函数覆盖率: 41.50%
- 缓存模块: 88.88%
目标: 90% 语句覆盖率
性能指标
- ✅ 缓存命中率优化
- ✅ 并发处理 (20 请求)
- ✅ 响应时间 < 100ms
- ✅ 内存使用合理
🤝 贡献指南
提交代码
- Fork 项目
- 创建功能分支
- 编写测试
- 运行测试:
npm test - 提交 PR
代码审查
- [ ] 所有测试通过
- [ ] 代码遵循规范
- [ ] 包含必要注释
- [ ] 更新相关文档
📄 许可证
ISC
🔗 相关链接
- MCP 协议
- 禅道 API 文档
- Jest 测试框架
- TypeScript 文档
维护者: Claude Code
版本: v1.0.0
最后更新: 2025-11-02