MCP Zentao Bugs

🚀 ZenTao Bugs MCP Server

FastMCPベースの禅道Bug管理MCPサーバーで、製品検索、Bug照会、解決機能を提供します。

🚀 クイックスタート

インストール

npm install -g mcp-zentao-bugs

設定と実行

方法1: 環境変数の設定

export ZENTAO_BASE_URL="https://your-zentao.com"
export ZENTAO_ACCOUNT="your-username"
export ZENTAO_PASSWORD="your-password"
mcp-zentao-bugs

方法2: .envファイルの使用

# カレントディレクトリに.envファイルを作成
echo "ZENTAO_BASE_URL=https://your-zentao.com" > .env
echo "ZENTAO_ACCOUNT=your-username" >> .env
echo "ZENTAO_PASSWORD=your-password" >> .env
mcp-zentao-bugs

💡 使用アドバイス：グローバルインストール後、.envファイルは自動的に読み込まれ、追加の設定は不要です。

方法3: 一度だけの設定

ZENTAO_BASE_URL="https://your-zentao.com" \
ZENTAO_ACCOUNT="your-username" \
ZENTAO_PASSWORD="your-password" \
mcp-zentao-bugs

コマンドラインオプション

mcp-zentao-bugs --help      # ヘルプ情報を表示
mcp-zentao-bugs --version   # バージョン情報を表示

✨ 主な機能

• 🔐 自動ログイン - 起動時に自動的に禅道にログインし、Tokenを保持します。
• 🧠 スマート検索 - 一度の操作で製品とBugの検索が完了します。唯一の製品が見つかった場合は直接Bugリストを返し、複数の製品がある場合は選択肢を提供します。
• 🐛 Bug管理 - 製品のBugを照会し、詳細を取得し、解決済みとしてマークします。
• 🖼️ 画像抽出 - Bugの手順から自動的に画像URLを抽出し、スクリーンショットの確認を容易にします。
• 🎯 高精度検索 - APIレベルでアクティブなBugをフィルタリングし、自動的にページングして十分なアクティブBugを取得します。
• 📡 SSEストリーミング転送 - Server-Sent Eventsを通じてログと結果をリアルタイムでプッシュします。
• 🔄 シリアル処理 - 単一プロセスのキュー処理で、ツールの呼び出しを順番に実行します。
• 🚀 FastMCP標準 - MCPプロトコルに互換性があり、HTTP StreamingとSSEをサポートします。
• 📉 トラフィック最適化 - 検索手順をスマートに統合し、API呼び出しとデータ転送を削減します。

ツールリスト

典型的な作業フロー

🔄 日常のBug処理フロー

ステップ1：利用可能な製品を確認（オプション）

{
  "keyword": "電子商取引",
  "limit": 10
}

• 🔍 製品発見：利用可能な製品を確認します。
• 📝 正確な命名：正確な製品名称を取得し、曖昧な一致を避けます。

ステップ2：Bugの完全な詳細を取得

{
  "productName": "電子商取引プラットフォーム",
  "keyword": "ログイン"
}

• 🎯 高精度な位置特定：製品名称を使用して、自分に割り当てられた最初のアクティブなBugを自動的に見つけます。
• 📋 完全な詳細：Bugの完全な情報を直接返し、追加の呼び出しは必要ありません。
• ⚡ 高効率な検索：製品名称を使用するため、業務習慣に合っています。
• 🔍 正確な一致検証：製品を曖昧に検索した場合、複数の製品が見つかったらユーザーに選択を促し、正確性を確保します。

ステップ3：解決済みとしてマーク

{
  "bugId": 123,
  "comment": "ログインページの表示問題を修正しました。"
}

• ✅ 迅速な解決：一度の操作でBugを解決済みとしてマークします。

ステップ4：次のBugに進む ステップ2を繰り返して、次のBugを処理します...

📊 その他のツールの使用シナリオ

Bugリストを確認（一括操作時）

{
  "productId": 1,
  "limit": 20,
  "keyword": "インターフェース"
}

Bug統計を確認

{
  "productId": 1,
  "activeOnly": true
}

📊 作業量管理

自分のBug統計を確認

{
  "productId": 1,
  "activeOnly": true
}

• 📈 作業量統計：現在処理する必要のあるアクティブなBugの数を把握します。
• 📋 優先度の並べ替え：深刻度に応じて自動的に並べ替えます。

自分のBugリストを確認

{
  "productId": 1,
  "limit": 20,
  "keyword": "インターフェース"
}

