@msgmesh/mcp-server

@msgmesh/mcp-server

讓 AI agent 原生訂閱事件流的 MCP server。

MsgMesh 是架在 Kafka 之上的多租戶事件總線。把這個 MCP server 加進 Claude Desktop / Cursor,agent 就能用自然語言收發事件、監看 topic、管理 topic 與 schema—— 你不必為它寫一層事件橋。

「監看 orders 這個 topic,有新訂單就告訴我。」

agent 會呼叫 watch_topic 長輪詢等下一批事件,收到就處理、再繼續等。

設定

加進 Claude Desktop(claude_desktop_config.json)或 Cursor 的 MCP 設定:

{
  "mcpServers": {
    "msgmesh": {
      "command": "npx",
      "args": ["-y", "@msgmesh/mcp-server"],
      "env": {
        "MQ_API_KEY": "<你的 API Key>"
      }
    }
  }
}

只需要一把 key:服務位址預設指向官方託管的 https://msgmesh-api.alderflux.com,自架才需覆寫(見下表)。 不需要事先安裝:npx -y 會在首次啟動時自動取得。

把 <你的 API Key> 連同角括號一起換成面板簽出的 key。沒填、或還留著佔位字串(<...>、 YOUR_API_KEY、mk_xxxxxxxx、$MQ_API_KEY 這類)時,server 會拒絕啟動並在 stderr 印出該 去哪拿 key——不會裝出「已連線」卻在第一次呼叫才吐 401。

還沒有 API Key?

到面板註冊後,在 Keys 頁簽發一把。

建議簽 admin scope:29 個 tool 裡多數是治理類(topic / key / schema / webhook / function / 方案 / 稽核 / 用量),後端要求 admin;producer / consumer key 只能用資料面 (publish_message / consume_messages / watch_topic / get_presence / DLQ)。 權限不足時後端回 403 —— 這時不能叫 agent 用 create_key 自己開通(簽發金鑰本身也需要 admin,只會再被擋一次),請到面板換一把。

拿到 key 之後,可以直接這樣用:

「建一個 support.tickets topic,然後幫我監看它,有新工單就告訴我。」

agent 會呼叫 create_topic → watch_topic,長輪詢等下一批事件。

環境變數

變數	說明	預設
MQ_API_KEY	API Key(必要;缺少或仍是佔位字串則不啟動)。	—
MQ_CONTROL_PLANE_URL	管理 API(建 topic / 簽 key / 查用量)。	https://msgmesh-api.alderflux.com
MQ_GATEWAY_URL	收發 API(publish / consume / DLQ)。	https://msgmesh-api.alderflux.com
MQ_REALTIME_URL	即時服務(get_presence 用)。	https://msgmesh-api.alderflux.com

自架時三個 URL 各自指向你的服務,例如本機開發:

"env": {
  "MQ_API_KEY": "<你的 API Key>",
  "MQ_CONTROL_PLANE_URL": "http://localhost:8080",
  "MQ_GATEWAY_URL": "http://localhost:8081",
  "MQ_REALTIME_URL": "http://localhost:8082"
}

工具

29 個 tool,涵蓋:

• 收發:publish_message、consume_messages、watch_topic(長輪詢等下一批事件—— 「watch → 反應 → 再 watch」的核心)、get_presence
• Topic:create_topic、list_topics、delete_topic
• 金鑰:create_key(支援 capabilities 細粒度能力)、list_keys、delete_key
• Schema:register_schema、get_schema、list_schemas、delete_schema
• Webhook:create_webhook、list_webhooks、delete_webhook
• 函數:register_function、get_function、delete_function
• 死信:dlq_peek、dlq_replay
• 其他:get_usage、get_audit、get_plan、set_plan、get_billing、 get_connection_snippet、get_docs

每個 tool 都帶 MCP annotations,client 可據此自動放行查詢、對會改動狀態的操作要求確認。 注意 consume_messages / watch_topic / dlq_peek 不是唯讀:它們會提交 consumer group 位移(at-most-once),取回的訊息不會再送第二次。

相關

• API 參考(可線上試打):https://msgmesh-api.alderflux.com/docs
• TypeScript SDK:@msgmesh/sdk

授權

MIT