Queue Pilot

🚀 Queue Pilot

メッセージキュー開発用のMCPサーバーです。メッセージの検査とJSONスキーマ検証を組み合わせています。RabbitMQ と Kafka をサポートしています。

複数のチームがメッセージブローカーを介して通信する統合プロジェクト向けに設計されています。キューやトピックを検査し、メッセージを表示し、合意されたスキーマに基づいてペイロードを検証することができます。これらの操作はすべてAIアシスタントから行えます。

✨ 主な機能

• 複数のブローカーをサポート — 統一されたアダプターインターフェースを介して、RabbitMQとApache Kafkaをサポートします。
• メッセージ検査 — キューやトピックを閲覧し、メッセージを消費せずに確認できます。
• スキーマ検証 — JSONスキーマ定義に基づいてメッセージペイロードを検証します。
• 統合検査 — inspect_queue はメッセージを確認し、各メッセージをそのスキーマに対して検証します。
• 検証済みのパブリッシュ — publish_message は送信前にスキーマに対して検証し、無効なメッセージはブローカーに到達しません。
• キュー管理 — 開発やテストのワークフロー用に、キューやトピック、バインディングを作成し、メッセージを削除できます。
• ブローカー情報 — エクスチェンジ、バインディング、コンシューマーグループ、パーティションの詳細を一覧表示します。

📦 インストール

前提条件

• Node.js >= 22 — 必要なランタイムです (node --version で確認できます)
• メッセージブローカー:
  • 管理プラグイン が有効になっている RabbitMQ (ポート15672のHTTP API)、または
  • Apache Kafka (@confluentinc/kafka-javascript をピア依存関係として必要とします)
• MCP互換クライアント — Claude Code、Claude Desktop、Cursor、VS Code (Copilot)、Windsurfなど

🚀 クイックスタート

1. スキーマを定義する

ディレクトリにJSONスキーマファイルを作成します。

schemas/order.created.json:

{
  "$id": "order.created",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Order Created",
  "description": "Emitted when a new order is placed",
  "version": "1.0.0",
  "type": "object",
  "required": ["orderId", "amount"],
  "properties": {
    "orderId": { "type": "string" },
    "amount": { "type": "number" }
  }
}

2. MCPクライアントに追加する

queue-pilot init を使用してクライアント用の設定を生成します。

npx queue-pilot init --schemas /absolute/path/to/your/schemas --client <name>

サポートされているクライアント: claude-code、claude-desktop、vscode、cursor、windsurf。--client を省略すると、汎用のJSONが生成されます。

Kafkaの場合は、--broker kafka を追加します。生成された設定には、必要な @confluentinc/kafka-javascript ピア依存関係が自動的に含まれます。

デフォルトではない資格情報は、ps 出力にシークレットが公開されないように、環境変数として含めます。

npx queue-pilot init --schemas ./schemas --rabbitmq-user admin --rabbitmq-pass secret

Kafka SASL認証を含むすべてのオプションについては、npx queue-pilot init --help を実行してください。

Windowsの注意: npx がパッケージを解決できない場合は、cmd /c npx queue-pilot init ... を試してください。

{
  "mcpServers": {
    "queue-pilot": {
      "command": "npx",
      "args": [
        "-y",
        "queue-pilot",
        "--schemas", "/absolute/path/to/your/schemas"
      ]
    }
  }
}

{
  "mcpServers": {
    "queue-pilot": {
      "command": "npx",
      "args": [
        "-y",
        "--package=@confluentinc/kafka-javascript",
        "--package=queue-pilot",
        "queue-pilot",
        "--schemas", "/absolute/path/to/your/schemas",
        "--broker", "kafka"
      ],
      "env": {
        "KAFKA_BROKERS": "localhost:9092"
      }
    }
  }
}

{
  "mcpServers": {
    "queue-pilot": {
      "command": "npx",
      "args": [
        "tsx",
        "src/index.ts",
        "--schemas", "./schemas"
      ],
      "cwd": "/path/to/queue-pilot"
    }
  }
}

3. 使用する

アシスタントに次のような質問をします。

• "どのキューがあり、それぞれに何個のメッセージがありますか？"
• "ordersキューのメッセージを表示してください"
• "registrationキューを検査し、すべてのメッセージが有効かどうかを確認してください"
• "利用可能なスキーマは何ですか？"
• "このメッセージをorder.createdスキーマに対して検証してください"
• "eventsエクスチェンジにorder.createdイベントをパブリッシュしてください"
• "dead-lettersという名前のキューを作成し、eventsエクスチェンジにバインドしてください"
• "ordersキューからすべてのメッセージを削除してください"
• "すべてのコンシューマーグループを一覧表示してください" (Kafka)
• "ordersトピックのパーティションの詳細を表示してください" (Kafka)

📚 ドキュメント

スキーマ形式

スキーマはJSON Schema draft-07に従い、いくつかの規則があります。

• $id — メッセージタイプ識別子 (メッセージの type プロパティと一致)
• version — スキーマバージョン (カスタムフィールド、JSON Schemaによって検証されません)
• required、properties、format などの標準的なJSON Schema検証

スキーマの一致: キューを検査するとき、メッセージの type プロパティを使用して、$id によって対応するスキーマを見つけます。

設定

CLI引数は環境変数よりも優先され、環境変数はデフォルトよりも優先されます。

MCPクライアントの env ブロックで環境変数を使用して、ps 出力に資格情報が公開されないようにしてください。

🔧 技術詳細

開発

npm install
npm test                    # 単体テスト
npm run test:coverage       # カバレッジレポート
npm run build               # TypeScriptのコンパイル
npm run typecheck           # 型チェック

# 統合テスト (RabbitMQが必要)
docker compose up -d --wait
npm run test:integration

技術スタック

• TypeScript (strictモード、ESM)
• MCP SDK v1.26.0
• Ajv for JSON Schema validation
• Zod for MCP tool parameter definitions
• Vitest for testing
• RabbitMQ Management HTTP API
• Confluent Kafka JavaScript (オプション、Kafkaサポート用)

📄 ライセンス

MIT