# ZenTao MCP Server

一个基于 Model Context Protocol (MCP) 的服务器实现，用于让 LLM 能够操作禅道项目管理系统的 API。

## ✨ 核心功能

### 🔧 管理功能
- ✅ **项目管理**：获取项目列表、创建项目、查询项目详情
- ✅ **任务管理**：获取任务列表、创建任务、更新任务状态
- ✅ **批量操作**：批量创建任务，提高操作效率

### 💡 技术特性
- 基于 TypeScript 开发，类型安全
- 智能 LRU 缓存机制，减少 API 调用
- 完善的错误处理和重试机制
- 支持并发控制和速率限制
- 完整的日志系统

---

## 🚀 快速开始

### 前置检查
- [ ] 禅道服务器正在运行 (`http://localhost`)
- [ ] 你有有效的禅道账号
- [ ] Node.js >= 16.0.0 已安装

### 安装依赖
```bash
npm install
```

### 构建项目
```bash
npm run build
```

### 获取 Token
**详细指南**: [`GETTING-TOKEN.md`](GETTING-TOKEN.md)

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

### 启动服务器
```bash
# Linux/Mac
./start-mcp.sh

# Windows
start-mcp.bat
```

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

---

## 🧪 测试

### 运行测试
**指南**: [`TEST-REPORTS.md`](TEST-REPORTS.md)

```bash
# 运行所有测试
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
bash tests/run-all-tests.sh  # 运行所有测试
```

### Token 管理
```bash
bash fetch-token.sh          # 自动获取 Token
./update-token.sh            # 手动更新 Token
./diagnose-token.sh          # 诊断 Token 问题
```

### 开发脚本
```bash
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
bash fetch-token.sh
npm run build
```

详细指南: [`GETTING-TOKEN.md`](GETTING-TOKEN.md)

### 构建失败
**现象**: TypeScript 编译错误  
**解决**: 
```bash
npm run clean
npm run build
```

### 测试失败
**现象**: 测试用例失败  
**解决**: 查看 [`TEST-REPORTS.md`](TEST-REPORTS.md)
```bash
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

---

## 🔗 相关链接

- [MCP 协议](https://modelcontextprotocol.io/)
- [禅道 API 文档](https://www.zentao.net/book/zentao_help/book/zentao_api.html)
- [Jest 测试框架](https://jestjs.io/)
- [TypeScript 文档](https://www.typescriptlang.org/)

---

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