# ZenTao User MCP (Python)

一个用 Python 实现的禅道用户管理 MCP 服务。项目通过禅道 API v1 提供 Token 获取、当前用户查询、用户列表查询，以及用户的创建、更新和删除能力；可使用 stdio 或 Streamable HTTP 两种传输方式。

> [!WARNING]
> 本项目包含创建、更新和删除禅道用户的工具。HTTP 模式没有内置身份认证，默认仅监听 `127.0.0.1`；不要把服务直接暴露到公网。Token 会作为工具调用内容进入 MCP 客户端或模型上下文，只连接你信任的客户端与模型服务。

## 功能

| MCP 工具 | 说明 | 必填参数 |
| --- | --- | --- |
| `zentao_get_token` | 使用服务端环境变量中的账号和密码获取 Token | 无 |
| `zentao_user_me` | 获取当前 Token 对应的用户信息 | `token` |
| `zentao_user_get` | 按用户 ID 查询详情 | `token`, `userId` |
| `zentao_user_list` | 分页查询用户列表 | `token` |
| `zentao_user_create` | 创建用户 | `token`, `account`, `password` |
| `zentao_user_update` | 更新用户资料 | `token`, `userId`，以及至少一个可更新字段 |
| `zentao_user_delete` | 删除用户 | `token`, `userId` |

`zentao_user_list` 可选参数为 `page` 和 `limit`；创建与更新工具的完整参数可由 MCP 客户端自动读取。调用写操作前，请先确认所连接的禅道环境和用户 ID。

## 环境要求

- Python 3.10 或更高版本（推荐 Python 3.12）
- 可访问的禅道实例，并已启用 API v1
- 禅道账号具有相应的用户读取或管理权限
- 仅运行可选示例时需要 Node.js/npm 和对应的大模型 API Key

## 快速开始

### 1. 创建虚拟环境并安装依赖

Windows PowerShell：

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
```

macOS/Linux：

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
```

### 2. 配置禅道连接

复制示例配置：

```powershell
Copy-Item .env.example .env
```

macOS/Linux 使用：

```bash
cp .env.example .env
```

然后编辑 `.env`：

```dotenv
ZENTAO_URL=https://zentao.example.com
ZENTAO_ACCOUNT=admin
ZENTAO_PASSWORD=change-me
```

`ZENTAO_URL` 支持以下形式：

- `https://zentao.example.com`
- `https://zentao.example.com/zentao`
- `https://zentao.example.com/zentao/api.php/v1`

程序会将前两种形式自动规范化为 API v1 地址。`.env` 已被 Git 忽略，请勿把真实账号、密码或 API Key 写入 README、源码或提交记录。

## stdio 模式

stdio 服务端通常由 Codex、Claude Desktop 等 MCP 客户端启动，无需提前在终端中单独运行。
在支持 MCP 的客户端中添加以下配置，并将路径替换为本机绝对路径：

```json
{
  "mcpServers": {
    "zentao": {
      "command": "C:\\absolute\\path\\zentao-user-mcp-python\\.venv\\Scripts\\python.exe",
      "args": ["-m", "zentao.zentao_server_stdio"],
      "cwd": "C:\\absolute\\path\\zentao-user-mcp-python"
    }
  }
}
```

macOS/Linux 将 `command` 改为虚拟环境中的 `.venv/bin/python`，并把 `cwd` 设为项目根目录。服务始终从项目根目录加载 `.env`。

## Streamable HTTP 模式

从项目根目录启动服务：

```powershell
python -m zentao.zentao_server_http
```

默认端点为 `http://127.0.0.1:8000/mcp`。支持通过环境变量修改监听地址和端口：

```dotenv
MCP_HOST=127.0.0.1
MCP_PORT=8000
```

HTTP 模式没有应用层鉴权。如果确实需要跨机器访问，应部署在可信网络内，并在前置网关配置 TLS、身份认证和访问控制；不要直接使用 `0.0.0.0` 裸露到公网。

## 客户端示例

客户端示例使用 LangChain 和大模型，不是运行 MCP 服务端所必需。先安装可选依赖：

```powershell
python -m pip install -r requirements-examples.txt
```

### 禅道 stdio 客户端

从项目根目录运行：

```powershell
python -m zentao.zentao_client_stdio
```

该客户端会自动启动 `zentao.zentao_server_stdio` 子进程，不要再单独启动 stdio 服务端。

### 禅道 HTTP 客户端

先按上一节启动 HTTP 服务端，再在另一个终端运行：

```powershell
python -m zentao.zentao_client_http
```

客户端默认连接 `http://127.0.0.1:8000/mcp`，可通过 `ZENTAO_MCP_URL` 修改地址。

### 其他示例

- `example_amap_client_http.py`：连接远程高德 MCP 服务，需要 `AMAP_API_KEY`。
- `example_playwright_client_stdio.py`：通过 stdio 启动 Playwright MCP，需要 Node.js/npm。

这些客户端还需要在 `.env` 中配置各自使用的大模型 API Key。

## 项目结构

```text
.
|-- zentao/
|   |-- __init__.py
|   |-- client.py                         # 禅道 REST API 客户端，不是 MCP 客户端
|   |-- zentao_server_stdio.py           # 禅道 MCP 服务端（stdio）
|   |-- zentao_client_stdio.py           # 禅道 MCP 客户端示例（stdio）
|   |-- zentao_server_http.py            # 禅道 MCP 服务端（Streamable HTTP）
|   `-- zentao_client_http.py            # 禅道 MCP 客户端示例（Streamable HTTP）
|-- example_amap_client_http.py           # 高德 MCP HTTP 客户端示例
|-- example_playwright_client_stdio.py    # Playwright MCP stdio 客户端示例
|-- tests/
|   `-- test_client.py                    # 禅道 REST API 客户端单元测试
|-- requirements.txt                      # 核心服务依赖
`-- requirements-examples.txt             # 可选客户端依赖
```

`client` 和 `server` 表示 MCP 中的角色，`stdio` 和 `http` 表示连接方式，并非两类客户端。
`zentao_client_stdio.py` 会启动对应的 stdio 服务端；`zentao_client_http.py` 则连接已经启动的 HTTP 服务端。
`zentao/client.py` 供两个服务端调用禅道 REST API，不参与 MCP 客户端连接。

## 验证

```powershell
python -m unittest discover -s tests -v
python -m compileall -q zentao tests example_amap_client_http.py example_playwright_client_stdio.py
```

单元测试不连接真实禅道，不会创建、修改或删除用户。首次接入真实环境时，建议先使用只读工具验证 URL、权限和返回格式。

## 常见问题

### 返回 401 或 403

确认账号密码、Token 以及禅道账号权限正确，并检查实例是否允许 API 访问。

### 返回 404

确认 `ZENTAO_URL` 的部署路径。程序默认将纯域名补全为 `/zentao/api.php/v1`；如果禅道安装在其他子路径，请直接填写完整的 `/api.php/v1` 地址。

### MCP 客户端无法启动 stdio 服务

确认 MCP 配置中的 Python 路径和项目根目录 `cwd` 正确。也可以在项目根目录执行 `python -m zentao.zentao_server_stdio` 检查依赖和 `.env`；进程正常启动后会等待 MCP 消息。stdio 协议使用标准输出通信，启动日志会写入标准错误。

## 许可证

当前仓库尚未附带开源许可证。公开可见不等于允许复制、修改或分发；正式发布前请根据你的授权意图选择并添加 `LICENSE`。