zendao-mcp

godlewis/zendao-mcp

3.2

If you are the rightful owner of zendao-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

ZenTao MCP Server is a Model Context Protocol (MCP) server implementation that allows LLM to interact with the ZenTao project management system's API.

Tools
7
Resources
0
Prompts
0

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

详细指南: 

# 快速获取（推荐）
bash fetch-token.sh

启动服务器

# Linux/Mac
./start-mcp.sh

# Windows
start-mcp.bat

启动成功标志:

[INFO] 启动 ZenTao MCP 服务器...
[INFO] 连接验证成功
[INFO] 禅道版本: 开源版 21.7
[INFO] MCP 服务器已启动，等待连接...

🧪 测试

运行测试

指南: 

# 运行所有测试
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.mdToken 获取和管理指南
TEST-REPORTS.md测试报告汇总

MCP 配置

文档说明
CODEX-MCP-CONFIG.mdCodex MCP 配置说明
codex-mcp-config-template.json配置文件模板

项目配置

文件说明
AGENTS.mdOpenSpec 指令
CLAUDE.mdClaude 项目指令
jest.config.jsJest 测试配置
.env.example环境变量示例
tsconfig.jsonTypeScript 配置

🛠️ 可用脚本

测试脚本

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

详细指南:

构建失败

现象: TypeScript 编译错误
解决:

npm run clean
npm run build

测试失败

现象: 测试用例失败
解决: 查看 

npm run test:startup  # 先运行启动测试

📊 质量指标

代码质量

  • ✅ TypeScript 类型安全
  • ✅ 完整的错误处理
  • ✅ 单元测试覆盖
  • ✅ 并发安全保证

测试覆盖

  • 语句覆盖率: 38.06%
  • 分支覆盖率: 19.14%
  • 函数覆盖率: 41.50%
  • 缓存模块: 88.88%

目标: 90% 语句覆盖率

性能指标

  • ✅ 缓存命中率优化
  • ✅ 并发处理 (20 请求)
  • ✅ 响应时间 < 100ms
  • ✅ 内存使用合理

🤝 贡献指南

提交代码

  1. Fork 项目
  2. 创建功能分支
  3. 编写测试
  4. 运行测试: npm test
  5. 提交 PR

代码审查

  • 所有测试通过
  • 代码遵循规范
  • 包含必要注释
  • 更新相关文档

📄 许可证

ISC

🔗 相关链接

维护者: Claude Code
版本: v1.0.0
最后更新: 2025-11-02