• 📝 一括確認：自分に割り当てられたBugリストを取得します。
• 🔍 キーワード検索：特定のタイプのBugをすばやく見つけます。

🎯 ツールの利点

• 🎯 デフォルトで自分に割り当てられたもの：すべてのツールはデフォルトで自分に割り当てられたBugのみを検索し、不要な情報を減らします。
• ⚡ デフォルトでアクティブ状態：デフォルトでアクティブ状態のBugのみを表示し、処理待ちのタスクに集中できます。
• 🏷️ 製品名称に優しい：主なツールは製品IDではなく製品名称を使用することができ、業務習慣に合っています。
• 📋 直接詳細を返す：getMyBugはBugの完全な詳細を直接返し、呼び出し手順を減らします。
• 🔍 正確な一致検証：製品を曖昧に検索した場合、複数の製品が見つかったらユーザーに選択を促し、正確性を確保します。
• 🔒 製品を指定する必要がある：すべてのツールは製品を指定する必要があり、一定期間は1つの製品に集中できます。
• 🔄 フロー最適化：ツールの設計は「取得→処理→解決→次のもの」の作業フローに完全に合っています。
• 💰 トラフィック節約：ジェネレーターモードを使用し、見つけたらすぐに停止し、不要なデータ転送を避けます。
• 📊 スマートな統計：正確な作業量統計を提供し、進捗管理を容易にします。

画像抽出機能

getBugDetailツールは現在、Bugの手順から自動的に画像を抽出する機能をサポートしています。

{
  "bug": {
    "id": 123,
    "title": "ログインページの表示が異常",
    "steps": "<p>ステップ1：ログインページを開く</p><p></p>",
    "stepsImages": [
      "https://example.com/screenshot.png"
    ]
  }
}

特徴：

• 🖼️ 自動識別 - HTMLコンテンツからすべての<img>タグのsrc属性を抽出します。
• 🔗 URLフィルタリング - HTTP/HTTPSで始まる有効な画像リンクのみを返します。
• 📋 独立した保存 - 画像URLはstepsImages配列に個別に保存され、アクセスが容易です。

🚀 クイックスタート

1. 環境設定

.env.exampleを.envにコピーし、禅道の情報を設定します。

cp .env.example .env

.envファイルを編集します。

# 禅道設定
ZENTAO_BASE_URL=https://your-zentao.com/api.php/
ZENTAO_ACCOUNT=your-username
ZENTAO_PASSWORD=your-password

# サーバーポート
PORT=3000

2. 依存関係のインストール

pnpm install

3. サーバーの起動

# 方法1: npxを使用（推奨）
npx mcp-zentao-bugs

# 方法2: ローカルインストール後に実行
pnpm start

# 方法3: 開発モード（ファイルの変更を自動的に検出して再起動）
pnpm dev

サーバーが起動すると、以下のことが行われます。

• 自動的に禅道にログインし、Tokenを取得します。
• 指定されたポートでHTTP Streamingサービスを起動します。
• /mcp（HTTP Streaming）と/sse（SSE）のエンドポイントを提供します。

4. ヘルスチェック

curl http://localhost:3000/health

MCPクライアント設定

Trae / Claude Codeの設定

TraeまたはClaude CodeのMCP設定に以下を追加します。

{
  "mcpServers": {
    "zentao-server": {
      "url": "http://localhost:3000/sse"
    }
  }
}

Claude Desktopの設定

Claude DesktopのMCP設定ファイルに以下を追加します。

{
  "mcpServers": {
    "zentao-server": {
      "command": "node",
      "args": ["src/mcp-server.mjs"],
      "env": {
        "ZENTAO_BASE_URL": "https://your-zentao.com/api.php/",
        "ZENTAO_ACCOUNT": "your-username",
        "ZENTAO_PASSWORD": "your-password",
        "PORT": "3000"
      }
    }
  }
}

開発

プロジェクト構造

├── src/
│   ├── mcp-server.mjs     # FastMCPサーバーのメインファイル
│   ├── zentao-api.mjs     # 禅道APIのラッピングモジュール
│   └── server.mjs         # 元のSSEサーバー（予備）
├── scripts/               # 公開とツールのスクリプト
│   ├── publish.sh         # Linux/macOSの公開スクリプト
│   ├── publish.bat        # Windowsの公開スクリプト
│   └── pre-publish.js     # 公開前のチェックスクリプト
├── api-docs/              # APIドキュメント
├── .env                   # 環境変数の設定
├── .env.example           # 環境変数のテンプレート
├── package.json
└── README.md

