# @msgmesh/mcp-server

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

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

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

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

## 設定

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

```json
{
  "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?

到[面板](https://msgmesh-panel.alderflux.com)註冊後,在 Keys 頁簽發一把。

**建議簽 `admin` scope**:多數治理類 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 各自指向你的服務,例如本機開發:

```json
"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"
}
```

## 工具

目前涵蓋:

- **收發**:`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`(預設只投遞建立之後的訊息;`from: "start"` 才會把保留期內的歷史再投遞並計費)、
  `list_webhooks`、`update_webhook`(就地改網址、不重送——換網址用它,不要刪除重建)、`delete_webhook`
  (刪掉之後 topic 上沒有其他啟用中的 webhook、而死信佇列還有死信時回 `dlq_not_empty` 與筆數,agent 會先問你要保留還是
  一併清除,再帶 `dlq: "keep"` / `"purge"` 重試;topic 上還有停權中的 webhook 時清除會被拒絕〔`dlq_purge_blocked`〕,
  只能保留,agent 會把原因原樣告訴你)
- **函數**:`register_function`、`get_function`、`delete_function`
- **死信**:`dlq_peek`、`dlq_replay`
- 同一個 topic 上**重放死信、清除死信(`delete_webhook` 的 `dlq: "purge"`)、刪 topic 三者互斥**:其中一個正在進行時,
  另外兩個回 `operation_in_progress`(什麼都沒做),agent 會等 Retry-After 秒後重試同一個呼叫,不會改用別的操作繞過
- **其他**:`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),取回的訊息不會再送第二次。

## 相關

- 公開安裝與目錄入口:[`LukeLogix/msgmesh-mcp`](https://github.com/LukeLogix/msgmesh-mcp)
- API 參考(可線上試打):<https://msgmesh-api.alderflux.com/docs>
- TypeScript SDK:[`@msgmesh/sdk`](https://www.npmjs.com/package/@msgmesh/sdk)

## 授權

MIT