# 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 模式

直接运行：

```powershell
python server_stdio.py
```

在支持 MCP 的客户端中添加服务器。下面是通用 JSON 配置示例，路径需要替换为本机绝对路径：

```json
{
  "mcpServers": {
    "zentao": {
      "command": "C:\\absolute\\path\\.venv\\Scripts\\python.exe",
      "args": ["C:\\absolute\\path\\server_stdio.py"]
    }
  }
}
```

macOS/Linux 将 `command` 改为虚拟环境中的 `.venv/bin/python`。服务会从项目根目录加载 `.env`，不依赖 MCP 客户端的当前工作目录。

## Streamable HTTP 模式

启动服务：

```powershell
python server_http.py
```

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

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

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

## 项目结构

```text
.
|-- server_stdio.py              # 禅道 MCP stdio 服务
|-- server_http.py               # 禅道 MCP Streamable HTTP 服务
|-- zentao/
|   |-- client.py                # 禅道 API 请求与 URL 规范化
|   |-- client_mcp.py            # HTTP MCP + 通义千问示例
|   `-- am_mcp.py                # 高德 MCP 出行规划示例
|-- mcp_stdio_server.py          # 最小加法 MCP 示例
|-- mcp_stdio_client.py          # stdio + LangChain 示例
|-- mcp_playwright_client.py     # Playwright MCP + 智谱示例
|-- requirements.txt             # 核心服务依赖
`-- requirements-examples.txt    # 可选示例依赖
```

示例不是运行禅道 MCP 服务的必要部分。如需运行它们，先安装额外依赖：

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

再按 `.env.example` 配置对应变量。Playwright MCP 示例还要求系统已安装 Node.js/npm。

## 验证

```powershell
python -m unittest discover -s tests -v
python -m compileall -q server_stdio.py server_http.py zentao
```

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

## 常见问题

### 返回 401 或 403

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

### 返回 404

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

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

使用虚拟环境 Python 和 `server_stdio.py` 的绝对路径，并先在终端中直接运行一次以检查缺失依赖或 `.env` 配置错误。stdio 协议使用标准输出通信，启动日志会写入标准错误。

## 许可证

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