zentao-mcp-v1

# ZenTao MCP Server (V1.0) 禅道（ZenTao）**V1.0 REST API** 的 MCP（Model Context Protocol）服务器，覆盖官方 V1.0 API 手册全部 **97 个接口**，让 Claude 等 AI 助手直接查询与操作禅道的项目、需求、任务、Bug、用例等数据。 ## 简介 - **全量覆盖**：Token、部门、用户、项目集、产品、产品计划、发布、需求、项目、版本、执行、任务、Bug、用例、测试单、反馈、工单 —— 17 个模块 97 个接口 - **规范驱动**：`docs/zentao-v1-openapi.json` 由脚本从[官方 API 手册](https://www.zentao.net/book/api/2309.html)第 2 章自动生成（可重复执行），FastMCP 据此自动注册全部工具 - **自动登录**：配置禅道账号密码后，服务端自动获取/续期 Token，MCP 客户端零配置接入；也可回退为客户端 Token 头透传 - **Streamable HTTP**：以 HTTP 服务方式部署，支持远程与多客户端共享 技术栈：Python ≥3.10、[FastMCP](https://gofastmcp.com) 3.x、httpx。 ## 快速开始 ### 1. 安装 ```bash git clone <本仓库地址> && cd zentao-mcp-v1.0 uv venv && uv pip install --python .venv/bin/python -e . --group dev # 或 pip: python -m venv .venv && .venv/bin/pip install -e . ``` ### 2. 配置 复制 `config.example.yaml` 为 `config.yaml`（已被 .gitignore 排除），填写： ```yaml base_url: "http://您的禅道域名/api.php/v1" # 必填 account: "您的禅道账号" # 自动登录（推荐） password: "您的禅道密码" ``` > 注意：`spec_path` 默认为相对当前工作目录的 `docs/zentao-v1-openapi.json`，请从仓库根目录启动；也可在配置或环境变量（`ZENTAO_MCP_SPEC_PATH`）中指定绝对路径。 所有配置项均可用环境变量覆盖：`ZENTAO_MCP_BASE_URL` / `ZENTAO_MCP_ACCOUNT` / `ZENTAO_MCP_PASSWORD` / `ZENTAO_MCP_HOST` / `ZENTAO_MCP_PORT` 等。 ### 3. 运行 ```bash cp config.example.yaml config.yaml # 编辑后 .venv/bin/python -m zentao_mcp --config config.yaml # 默认监听 0.0.0.0:9091，MCP 端点 http://127.0.0.1:9091/mcp ``` ## 客户端接入 **自动登录模式（推荐）**——客户端只需 URL： ```json { "mcpServers": { "zentao-v1": { "url": "http://127.0.0.1:9091/mcp" } } } ``` **Token 透传模式**（未配置账号密码时；先用 `get_token` 工具或 `curl -X POST {base_url}/tokens` 获取 Token）： ```json { "mcpServers": { "zentao-v1": { "url": "http://127.0.0.1:9091/mcp", "headers": { "token": "您的Token" } } } } ``` ## Docker 部署 ```bash docker build -t zentao-mcp-v1 . docker run -d -p 9091:9091 \ -e ZENTAO_MCP_BASE_URL=http://您的禅道域名/api.php/v1 \ -e ZENTAO_MCP_ACCOUNT=您的账号 \ -e ZENTAO_MCP_PASSWORD=您的密码 \ zentao-mcp-v1 ``` ## 工具清单（97…