ZenTao MCP Server
一个基于 Model Context Protocol (MCP) 的服务器实现，用于让 LLM 能够操作禅道项目管理系统的 API。
✨ 核心功能
🔧 管理功能
- ✅ 项目管理：获取项目列表、创建项目、查询项目详情
- ✅ 任务管理：获取任务列表、创建任务、更新任务状态
- ✅ 批量操作：批量创建任务，提高操作效率
💡 技术特性
- 基于 TypeScript 开发，类型安全
- 智能 LRU 缓存机制，减少 API 调用
- 完善的错误处理和重试机制
- 支持并发控制和速率限制
- 完整的日志系统
🚀 快速开始
前置检查
- 禅道服务器正在运行 (
http://localhost) - 你有有效的禅道账号
- Node.js >= 16.0.0 已安装
安装依赖
npm install
构建项目
npm run build
获取 Token
详细指南: GETTING-TOKEN.md
# 快速获取（推荐）
bash fetch-token.sh
启动服务器
# Linux/Mac
./start-mcp.sh
# Windows
start-mcp.bat
启动成功标志:
[INFO] 启动 ZenTao MCP 服务器...
[INFO] 连接验证成功
[INFO] 禅道版本: 开源版 21.7
[INFO] MCP 服务器已启动，等待连接...
🧪 测试
运行测试
指南: TEST-REPORTS.md
# 运行所有测试
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 tests/run-all-tests.sh # 运行所有测试
Token 管理
bash fetch-token.sh # 自动获取 Token
./update-token.sh # 手动更新 Token
./diagnose-token.sh # 诊断 Token 问题
开发脚本
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 fetch-token.sh
npm run build
详细指南: GETTING-TOKEN.md
构建失败
现象: TypeScript 编译错误
解决:
npm run clean
npm run build
测试失败
现象: 测试用例失败
解决: 查看 TEST-REPORTS.md
npm run test:startup # 先运行启动测试
📊 质量指标
代码质量
- ✅ TypeScript 类型安全
- ✅ 完整的错误处理
- ✅ 单元测试覆盖
- ✅ 并发安全保证
测试覆盖
- 语句覆盖率: 38.06%
- 分支覆盖率: 19.14%
- 函数覆盖率: 41.50%
- 缓存模块: 88.88%
目标: 90% 语句覆盖率
性能指标
- ✅ 缓存命中率优化
- ✅ 并发处理 (20 请求)
- ✅ 响应时间 < 100ms
- ✅ 内存使用合理
🤝 贡献指南
提交代码
- Fork 项目
- 创建功能分支
- 编写测试
- 运行测试:
npm test - 提交 PR
代码审查
- 所有测试通过
- 代码遵循规范
- 包含必要注释
- 更新相关文档
📄 许可证
ISC
🔗 相关链接
维护者: Claude Code
版本: v1.0.0
最后更新: 2025-11-02