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