How do I use ZenTao MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ZenTao MCP Server show me all open tasks assigned to me in project 123" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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