環境変数

スクリプトコマンド

# 依存関係のインストール
pnpm install

# サーバーの起動
pnpm start

# 開発モード（ファイルの変更を監視）
pnpm dev

APIエンドポイント

• HTTP Streaming: http://localhost:3000/mcp
• SSE: http://localhost:3000/sse
• ヘルスチェック: http://localhost:3000/health

🔧 技術詳細

• FastMCP - MCPサーバーフレームワーク
• Node.js 20+ - ランタイム環境
• Zod - パラメータ検証
• dotenv - 環境変数管理
• モジュール化アーキテクチャ - 禅道APIを独立してラッピングし、保守とテストを容易にします。

トラブルシューティング

ログイン失敗

1. .envファイルの禅道設定が正しいことを確認します。
2. ネットワークが禅道サーバーにアクセスできることを確認します。
3. アカウントとパスワードがAPIにアクセスする権限を持っていることを検証します。

接続問題

1. サーバーが起動していることを確認します：curl http://localhost:3000/health
2. ファイアウォールの設定を確認し、ポートがアクセス可能であることを確認します。
3. サーバーのログを確認して詳細なエラー情報を取得します。

ツールの呼び出し失敗

1. 禅道のTokenが有効であることを確認します（Tokenが期限切れになった場合はサーバーを再起動する必要があります）。
2. 入力されたパラメータの形式が正しいことを確認します。
3. サーバーのログに記載されているエラー情報を確認します。

APIのページング問題

問題の説明：禅道APIのページングメカニズムには特殊な動作があり、要求するページ番号が最大ページ数を超えると、APIは空のデータを返さず、最初のページのデータを返しますが、返されるページ番号フィールドは要求したページ番号と一致しません。

解決策：

• ページングの有効性チェック：data.pageと要求したpageパラメータを比較して、最大ページ数を超えたかどうかを判断します。
• スマートページング：ページごとにデータを取得し、ページ番号が一致しないことが検出されたらページングを停止します。
• パフォーマンス最適化：合理的な最大ページ数制限（50ページ）を設定し、無限ループを防止します。
• データの完全性：最後のページに到達したときにすべてのデータを正しく処理することを確保します。

実装の詳細：

// ページングが有効かどうかをチェックします。返されるページ番号が要求したページ番号と一致しない場合は、最大ページ数を超えていることを意味します。
if (data.page && data.page !== page) {
  break; // 最後のページに到達しました。
}

npmjsへの公開

公開前の準備

1. npmアカウントを登録

   npm adduser
   # または既存のアカウントを使用する場合は: npm login
   

2. プロジェクトの状態を確認

   # 公開前のチェックを実行
   npm run pre-release
   
   # または手動でチェック
   ./scripts/publish.sh patch --dry-run
   

公開フロー

方法1: 公開スクリプトを使用（推奨）

# パッチバージョンを公開
./scripts/publish.sh patch

# マイナーバージョンを公開
./scripts/publish.sh minor

# メジャーバージョンを公開
./scripts/publish.sh major

方法2: npmコマンドを使用

# パッチバージョンを公開
npm run release:patch

# マイナーバージョンを公開
npm run release:minor

# メジャーバージョンを公開
npm run release:major

方法3: 手動で公開

# 1. バージョンを更新
npm version patch

# 2. 公開
npm publish

# 3. タグをプッシュ
git push && git push --tags

公開スクリプトの機能

• 自動チェック：プロジェクトの状態、依存関係、ファイルの完全性をチェックします。
• バージョン管理：自動的にバージョン番号を更新し、gitタグを作成します。
• 安全な公開：npmのログイン状態とパッケージ名の可用性をチェックします。
• クロスプラットフォーム対応：bashとWindowsバッチスクリプトを提供します。

バージョン管理戦略

• patch: Bugの修正で、後方互換性があります (1.0.0 → 1.0.1)
• minor: 新機能の追加で、後方互換性があります (1.0.0 → 1.1.0)
• major: 重大な変更で、互換性がない場合があります (1.0.0 → 2.0.0)

公開チェックリスト

• [ ] テストが通過していること (npm test)
• [ ] README.mdが完全に更新されていること
• [ ] バージョン番号が更新されていること
• [ ] すべての変更がコミットされていること
• [ ] npmアカウントにログインしていること
• [ ] パッケージ名の可用性が確認されていること

📄 ライセンス

ISC License