Zentao Mcp

npm version npm downloads GitHub release License Node.js TypeScript MCP Tests

A Model Context Protocol (MCP) server for integrating AI assistants (Claude, Cursor, etc.) with the ZenTao project management API.
Fetch task details, bug reports, and attachments — all directly inside your AI chat.

---

✨ Features

Tool	Description
zentao_get_details	Fetch full details of a task or bug by ID
zentao_get_comments	Fetch only the history and comments timeline of a task or bug
zentao_add_comment	Add a comment/remark to a task or bug
zentao_update_task_status	Update task status (start, finish, close, pause, cancel, restart) and add optional comments/hours
zentao_update_bug_status	Update bug status (resolve, close, activate) and add optional comments/resolutions
zentao_get_assigned_to_me	Get tasks and bugs currently assigned to you (configured via ZENTAO_ACCOUNT)

Under the hood:

• 🔐 Auto login & token refresh — no manual auth needed
• 📦 In-memory cache (2 min TTL) + in-flight request dedup — avoids redundant API calls
• 🔁 Classic JSON API fallback — seamlessly retries via the web API when the REST endpoint returns empty or errors
• 🖼️ Inline HTML images are automatically downloaded and served as local file:// links
• 📎 Attachments are downloaded and embedded as clickable local links
• 🛡️ Corrupt partial downloads are auto-cleaned on error
• ⚡ Non-blocking async image I/O — base64 encoding uses fs.promises + Promise.all

---

📦 Installation

Option 1 — npx (recommended, no install required)

npx @dyno181cm.nexsoft/zentao_mcp

Option 2 — Global install

npm install -g @dyno181cm.nexsoft/zentao_mcp
zentao_mcp

Option 3 — Clone & build

git clone https://github.com/dyno-nexsoft/zentao_mcp.git
cd zentao_mcp
npm install
npm run build

---

⚙️ Configuration

Create a .env file in the project root (or pass via MCP client env block):

ZENTAO_BASE_URL=https://your-zentao-url.com/zentao/api.php/v1
ZENTAO_ACCOUNT=your_username
ZENTAO_PASSWORD=your_password

---

🔌 MCP Client Integration

This server communicates via stdio transport — compatible with any MCP client.

Claude Desktop / Cursor / Windsurf

Add to your MCP client config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "zentao": {
      "command": "npx",
      "args": ["-y", "@dyno181cm.nexsoft/zentao_mcp"],
      "env": {
        "ZENTAO_BASE_URL": "https://your-zentao-url.com/zentao/api.php/v1",
        "ZENTAO_ACCOUNT": "your_username",
        "ZENTAO_PASSWORD": "your_password"
      }
    }
  }
}

---

🛠️ Available Tools

zentao_get_details

Get full details of a ZenTao task or bug, including repro steps (for bugs), inline images, attachments, history, and comments.

Parameter	Type	Required	Description
type	"task" | "bug"	✅	Type of the object
id	string | number	✅	Task or Bug ID

zentao_get_comments

Get only the history and comments timeline of a task or bug.

Parameter	Type	Required	Description
type	"task" | "bug"	✅	Type of the object
id	string | number	✅	Task or Bug ID

zentao_add_comment

Add a comment/remark to a task or bug.

Parameter	Type	Required	Description
type	"task" | "bug"	✅	Type of the object
id	string | number	✅	Task or Bug ID
comment	string	✅	Comment content

zentao_update_task_status

Update a task's status with optional comments, actual start/finish dates, and consumed hours.

Parameter	Type	Required	Description
taskId	string | number	✅	Task ID
action	"start" | "finish" | "close" | "pause" | "cancel" | "restart"	✅	Status transition action
comment	string	❌	Optional comment to attach
consumed	number	❌	Optional hours consumed
finishedDate	string	❌	Optional actual finish date (YYYY-MM-DD)
realStarted	string	❌	Optional actual start date (YYYY-MM-DD)
assignedTo	string	❌	Optional user account to assign to next
left	number	❌	Optional left hours (for restart)

zentao_update_bug_status

Update a bug's status with optional comments and resolutions.

Parameter	Type	Required	Description
bugId	string | number	✅	Bug ID
action	"resolve" | "close" | "activate"	✅	Status transition action
comment	string	❌	Optional comment to attach
resolution	"fixed" | "bydesign" | "postponed" | "external" | "notrepro" | "willnotfix"	❌	Optional resolution type
resolvedBuild	string	❌	Optional build ID where bug was resolved
resolvedDate	string	❌	Optional resolution date (YYYY-MM-DD)
assignedTo	string	❌	Optional user account to assign to next
openedBuild	string	❌	Optional build ID where bug was found (for activate)

zentao_get_assigned_to_me

Get tasks and bugs currently assigned to the configured user account. Takes no arguments.

---

🧑‍💻 Development

npm run build      # Compile TypeScript
npm run dev        # Watch mode
npm test           # Unit tests (Jest)
npm run test:api   # Live API integration test

Project structure

src/
├── index.ts                  # MCP server entry point
├── zentaoClient.ts           # Axios client: auth, cache, dedup, fallback, stream helpers
├── tools.ts                  # Thin orchestrator + backward-compat exports
├── utils/
│   ├── fileUtils.ts          # toFileUrl · getMimeType · formatSize
│   ├── markdownUtils.ts      # htmlToMarkdown · parseFiles · formatUser
│   └── mcpResponse.ts        # mcpText · buildMcpResponse (async)
├── formatters/
│   ├── imageLocalizer.ts     # Inline <img> → local file:// link (deduped, concurrent)
│   ├── attachmentRenderer.ts # Attachments → Markdown ## Files section
│   ├── actionFormatter.ts    # renderHistoryAndComments
│   ├── taskFormatter.ts      # taskToMarkdown (includes comments)
│   ├── bugFormatter.ts       # bugToMarkdown (includes comments)
│   └── myWorkFormatter.ts    # myWorkToMarkdown (includes comments)
└── tools/
    ├── detailTool.ts         # zentao_get_details
    ├── commentTool.ts        # zentao_get_comments · zentao_add_comment
    ├── statusTool.ts         # zentao_update_task_status · zentao_update_bug_status
    └── myWorkTool.ts         # zentao_get_assigned_to_me

Running tests

npm test           # Unit tests — 13 tests across ZentaoClient
npm run test:api   # Live API integration test (requires .env)

---

📄 License

MIT © dyno-nexsoft