bussin-mcp

bussin-mcp

Claude、ChatGPT、Cursor、その他あらゆる MCP 対応クライアント向けの Azure Service Bus ツールです。

Model Context Protocol サーバーです。AI アシスタントから Azure Service Bus のキュー、トピック、サブスクリプション、デッドレターキューを調べられます。Bussin のウェブエクスプローラーを支えるものと同じ AMQP クライアントを使って、メッセージのピーク、ペイロードの検索、失敗したメッセージの再送を行えます。

デフォルトでは読み取り専用です。指示がない限り、ブローカーへの書き込みは行いません。

npx -y bussin-mcp --demo

インストール

npm install -g bussin-mcp

または、以下のクライアント設定で使われているように、npx から直接実行できます。

クイックスタート

Azure アカウントなしで試せます。--demo を指定すると、キューが用意されたプロセス内シミュレーターに接続します。

npx -y bussin-mcp --demo

Claude Code

claude mcp add bussin -- npx -y bussin-mcp --namespace my-namespace

Claude Desktop / Cursor

MCP 設定（claude_desktop_config.json または .cursor/mcp.json）に追加します。

{
  "mcpServers": {
    "bussin": {
      "command": "npx",
      "args": ["-y", "bussin-mcp", "--namespace", "my-namespace"]
    }
  }
}

認証

デフォルトであり、推奨される方法は Entra ID です。このサーバーは Azure の DefaultAzureCredential を使用するため、すでに利用可能な認証情報が自動的に選択されます。

az login

マネージド ID、または AZURE_TENANT_ID、AZURE_CLIENT_ID、AZURE_CLIENT_SECRET を使ったサービスプリンシパルでも認証できます。

名前空間（またはそのリソースグループ）に、次の 2 つのロールを割り当てる必要があります。

ロール	用途
Azure Service Bus Data Receiver	メッセージのピークと検索
Azure Service Bus Data Sender	--allow-send を有効にした場合のみ
Reader	メッセージ数を含め、名前空間、キュー、トピックを一覧表示

サインイン中の ID から見えない名前空間では、SAS 接続文字列を使用できます。

npx -y bussin-mcp --connection-string "Endpoint=sb://...;SharedAccessKeyName=...;SharedAccessKey=..."

接続文字列で認証できるのはデータプレーンのみです。エンティティの検出（list_queues など）は Azure Resource Manager 経由で行われ、Entra ID が必要です。

安全性のモデル

呼び出し元は言語モデルであるため、取り消しできない操作はオプトイン方式です。有効にしていないツールは登録されません。モデルから見えないため、単に拒否される場合とは異なり、実行するよう説得されることもありません。

フラグ	有効になる機能
(なし)	list_namespaces、list_queues、list_topics、list_subscriptions、peek_messages、search_messages
--allow-send	send_message、resubmit_dead_letter
--allow-destructive	delete_messages、dead_letter_messages、purge_entity

追加のガード：

• ピークは実際に非破壊的です：ロック、消費、配信回数の増加は発生しません。
• purge_entity には確認が必要です：confirm 引数は、消去するエンティティ名と完全に一致する必要があります。
• resubmit_dead_letter はデフォルトで追加方式です：メッセージを元のキューにコピーし、デッドレター化された元のメッセージはそのまま残します。元のメッセージの削除には、追加で --allow-destructive が必要です。
• スキャンには上限があります：検索と消去は、呼び出しが停止しなくなるのを防ぐため、--search-timeout-ms（デフォルトは 30 秒）で停止します。
• メッセージ本文は切り詰められます：1 メッセージあたり 4000 文字に制限されるため、大きなペイロードでモデルのコンテキストがあふれることはありません。

オプション

オプション	環境変数	説明
--namespace <name>	BUSSIN_NAMESPACE	ツール呼び出しで使用するデフォルトの名前空間
--demo	BUSSIN_DEMO	組み込みシミュレーターに接続して実行します。Azure とサインインは不要です
--allow-send	BUSSIN_ALLOW_SEND	送信と再送を有効にします
--allow-destructive	BUSSIN_ALLOW_DESTRUCTIVE	削除、デッドレター化、消去を有効にします
--connection-string <cs>	BUSSIN_CONNECTION_STRING	Entra ID の代わりに使用する SAS 接続文字列
--tenant <id>	AZURE_TENANT_ID	認証に使用する Entra テナント
--search-timeout-ms <n>	BUSSIN_SEARCH_TIMEOUT_MS	1 回のスキャンまたは消去の上限時間（デフォルトは 30000）

ツール

常に利用可能

• list_namespaces：ID がサブスクリプションをまたいで参照できるすべての Service Bus 名前空間
• list_queues：アクティブ、配信不能、スケジュール済みの件数を含むキュー
• list_topics：メッセージ数を含むトピック
• list_subscriptions：件数を含む、トピック配下のサブスクリプション
• peek_messages：キュー、サブスクリプション、または配信不能キューからメッセージを読み取ります
• search_messages：本文の部分文字列、メッセージ ID、または件名を検索します

--allow-send を指定した場合

• send_message：キューまたはトピックに送信します
• resubmit_dead_letter：配信不能メッセージを元のキューに再送します

--allow-destructive を指定した場合

• delete_messages：シーケンス番号を指定して、特定のメッセージを完全に削除します
• dead_letter_messages：アクティブなメッセージを配信不能キューに移動します
• purge_entity：キュー、サブスクリプション、または DLQ からすべてのメッセージを削除します

プロンプトの例

my-namespace のうち、配信不能メッセージがあるキューはどれですか？

orders キューにある直近の配信不能メッセージを 5 件表示して、共通点を教えてください。

payments サブスクリプションで、直近のバッチに「timeout」を含むものを検索してください。

この 3 件の DLQ メッセージは、修正済みのバグが原因で失敗したので、再送してください。

関連項目

• Bussin：このツールのベースとなった、ブラウザー上で動作する Azure Service Bus エクスプローラー
• app.bussin.dev：インストール不要のウェブアプリ
• github.com/sgebb/bussin：ソースコード

開発

npm install
npm run build     # builds the Node bundle of bussin-client-js, then bundles with esbuild
npm test          # drives the server over stdio against the simulator
npm run typecheck # tsc --noEmit

bussin-client-js はこのリポジトリに含まれ、ビルド時にインライン化されるため、公開パッケージは単独で動作し、file: 依存関係はありません。

リリース

公開はタグによって行われるため、必ず明示的に実施されます。

1. package.json の version を更新します
2. 変更履歴にリリースを追加します
3. タグを付けてプッシュします。

git tag mcp-v0.1.0 && git push origin mcp-v0.1.0

タグと package.json のバージョンが一致しない場合、またはそのバージョンがすでに npm に存在する場合、ワークフローは公開を拒否します。--provenance を指定して公開することで、tarball を生成したワークフローの実行とコミットに紐付けます。

初回のみの設定： 公開権限を持つ npm オートメーショントークンを作成し、npm-publish という名前のリポジトリ環境の NPM_TOKEN シークレットとして登録します。

公開せずに検証するには、dry_run を有効にしてワークフローを手動で実行します。

ライセンス

Business Source License 1.1 (BUSL-1.1) — LICENSE を参照してください。

個人利用、教育目的での利用、社内業務での利用は無料です。第三者による商用再配布、ブランド変更、またはサービスとしての本ソフトウェアのホスティングは禁止されています。2029-01-01 に Apache 2.0 に移行します。