Skip to main content
Glama

Servidor MCP de ZenTao (API V1.0)

Servicio MCP de ZenTao basado en TypeScript + Node.js + @modelcontextprotocol/sdk, que admite:

  • Inicialización de inicio de sesión (initZentao)

  • Ver productos (getProducts)

  • Ver mis errores (getMyBugs)

  • Ver detalles de errores (getBugDetail)

  • Resolver errores (resolveBug)

  • Activar errores (activateBug, reabrir)

1. Preparación del entorno

npm install
cp .env.example .env

Configure la dirección de ZenTao y la información de autenticación en .env (se recomienda pasar la cuenta y la contraseña a través de initZentao en tiempo de ejecución, no guardarlas en texto plano en el archivo).

Related MCP server: ZenTao MCP Server

2. Ejecución desde npm / npx (recomendado para otras máquinas)

Nombre del paquete npm: @wudidada/zentao-mcp-server (paquete con ámbito; comando ejecutable zentao-mcp-server).

Requisito: Node.js >= 20. Para Linux/macOS se recomienda instalar el curl del sistema (el backend HTTP predeterminado es curl).

2.1 Prueba de línea de comandos

npx -y @wudidada/zentao-mcp-server

Ejemplo de modo HTTP:

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

2.2 Cursor mcp.json (stdio + variables de entorno)

Configúrelo en .cursor/mcp.json en el directorio del proyecto o del usuario, por ejemplo:

{
  "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"
      }
    }
  }
}

Después de modificar la configuración, reinicie Cursor por completo. También puede cambiar el nombre del paquete en args a una versión fija, por ejemplo @wudidada/zentao-mcp-server@1.0.1.

2.3 Mantenedor: Publicar en npm

npm run build
npm test
npm publish --access public

Antes de la primera publicación, debe ejecutar npm login y asegurarse de que la version en package.json no esté ocupada.

Repositorio de código fuente: https://github.com/wudidada/zentao-mcp-server

3. Métodos de inicio

stdio (preferido para IDE local)

npm run start:stdio

HTTP/SSE (acceso remoto)

npm run start:http

Puerto predeterminado 3000, verificación de estado:

curl http://localhost:3000/healthz

4. Construcción y pruebas

npm run build
npm test

5. Descripción de los parámetros de la herramienta MCP

initZentao

  • baseUrl?: string

  • account: string

  • password?: string

  • token?: string

Elija entre password y token.

getMyBugs

  • status?: "active" | "resolved" | "closed" | "all" (predeterminado active)

  • productId?: number

getBugDetail

  • bugId: number

activateBug

  • bugId: number

  • assignedTo?: string (asignado a, cuenta)

  • openedBuild?: string | string[] (versión afectada, el documento indica una matriz; si no se pasa, el valor predeterminado es ["trunk"])

  • comment?: string

resolveBug

  • bugId: number

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

  • resolution.resolvedBuild?: string (cuando la solución es fixed, el servidor envía trunk de forma fija, ignorando este campo para evitar anomalías en la visualización de la interfaz web de ZenTao)

  • resolution.duplicateBug?: number (obligatorio cuando resolution=duplicate)

  • resolution.comment?: string

6. Línea base de seguridad y operaciones

  • Los registros (logs) enmascaran por defecto password/token/authorization

  • Tiempo de espera de solicitud predeterminado 10s

  • Las interfaces de consulta (GET) admiten reintentos con retroceso exponencial

  • El modo HTTP proporciona una verificación de estado /healthz

  • Si se configuran ZENTAO_BASE_URL + ZENTAO_ACCOUNT + (ZENTAO_PASSWORD o ZENTAO_TOKEN), el proceso iniciará sesión automáticamente al arrancar, sin necesidad de llamar a initZentao cada vez

  • ZENTAO_HTTP_BACKEND: axios utiliza el HTTP nativo de Node; curl invoca el curl del sistema. En sistemas que no son Windows, el valor predeterminado es curl, utilizado para evitar problemas de falta de respuesta prolongada en algunas instancias de ZenTao con "cliente Node + encabezado Token + GET"

6.1 Resumen de variables de entorno

Variable

Descripción

ZENTAO_BASE_URL

Dirección raíz de la API V1 de ZenTao, como http://host/zentao/api.php/v1

ZENTAO_ACCOUNT / ZENTAO_PASSWORD / ZENTAO_TOKEN

Para inicio de sesión automático (elija entre contraseña y token)

ZENTAO_HTTP_BACKEND

axios o curl; si no se establece, el valor predeterminado en Linux/macOS es curl, en Windows es axios

7. Estructura del proyecto

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

8. Notas

  • La implementación actual encapsula las rutas REST comunes de la API V1.0 de ZenTao (/tokens, /bugs, /products).

  • Resolver errores: La interfaz oficial v1 es POST /bugs/{id}/resolve (no PUT). Si se usa PUT por error, es posible que la solicitud HTTP tenga éxito pero que el estado no se actualice realmente en ZenTao.

  • Si la ruta de su instancia de ZenTao o los campos de autenticación son diferentes, puede adaptarlos en 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.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    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
      30 npm
      16
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to manage Zentao bugs, requirements, and test cases through natural language interactions. It supports querying, creating, and updating various Zentao data entities including products, projects, and executions.
      12
      MIT