内容
# pumble-mcp
一款小型MCP服务器，封装了Pumble的"API密钥插件"的REST API，为Claude Code提供了六种工具：发送消息、列出频道消息、编辑消息、列出频道、发送直接消息和列出工作区用户。详细设计请参见`SPEC.md`。
> **安全注意事项：** 您配置的Pumble API密钥授予了广泛的工作区访问权限。请在安装前阅读[安全/权限](#安全权限)部分。
## 1. 获取Pumble API密钥
1. 在您的Pumble工作区中，安装**API密钥**插件（应用/集成）。
2. 从插件设置中生成密钥。Pumble会将其显示为一次性的临时消息 — 立即复制。
## 2. 配置密钥
```bash
cp .env.example .env
# 编辑.env并设置PUMBLE_API_KEY=<您的密钥>
```
`.env` 文件被 gitignore — 永不提交。如果您更喜欢为 shell全局设置它（这样任何工具都可以在没有 `.env` 文件的情况下使用），请添加到 `~/.bashrc`：
```bash
export PUMBLE_API_KEY="<您的密钥>"
```
## 3. 安装、构建
```bash
npm install
npm run build
```
## 4. 在Claude Code中注册
使用您机器上构建入口点的绝对路径，将其注册为MCP服务器。从项目根目录运行，以便 `$(pwd)` 正确解析：
```bash
claude mcp add pumble --env PUMBLE_API_KEY="$PUMBLE_API_KEY" -- node "$(pwd)/dist/index.js"
```
这会在Claude Code的MCP服务器配置中写入 `pumble` 条目，以便未来的会话自动具有所有六种工具，就像Slack的工具显示为 `mcp__plugin_slack_slack__*` 一样。
验证是否已注册：
```bash
claude mcp list
```
## 开发
```bash
npm run dev # 监视模式
npm run typecheck # tsc --noEmit
npm test # vitest
```
## 工具
| 工具 | Pumble 端点 | 备注 |
|---|---|---|
| `pumble_send_message` | `POST /sendMessage` | `channel` 或 `channelId`（两者选一），`text`，`asBot`（默认为 `false` — 以您的用户身份发布） |
| `pumble_list_messages` | `GET /listMessages` | `channel` 或 `channelId`（两者选一），可选 `cursor`/`limit`；返回 `{ hasMoreAfter, hasMoreBefore, messages }` |
| `pumble_edit_message` | `POST /editMessage` | `messageId`，`channelId`，`text` |
| `pumble_list_channels` | `GET /listChannels` | 无输入；返回密钥可见的每个频道，**包括DM（`channelType DIRECT`）和群组DM频道** |
| `pumble_send_dm` | `POST /dmUser` | `userId` 或 `email`（两者选一），`text` |
| `pumble_list_users` | `GET /listUsers` | 无输入；返回每个工作区成员的 `id`，`name`，`email` |
## 安全/权限
此服务器向Claude Code可以调用的MCP服务器提供一个静态的Pumble API密钥。请在安装前了解其影响范围：
- API密钥继承了生成它的Pumble用户的完全可见性和权限。它是一个**与密码等效的密钥**。
- 使用这六种工具，任何能够调用此服务器的人（包括任何配置了它的Claude会话），都可以**以您的身份**：
- 读取、发送和编辑**密钥可见的任何频道中的消息**；
- 向任何用户发送直接消息（`pumble_send_dm`）；
- 列出**每个工作区成员的名称和电子邮件**（`pumble_list_users`）；
- 读取**DM历史记录** — `pumble_list_channels` 返回DM频道（`channelType DIRECT`），其 `channelId` 提供给 `pumble_list_messages`。
- 没有每个工具的作用域，也没有只读模式：一个密钥意味着跨频道、DM和用户目录的完全读写权限。
建议：
- 永不提交 `.env`（它被 gitignore）。不要将密钥粘贴到日志、问题或聊天中。
- 如果密钥曾经暴露，请轮换它：在API密钥插件中生成新密钥，更新 `.env`，确认其有效，然后撤销旧密钥。
- 如果您的工作区允许，请从专用的、权限最小的服务帐户生成密钥，而不是从具有完全管理员权限的用户。
