Skip to main content
Glama

ZenTao MCP Server (API V1.0)

Сервер ZenTao MCP на базе TypeScript + Node.js + @modelcontextprotocol/sdk, поддерживающий:

  • Инициализацию входа (initZentao)

  • Просмотр продуктов (getProducts)

  • Просмотр моих ошибок (getMyBugs)

  • Просмотр деталей ошибки (getBugDetail)

  • Решение ошибок (resolveBug)

  • Активацию ошибок (activateBug, повторное открытие)

1. Подготовка окружения

npm install
cp .env.example .env

Пожалуйста, настройте адрес ZenTao и информацию аутентификации в .env (рекомендуется передавать логин и пароль во время выполнения через initZentao, не храня их в открытом виде в файле).

Related MCP server: ZenTao MCP Server

2. Запуск из npm / npx (рекомендуется для других машин)

Имя пакета npm: @wudidada/zentao-mcp-server (пакет с областью видимости; исполняемая команда zentao-mcp-server).

Требования: Node.js >= 20. Для Linux/macOS рекомендуется установить системный curl (по умолчанию HTTP-бэкенд — curl).

2.1 Пробный запуск из командной строки

npx -y @wudidada/zentao-mcp-server

Пример HTTP-режима:

MCP_TRANSPORT=http npx -y @wudidada/zentao-mcp-server

2.2 Cursor mcp.json (stdio + переменные окружения)

Настройте в файле .cursor/mcp.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"
      }
    }
  }
}

После изменения конфигурации полностью перезапустите Cursor. Вы также можете изменить имя пакета в args на фиксированную версию, например @wudidada/zentao-mcp-server@1.0.1.

2.3 Сопровождающим: публикация в npm

npm run build
npm test
npm publish --access public

Перед первой публикацией необходимо выполнить npm login и убедиться, что version в package.json не занята.

Репозиторий исходного кода: https://github.com/wudidada/zentao-mcp-server

3. Способы запуска

stdio (предпочтительно для локальной IDE)

npm run start:stdio

HTTP/SSE (удаленное подключение)

npm run start:http

Порт по умолчанию 3000, проверка работоспособности:

curl http://localhost:3000/healthz

4. Сборка и тестирование

npm run build
npm test

5. Описание параметров инструментов MCP

initZentao

  • baseUrl?: string

  • account: string

  • password?: string

  • token?: string

Выберите либо password, либо token.

getMyBugs

  • status?: "active" | "resolved" | "closed" | "all" (по умолчанию active)

  • productId?: number

getBugDetail

  • bugId: number

activateBug

  • bugId: number

  • assignedTo?: string (назначено на, аккаунт)

  • openedBuild?: string | string[] (затронутые сборки, в документации массив; если не передано, по умолчанию ["trunk"])

  • comment?: string

resolveBug

  • bugId: number

  • resolution.resolution: "fixed" | "notrepro" | "duplicate" | "bydesign" | "willnotfix" | "tostory" | "external"

  • resolution.resolvedBuild?: string (когда решение fixed, сервер фиксированно отправляет trunk, поле игнорируется, чтобы избежать аномалий отображения в веб-интерфейсе ZenTao)

  • resolution.duplicateBug?: number (обязательно, когда resolution=duplicate)

  • resolution.comment?: string

6. Базовые принципы безопасности и эксплуатации

  • Логи по умолчанию маскируют password/token/authorization

  • Таймаут запроса по умолчанию 10s

  • Интерфейсы запросов (GET) поддерживают повторные попытки с экспоненциальной задержкой

  • HTTP-режим предоставляет проверку работоспособности /healthz

  • Если настроены ZENTAO_BASE_URL + ZENTAO_ACCOUNT + (ZENTAO_PASSWORD или ZENTAO_TOKEN), процесс автоматически выполнит вход при запуске, нет необходимости каждый раз вызывать initZentao

  • ZENTAO_HTTP_BACKEND: axios использует встроенный HTTP Node.js; curl вызывает системный curl. На не-Windows системах по умолчанию используется curl, чтобы избежать проблем с длительным отсутствием ответа от некоторых экземпляров ZenTao при использовании «Node-клиент + заголовок Token + GET»

