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