Skip to main content
Glama

ZenTao MCP Server (API V1.0)

TypeScript + Node.js + @modelcontextprotocol/sdk ベースのZenTao MCPサービスで、以下をサポートしています:

  • ログイン初期化(initZentao)

  • 製品の表示(getProducts)

  • マイバグの表示(getMyBugs)

  • バグ詳細の表示(getBugDetail)

  • バグの解決(resolveBug)

  • バグの有効化(activateBug、再オープン)

1. 環境準備

npm install
cp .env.example .env

.env にZenTaoのURLと認証情報を設定してください(実行時に 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 が必要です。また、package.json の version が使用されていないことを確認してください。

ソースコードリポジトリ: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 Web画面での表示異常を避けるため、このフィールドは無視されます)

  • 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 はNode内蔵HTTPを使用し、curl はシステムの curl を呼び出します。Windows以外ではデフォルトで curl を使用し、一部のZenTaoインスタンスで発生する「Nodeクライアント + Token ヘッダー + GET」の長時間応答なし問題を回避します

6.1 環境変数一覧

変数

説明

ZENTAO_BASE_URL

ZenTao API V1 ルートURL(例: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. 注意事項

  • 現在の実装は、ZenTao API V1.0 の一般的なRESTパス(/tokens、/bugs、/products)に基づいています。

  • バグの解決:公式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.

    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