bussin-mcp

bussin-mcp

为 Claude、ChatGPT、Cursor 和任何其他支持 MCP 的客户端提供 Azure Service Bus 工具。

一个 Model Context Protocol 服务，可让 AI 助手检查你的 Azure Service Bus 队列、主题、订阅和死信队列。使用为 Bussin Web 浏览器提供支持的同一 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

托管标识也适用；你也可以通过 AZURE_TENANT_ID、AZURE_CLIENT_ID 和 AZURE_CLIENT_SECRET 使用服务主体。

你需要在命名空间（或其资源组）上分配以下两个角色：

角色	用途
Azure Service Bus Data Receiver	预览和搜索消息
Azure Service Bus Data Sender	仅在启用 --allow-send 时需要
Reader	列出命名空间、队列和主题及其消息数量

对于已登录身份无法访问的命名空间，也支持 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（默认值为 30s）达到时停止，而不会让调用一直挂起。
• 消息正文会截断：每条消息最多保留 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	使用 SAS 连接字符串代替 Entra ID
--tenant <id>	AZURE_TENANT_ID	要进行身份验证的 Entra 租户
--search-timeout-ms <n>	BUSSIN_SEARCH_TIMEOUT_MS	单次扫描或清空操作的时限（默认值为 30000）

工具

始终可用

• list_namespaces：该身份在所有订阅中可见的每个 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 消息因一个现已修复的 Bug 失败了，请重新发送它们。

相关项目

• Bussin：本项目基于其构建的浏览器原生 Azure Service Bus 浏览器工具
• app.bussin.dev：Web 应用，无需安装
• 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。