# 禅道MCP

**Repository Path**: umegame/zentao-mcp

## Basic Information

- **Project Name**: 禅道MCP
- **Description**: 基于 Model Context Protocol (MCP) 的禅道项目管理系统 API 封装服务，使 AI 助手能够与禅道系统进行交互。
- **Primary Language**: Python
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 6
- **Forks**: 1
- **Created**: 2025-12-02
- **Last Updated**: 2025-12-11

## Categories & Tags

**Categories**: MCP

**Tags**: None

## README

# 禅道MCP Server

[![Version](https://img.shields.io/badge/version-1.4.0-blue.svg)](https://gitee.com/umegame/zentao-mcp)
[![Python](https://img.shields.io/badge/python-3.13+-green.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)

基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的禅道项目管理系统 API 封装服务，使 AI 助手能够与禅道系统进行交互。

## 目录

- [功能特性](#功能特性)
- [系统要求](#系统要求)
- [用户指南](#用户指南)
  - [部署](#一部署)
  - [使用](#二使用)
- [开发者指南](#开发者指南)
- [配置说明](#配置说明)
- [使用示例](#使用示例)
- [常见问题](#常见问题)
- [版本迁移](#版本迁移)
- [贡献指南](#贡献指南)
- [许可证](#许可证)

## 功能特性

- 🔐 **安全认证** - 支持禅道 Token 认证，自动刷新
- 📦 **产品管理** - 获取产品列表、产品详情
- 📋 **需求管理** - 获取需求层级结构、创建/变更/修改需求
- 📁 **模块管理** - 获取/创建/编辑产品模块
- 🚀 **项目管理** - 获取项目和迭代信息
- ✅ **任务管理** - 获取任务列表、创建任务
- 📝 **模板支持** - 提供需求和任务创建模板
- 📊 **日志记录** - 支持文件日志和日志轮转
- 🟢 **健康检查** - 提供服务状态检查工具
- ⚡ **缓存机制** - API 响应缓存，减少重复请求

## 系统要求

| 依赖 | 版本要求 | 说明 |
|------|----------|------|
| Python | 3.13+ | |
| 禅道 | 21.0+ | 需开启 API 功能、开启敏捷开发模式、启用三级需求（史诗/特性/故事） |
| uv | 最新版 | 推荐使用（或 pip） |

---

## 用户指南

本节面向使用禅道MCP Server的用户，介绍如何部署和使用。

### 一、部署

#### 开发环境部署

适用于本地开发、测试场景。

**1. 安装 uv（如未安装）**

```bash
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**2. 获取项目**

```bash
git clone https://gitee.com/umegame/zentao-mcp.git
cd zentao-mcp
uv sync --all-extras
```

**3. 配置环境变量**

```bash
cp .env.example .env
# 编辑 .env 文件，填入禅道服务器信息
```

**4. 启动服务器**

```bash
# Windows
start.bat

# macOS / Linux
./start.sh
```

服务器启动后监听 `http://localhost:8000/sse`。

#### 生产环境部署

##### 方式一：克隆完整项目

与开发环境部署方式相同，适用于可访问 Git 仓库的服务器。

##### 方式二：Docker 离线部署（推荐）

适用于无法访问外网或需要统一镜像分发的场景。

**步骤1：构建并导出镜像（开发机执行）**

```bash
# 克隆仓库
git clone https://gitee.com/umegame/zentao-mcp.git
cd zentao-mcp

# 构建镜像
docker-compose build

# 导出镜像文件
docker save zentao-mcp:1.4.0 -o zentao-mcp-1.4.0.tar
```

> Windows 用户需在 WSL2 中执行上述命令。

**步骤2：导入镜像（生产机执行）**

将 `zentao-mcp-1.4.0.tar` 传输到生产服务器后：

```bash
docker load -i zentao-mcp-1.4.0.tar
```

**步骤3：运行容器**

*方式 A：docker run*

```bash
docker run -d \
  --name zentao-mcp \
  -p 8000:8000 \
  -e ZENTAO_URL=http://your-zentao-server \
  -e ZENTAO_ACCOUNT=admin \
  -e ZENTAO_PASSWORD=your-password \
  --restart unless-stopped \
  zentao-mcp:1.4.0
```

*方式 B：docker-compose（推荐）*

创建 `docker-compose.yml`：

```yaml
version: '3.8'
services:
  zentao-mcp:
    image: zentao-mcp:1.4.0
    container_name: zentao-mcp
    ports:
      - "8000:8000"
    env_file: .env              # 或使用 environment 直接配置
    restart: unless-stopped
```

创建 `.env` 文件：

```bash
ZENTAO_URL=http://your-zentao-server
ZENTAO_ACCOUNT=admin
ZENTAO_PASSWORD=your-password
```

启动：`docker-compose up -d`

**⚠️ 网络配置注意事项**

如果禅道也运行在 Docker 中，需注意网络配置：

- **ZENTAO_URL 应使用容器内部地址**，而非宿主机映射端口
- 例如：禅道容器 IP 为 `172.18.0.5`，内部端口为 `80`，则配置：
  ```bash
  ZENTAO_URL=http://172.18.0.5:80   # ✅ 正确
  ZENTAO_URL=http://172.18.0.5:9001 # ❌ 错误（9001 是宿主机端口）
  ```

如需加入已有 Docker 网络并指定固定 IP：

```yaml
version: '3.8'
services:
  zentao-mcp:
    image: zentao-mcp:1.4.0
    container_name: zentao-mcp
    ports:
      - "8000:8000"
    env_file: .env
    restart: unless-stopped
    networks:
      your-network:
        ipv4_address: 172.18.0.10

networks:
  your-network:
    external: true
```

**Docker 常用命令**

```bash
docker ps                    # 查看运行中的容器
docker logs zentao-mcp       # 查看日志
docker restart zentao-mcp    # 重启容器
docker stop zentao-mcp       # 停止容器
```

### 二、使用

部署完成后，配置 MCP 客户端即可使用。

#### 配置 MCP 客户端

编辑 MCP 配置文件（Claude Desktop、Windsurf、Cursor 等支持 HTTP 方式连接 MCP 服务器的客户端）：

```json
{
  "mcpServers": {
    "zentao-mcp": {
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

> ⚠️ **v1.4.0 变更**：配置字段从 `serverUrl` 改为 `url`，端点从 `/sse` 改为 `/mcp`

> **注意**：
> - 如服务部署在远程服务器，请将 `localhost` 替换为服务器 IP
> - 如修改了端口映射，请相应修改 URL 中的端口号

---

## 开发者指南

本节面向开发者，介绍开发环境设置、项目结构、API 接口、测试和构建。

### 开发环境设置

```bash
# 克隆仓库
git clone https://gitee.com/umegame/zentao-mcp.git
cd zentao-mcp

# 安装依赖（包括开发依赖）
uv sync --all-extras

# 配置环境变量
cp .env.example .env
# 编辑 .env 填入真实配置

# 本地运行
start.bat      # Windows CMD
.\start.ps1    # Windows PowerShell
./start.sh     # macOS / Linux

# 或直接使用 uv
uv run python -m zentao_mcp
```

### 项目结构

```
zentao-mcp/
├── src/zentao_mcp/
│   ├── __init__.py       # 包初始化
│   ├── __main__.py       # 程序入口
│   ├── config.py         # 配置管理
│   ├── logging_config.py # 日志配置
│   ├── exceptions.py     # 异常定义
│   ├── client/           # API 客户端模块（v1.4.0 拆分）
│   │   ├── __init__.py   # 导出接口
│   │   ├── base.py       # 基础客户端
│   │   └── api.py        # API 封装
│   ├── server.py         # MCP 服务器
│   └── tools/            # MCP 工具（19个）
│       ├── products.py   # 产品工具
│       ├── projects.py   # 项目工具
│       ├── requirements.py # 需求工具
│       ├── tasks.py      # 任务工具
│       ├── modules.py    # 模块工具
│       ├── templates.py  # 模板工具
│       └── health.py     # 健康检查/重连工具
├── tests/                # 测试代码
├── docs/                 # 项目文档
├── .env.example          # 环境变量示例
├── pyproject.toml        # 项目配置
└── README.md             # 项目说明
```

### API 接口

#### 产品工具

| 工具名 | 说明 | 参数 |
|--------|------|------|
| `get_products` | 获取所有产品列表 | 无 |
| `get_product` | 获取产品详情 | `product_id` 或 `product_name` |

#### 项目工具

| 工具名 | 说明 | 参数 |
|--------|------|------|
| `get_active_projects` | 获取进行中的项目 | 无 |
| `get_active_executions` | 获取进行中的迭代 | `project_id`（可选） |

#### 需求工具

| 工具名 | 说明 | 参数 |
|--------|------|------|
| `get_product_requirements` | 获取产品需求（分层） | `product_id` |
| `get_requirement_detail` | 获取需求详情 | `requirement_id`, `requirement_type`, `product_id` |
| `create_requirement` | 创建需求 | `product_id`, `title`, `category`, ... |
| `change_requirement` | 变更需求内容（生成新版本） | `story_id`, `title`, `spec`, `verify` |
| `update_requirement` | 修改需求属性（不生成新版本） | `product_id`, `requirement_id`, `pri`, `estimate`, ... |

#### 任务工具

| 工具名 | 说明 | 参数 |
|--------|------|------|
| `get_execution_tasks` | 获取迭代任务列表 | `execution_id` |
| `get_task_detail` | 获取任务详情 | `task_id` |
| `create_task` | 创建任务 | `execution_id`, `name`, `est_started`, `deadline`, ... |

#### 模块工具

| 工具名 | 说明 | 参数 |
|--------|------|------|
| `get_product_modules` | 获取产品模块树 | `product_id` |
| `create_product_module` | 创建产品模块 | `product_id`, `name`, `parent_id` |
| `update_product_module` | 编辑产品模块 | `module_id`, `name`, `parent_id` |

#### 模板工具

| 工具名 | 说明 | 参数 |
|--------|------|------|
| `get_task_template` | 获取任务创建模板 | 无 |
| `get_requirement_template` | 获取需求创建模板 | 无 |

#### 系统工具

| 工具名 | 说明 | 参数 |
|--------|------|------|
| `health_check` | 检查服务健康状态 | 无 |
| `reconnect` | 手动重连禅道服务 | 无 |

`health_check` 返回示例：

```json
{
  "status": "healthy",
  "version": "1.4.0",
  "zentao_connected": true,
  "timestamp": "2025-12-04T20:00:00"
}
```

### 测试

```bash
# 运行所有单元测试
uv run pytest tests/ -v

# 运行端到端测试（需要配置真实禅道服务器）
uv run pytest tests/test_e2e.py -v -m e2e

# 查看测试覆盖率
uv run pytest tests/ --cov=zentao_mcp --cov-report=html
```

### 构建 Docker 镜像

**Linux / macOS：**

```bash
# 构建镜像
docker-compose build

# 导出镜像（用于离线分发）
docker save zentao-mcp:1.4.0 -o zentao-mcp-1.4.0.tar
```

**Windows（需要 WSL2）：**

```powershell
# 安装 WSL2 和 Ubuntu
wsl --install -d Ubuntu
wsl
# 在 Ubuntu 中执行上述 Linux 命令
```

---

## 配置说明

### 环境变量

#### 必填配置

| 变量名 | 说明 | 示例 |
|--------|------|------|
| `ZENTAO_URL` | 禅道服务器地址 | `http://zentao.example.com` |
| `ZENTAO_ACCOUNT` | 登录账号 | `admin` |
| `ZENTAO_PASSWORD` | 登录密码 | `your-password` |

#### 可选配置

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `ZENTAO_TIMEOUT` | 请求超时时间（秒） | `30` |
| `ZENTAO_SSL_VERIFY` | 是否验证 SSL 证书 | `true` |

#### SSE 服务器配置

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `ZENTAO_SSE_PORT` | SSE 服务器监听端口 | `8000` |
| `ZENTAO_SSE_HOST` | SSE 服务器监听地址 | `0.0.0.0` |

#### 日志配置

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `ZENTAO_LOG_ENABLED` | 是否启用文件日志 | `true` |
| `ZENTAO_LOG_FILE` | 日志文件路径 | `logs/zentao-mcp.log` |
| `ZENTAO_LOG_LEVEL` | 日志级别 | `INFO` |
| `ZENTAO_LOG_MAX_SIZE` | 单个日志文件最大字节数 | `10485760` (10MB) |
| `ZENTAO_LOG_BACKUP_COUNT` | 日志文件保留数量 | `5` |

---

## 使用示例

### 通过 AI 助手使用

确保服务器已启动，然后直接与 AI 对话：

```
用户: 获取所有产品列表
AI: [调用 get_products 工具]

用户: 查看产品"测试产品"的详情
AI: [调用 get_product 工具，参数 product_name="测试产品"]

用户: 获取该产品的所有需求
AI: [调用 get_product_requirements 工具，参数 product_id=6]

用户: 创建一个新的用户故事需求
AI: [调用 create_requirement 工具]
```

---

## 常见问题

### Docker 容器无法连接禅道服务器

**问题**：容器启动正常，但调用工具时报错 `Connection refused`。

**原因**：`ZENTAO_URL` 配置了宿主机映射端口，而非容器内部端口。

**解决**：
```bash
# ❌ 错误：使用宿主机端口
ZENTAO_URL=http://172.18.0.5:9001

# ✅ 正确：使用容器内部端口
ZENTAO_URL=http://172.18.0.5:80
```

### 认证失败

**问题**：调用工具时报错 `认证失败`。

**排查步骤**：
1. 确认 `ZENTAO_URL`、`ZENTAO_ACCOUNT`、`ZENTAO_PASSWORD` 配置正确
2. 确认禅道已开启 API 功能（后台 → 二次开发 → 应用）
3. 确认账号有相应权限
4. 使用 `health_check` 工具测试连接

### MCP 客户端连接失败

**问题**：客户端报错无法连接到 MCP 服务器。

**排查步骤**：
1. 确认服务器已启动（`http://localhost:8000/mcp` 可访问）
2. 确认 `url` 配置正确（v1.4.0+ 使用 `url` 而非 `serverUrl`）
3. 如使用 Docker，确认端口映射正确
4. 检查防火墙是否放行端口

### Docker 镜像构建失败

**问题**：执行 `docker-compose build` 时报错。

**常见原因及解决**：
- **网络问题**：配置 Docker 镜像加速器
  ```bash
  # /etc/docker/daemon.json
  { "registry-mirrors": ["https://docker.1ms.run"] }
  ```
- **权限问题**：使用 `sudo` 执行命令
- **WSL2 问题**：确保 Docker Desktop 已启用 WSL2 集成

---

## 版本迁移

### 从 v1.1.0 升级到 v1.2.0

v1.2.0 将传输层从 STDIO 切换到 SSE，配置方式有重大变化：

| 项目 | v1.1.0 (STDIO) | v1.2.0~v1.3.x (SSE) | v1.4.0+ (HTTP) |
|------|----------------|---------------------|----------------|
| 服务器启动 | MCP 客户端自动启动 | 需手动启动服务器 | 需手动启动服务器 |
| 客户端配置 | `command` + `args` + `env` | `serverUrl` | `url` |
| 端点 | - | `/sse` | `/mcp` |
| 环境变量 | MCP 配置文件中 | 服务器端 `.env` 文件 | 服务器端 `.env` 文件 |

**旧配置（v1.1.0，已弃用）：**

```json
{
  "mcpServers": {
    "zentao-mcp": {
      "command": "python",
      "args": ["-u", "-m", "zentao_mcp"],
      "env": { "ZENTAO_URL": "...", "...": "..." }
    }
  }
}
```

**v1.2.0~v1.3.x 配置（SSE）：**

```json
{
  "mcpServers": {
    "zentao-mcp": {
      "serverUrl": "http://localhost:8000/sse"
    }
  }
}
```

**v1.4.0+ 配置（HTTP，推荐）：**

```json
{
  "mcpServers": {
    "zentao-mcp": {
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

---

## 贡献指南

欢迎贡献代码！请遵循以下流程：

### 提交 PR

1. Fork 本仓库
2. 创建特性分支：`git checkout -b feature/your-feature`
3. 提交更改：`git commit -m "feat: 添加新功能"`
4. 推送分支：`git push origin feature/your-feature`
5. 创建 Pull Request

### 提交规范

提交信息请遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范：

| 类型 | 说明 |
|------|------|
| `feat` | 新功能 |
| `fix` | Bug 修复 |
| `docs` | 文档更新 |
| `refactor` | 代码重构 |
| `test` | 测试相关 |
| `chore` | 构建/工具相关 |

### 开发规范

- 代码风格遵循 PEP 8
- 新功能需编写单元测试
- 确保所有测试通过：`uv run pytest tests/ -v`

---

## 许可证

MIT License

## 作者

梁铭显 <2655050@qq.com>