6.1 Обзор переменных окружения

Переменная

Описание

ZENTAO_BASE_URL

Корневой адрес ZenTao API V1, например http://host/zentao/api.php/v1

ZENTAO_ACCOUNT / ZENTAO_PASSWORD / ZENTAO_TOKEN

Для автоматического входа (выберите пароль или токен)

ZENTAO_HTTP_BACKEND

axios или curl; если не задано, Linux/macOS по умолчанию curl, Windows по умолчанию axios

7. Структура проекта

src/
  adapters/      # 禅道 API V1.0 适配层
  schemas/       # zod 参数校验
  server/        # stdio/http 双入口
  services/      # 领域服务
  tools/         # MCP 工具实现

8. Примечания

  • Текущая реализация инкапсулирована в соответствии с общими путями REST API ZenTao V1.0 (/tokens, /bugs, /products).

  • Решение ошибки (Resolve Bug): официальный интерфейс v1 — это POST /bugs/{id}/resolve (не PUT). При ошибочном использовании PUT запрос может вернуть HTTP-успех, но статус в ZenTao не обновится.

  • Если пути вашего экземпляра ZenTao или поля аутентификации отличаются, вы можете адаптировать их в src/adapters/zentaoApiV1.ts.

Available Tools

7 tools
activateBugB

激活(重新打开)Bug,对应禅道 API v1:POST /bugs/{id}/active。适用于已解决/已关闭后重新激活。

Inputs: bugId (required), assignedTo, openedBuild, comment.

getBugDetailB
Read-only

查看单个 bug 详情。

Inputs: bugId (required).

getMyBugsB
Read-only

按状态与产品筛选我的 bug 列表。

Inputs: status, productId.

getProductsB
Read-only

获取禅道产品列表。

Inputs: no named parameters.

healthCheckB
Read-only

检查当前会话与服务可用性。

Inputs: no named parameters.

initZentaoC

初始化禅道连接并登录(支持 password 或 token)。

Inputs: baseUrl, account, password, token.

resolveBugC

提交 Bug 解决动作(fixed/notrepro/duplicate/...)。

Inputs: bugId (required), resolution (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no ambiguity. activateBug, resolveBug, getBugDetail, and getMyBugs handle different bug lifecycle stages and views, while getProducts, healthCheck, and initZentao cover separate administrative and setup functions. The descriptions make it easy to distinguish between tools like activateBug (reopen) and resolveBug (close with resolution).

    Naming Consistency4/5

    The naming follows a mostly consistent verb_noun pattern with minor deviations. Tools like activateBug, getBugDetail, getMyBugs, getProducts, and resolveBug use clear action-object naming. However, healthCheck and initZentao deviate slightly by using compound nouns without verbs, though they remain readable and intuitive.

    Tool Count5/5

    With 7 tools, this server is well-scoped for bug tracking and system management in ZenTao. Each tool earns its place by covering essential operations: bug lifecycle (activate, resolve, view), product listing, and system setup/health. The count is neither too sparse nor bloated, fitting the domain appropriately.

    Completeness4/5

    The tool set provides strong coverage for bug management with create, read, update (activate/resolve), and delete implied through resolution. Minor gaps exist, such as no explicit tool for creating bugs or managing other entities like tasks or users, but agents can work around this with the available tools for core workflows.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      Not graded
      maintenance
      Enables direct integration with Zentao bug tracking systems through Cursor. Supports authentication, bug retrieval, searching, and listing operations for comprehensive bug management through natural language.
      5
      7 npm
      -
    • F
      license
      A
      quality
      B
      maintenance
      Enables interaction with ZenTao project management system through RESTful APIs. Supports listing products, managing bugs, viewing statistics, and filtering personal bug assignments through natural language.
      4
      26 npm
      16
      -