Content
# ZenTao MCP Server (API V1.0)
Based on `TypeScript + Node.js + @modelcontextprotocol/sdk`, the ZenTao MCP service supports:
- Login initialization (`initZentao`)
- Viewing products (`getProducts`)
- Viewing my bugs (`getMyBugs`)
- Viewing bug details (`getBugDetail`)
- Resolving bugs (`resolveBug`)
- Activating bugs (`activateBug`, reopening)
## 1. Environment Preparation
```bash
npm install
cp .env.example .env
```
Please configure the ZenTao address and authentication information in `.env` (recommended to pass the account and password through `initZentao` at runtime, not storing them in plain text in the file).
## 2. Running from npm / npx (recommended for other machines)
The npm package name is: **`@wudidada/zentao-mcp-server`** (a scoped package; executable command **`zentao-mcp-server`**).
Requirements: **Node.js >= 20**. Linux/macOS recommends installing the system **`curl`** (default HTTP backend is `curl`).
### 2.1 Command Line Trial
```bash
npx -y @wudidada/zentao-mcp-server
```
HTTP mode example:
```bash
MCP_TRANSPORT=http npx -y @wudidada/zentao-mcp-server
```
### 2.2 Cursor `mcp.json` (stdio + environment variables)
Configure in `.cursor/mcp.json` in the project or user directory, for example:
```json
{
"mcpServers": {
"zentao": {
"command": "npx",
"args": ["-y", "@wudidada/zentao-mcp-server"],
"env": {
"ZENTAO_BASE_URL": "http://your-host/zentao/api.php/v1",
"ZENTAO_ACCOUNT": "your_account",
"ZENTAO_PASSWORD": "your_password",
"ZENTAO_HTTP_BACKEND": "curl",
"LOG_LEVEL": "info"
}
}
}
}
```
After modifying the configuration, please **completely restart Cursor**. You can also change the package name in `args` to a fixed version, such as `@wudidada/zentao-mcp-server@1.0.1`.
### 2.3 Maintainer: Publishing to npm
```bash
npm run build
npm test
npm publish --access public
```
You need to `npm login` before the first publication, and ensure that the `version` in `package.json` is not occupied.
Source code repository: <https://github.com/wudidada/zentao-mcp-server>
## 3. Startup Method
### stdio (local IDE preferred)
```bash
npm run start:stdio
```
### HTTP/SSE (remote access)
```bash
npm run start:http
```
Default port `3000`, health check:
```bash
curl http://localhost:3000/healthz
```
## 4. Building and Testing
```bash
npm run build
npm test
```
## 5. MCP Tool Parameter Description
### initZentao
- `baseUrl?: string`
- `account: string`
- `password?: string`
- `token?: string`
> Choose one of `password` and `token`.
### getMyBugs
- `status?: "active" | "resolved" | "closed" | "all"` (default `active`)
- `productId?: number`
### getBugDetail
- `bugId: number`
### activateBug
- `bugId: number`
- `assignedTo?: string` (assigned to, account)
- `openedBuild?: string | string[]` (affected version, document is an array; **default is `["trunk"]` if not passed**)
- `comment?: string`
### resolveBug
- `bugId: number`
- `resolution.resolution: "fixed" | "notrepro" | "duplicate" | "bydesign" | "willnotfix" | "tostory" | "external"`
- `resolution.resolvedBuild?: string` (**when the solution is `fixed`, the server will submit `trunk`**, ignore this field to avoid some ZenTao web display exceptions)
- `resolution.duplicateBug?: number` (required when `resolution=duplicate`)
- `resolution.comment?: string`
## 6. Security and Operation Baseline
- Logs are desensitized by default for `password/token/authorization`
- Default request timeout `10s`
- Query interfaces (GET) support exponential backoff retries
- HTTP mode provides `/healthz` health check
- If `ZENTAO_BASE_URL` + `ZENTAO_ACCOUNT` + (`ZENTAO_PASSWORD` or `ZENTAO_TOKEN`) are configured, the process will automatically log in at startup, without needing to call `initZentao` every time
- `ZENTAO_HTTP_BACKEND`: `axios` uses Node built-in HTTP; `curl` calls system `curl`. On non-Windows platforms, `curl` is used by default to avoid some ZenTao instances' issues with "Node client + `Token` header + GET" having no response for a long time
### 6.1 Environment Variable List
| Variable | Description |
| --- | --- |
| `ZENTAO_BASE_URL` | ZenTao API V1 root address, such as `http://host/zentao/api.php/v1` |
| `ZENTAO_ACCOUNT` / `ZENTAO_PASSWORD` / `ZENTAO_TOKEN` | Used for automatic login (choose one of password and token) |
| `ZENTAO_HTTP_BACKEND` | `axios` or `curl`; if not set, Linux/macOS defaults to `curl`, Windows defaults to `axios` |
## 7. Project Structure
```text
src/
adapters/ # ZenTao API V1.0 adapter layer
schemas/ # zod parameter validation
server/ # stdio/http dual entry
services/ # domain services
tools/ # MCP tool implementation
```
## 8. Precautions
- The current implementation is based on ZenTao API V1.0 common REST paths encapsulation (`/tokens`, `/bugs`, `/products`).
- **Resolving Bug**: the official v1 interface is **`POST /bugs/{id}/resolve`** (not PUT). If PUT is used incorrectly, it may result in HTTP success but ZenTao not actually updating the status.
- If your ZenTao instance path or authentication field has differences, you can adapt it in `src/adapters/zentaoApiV1.ts`.
