Name: Pumble MCP服务器
Author: shoutkol

使用说明

Pumble MCP服务器

Pumble的模型上下文协议（MCP）服务器，使用测试驱动开发（TDD）使用TypeScript构建。

📦 发布于npm： @shoutkol/pumpble mcp服务器

概述

此MCP服务器可与Pumble的API集成，允许您通过兼容MCP的客户端发送消息、管理频道、对消息做出反应，并与您的Pumble工作空间进行交互。

先决条件

Node.js（v18或更高版本）
可泵API钥匙（参见 API密钥设置)

安装

使用npm（推荐）

该包发布在npm上： @shoutkol/pumpble mcp服务器

无需安装！直接与 npx:

npx -y @shoutkol/pumble-mcp-server

或全局安装：

npm install -g @shoutkol/pumble-mcp-server

地方发展

为了地方发展和贡献：

# Clone the repository
git clone https://github.com/shoutkol/pumble-mcp-server.git
cd pumble-mcp-server

# Install dependencies
pnpm install

# Build the project
pnpm build

API密钥设置

要使用此MCP服务器，您需要一个Pumble API密钥。通过以下方式生成一个：

在您的Pumble工作空间中安装API应用程序
打字 /api-keys generate 在任何Pumble频道
从暂时消息中复制生成的API密钥

配置

API密钥可以通过两种方式提供：

MCP服务器配置 （推荐）：在MCP客户端配置中提供API密钥：

{
  "mcpServers": {
    "pumble": {
      "command": "npx",
      "args": ["-y", "@shoutkol/pumble-mcp-server"],
      "initializationOptions": {
        "apiKey": "your-api-key-here"
      }
    }
  }
}

环境变量：设置 PUMBLE_API_KEY 环境变量：
```
export PUMBLE_API_KEY="your-api-key-here"
```
然后将其与以下内容一起使用：
```
npx -y @shoutkol/pumble-mcp-server
```

发展

# Run in development mode with hot reload
pnpm dev

# Build the project
pnpm build

# Run the built server
pnpm start

# Watch mode for building
pnpm watch

# Run tests
pnpm test

# Run tests in watch mode
pnpm test:watch

MCP检验员测试

您可以使用MCP检查器交互式地测试MCP服务器。要使用API密钥运行它，请执行以下操作：

选项1：内联（单个命令）

PUMBLE_API_KEY="your-api-key-here" npx @modelcontextprotocol/inspector -- tsx src/index.ts

选项2：先导出，然后运行

export PUMBLE_API_KEY="your-api-key-here"
npx @modelcontextprotocol/inspector -- tsx src/index.ts

选项3：使用dotenv-cli

创建一个 .env 项目根目录中的文件：

PUMBLE_API_KEY=your-api-key-here

然后运行：

# Install dotenv-cli if needed: pnpm add -D dotenv-cli
npx dotenv-cli npx @modelcontextprotocol/inspector -- tsx src/index.ts

检查员将打开一个web界面 http://localhost:6274 您可以在哪里：

查看所有可用工具
交互式测试工具调用
查看请求/响应详细信息
调试API交互

注：替换 "your-api-key-here" 使用您的实际Pumble API密钥（使用生成 /api-keys generate 在Pumble）。

测试

该项目使用测试驱动开发（TDD）和Vitest。测试位于 src/__tests__/.

运行测试

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

TDD工作流程

该项目遵循红绿重构周期：

红：首先编写定义所需功能的测试
绿色：实现最少的代码以使测试通过
重构：在保持测试绿色的同时改进代码

可用工具

`pumble_validate_api_key`

通过进行测试API调用来验证Pumble API密钥。

参数： 无

例子：

{
  "tool": "pumble_validate_api_key",
  "arguments": {}
}

`pumble_send_message`

向Pumble频道发送消息。

参数：

text （string，必填）：要发送的消息文本
channel （字符串，可选）：频道名称（使用 channel 或 channelId)
channelId （字符串，可选）：通道ID（使用 channel 或 channelId)
asBot （布尔值，可选）：是否以机器人模式发送消息（默认值： true)

例子：

{
  "tool": "pumble_send_message",
  "arguments": {
    "text": "Hello from MCP!",
    "channel": "general",
    "asBot": true
  }
}

`pumble_send_reply`

回复Pumble频道中的特定消息。

参数：

text （string，必填）：回复文本
messageId （string，必填）：要回复的消息的ID
channel （字符串，可选）：频道名称（使用 channel 或 channelId)
channelId （字符串，可选）：通道ID（使用 channel 或 channelId)
asBot （布尔值，可选）：是否以机器人模式发送回复（默认值： true)

例子：

{
  "tool": "pumble_send_reply",
  "arguments": {
    "text": "This is a reply",
    "messageId": "65c4ba025f3c124940579c7f",
    "channel": "general",
    "asBot": true
  }
}

`pumble_add_reaction`

在消息中添加表情符号反应。

参数：

messageId （string，必填）：要响应的消息的ID
reaction （字符串，必需）：表情符号反应码（例如。， :grin:)

例子：

{
  "tool": "pumble_add_reaction",
  "arguments": {
    "messageId": "65c4a8ab99f15a6b2150e0f0",
    "reaction": ":grin:"
  }
}

`pumble_create_channel`

在Pumble中创建一个新频道。

参数：

name （string，必填）：频道名称
type （string，必填）：通道类型(PUBLIC 或 PRIVATE)
description （字符串，可选）：可选频道描述

例子：

{
  "tool": "pumble_create_channel",
  "arguments": {
    "name": "my-new-channel",
    "type": "PUBLIC",
    "description": "A new channel created via MCP"
  }
}

`pumble_delete_message`

从Pumble频道删除消息。

参数：

messageId （string，必填）：要删除的消息的ID
channel （字符串，可选）：频道名称（使用 channel 或 channelId)
channelId （字符串，可选）：通道ID（使用 channel 或 channelId)

例子：

{
  "tool": "pumble_delete_message",
  "arguments": {
    "messageId": "65c4ba025f3c124940579c7f",
    "channel": "general"
  }
}

`pumble_list_messages`

在Pumble频道中列出消息。

参数：

channel （字符串，可选）：频道名称（使用 channel 或 channelId)
channelId （字符串，可选）：通道ID（使用 channel 或 channelId)
cursor （字符串，可选）：用于分页的可选光标
limit （number，可选）：消息数量的可选限制

例子：

{
  "tool": "pumble_list_messages",
  "arguments": {
    "channel": "general",
    "limit": 50
  }
}

`pumble_list_channels`

列出工作区中的所有频道和DM。

参数： 无

例子：

{
  "tool": "pumble_list_channels",
  "arguments": {}
}

`pumble_list_users`

列出工作区中的所有用户。

参数： 无

例子：

{
  "tool": "pumble_list_users",
  "arguments": {}
}

用法

此MCP服务器可以与MCP兼容的客户端一起使用。在MCP客户端设置中配置它以使用stdio传输。

通过npm（npx）安装

一旦发布到npm，用户可以直接运行此MCP服务器，而无需安装它：

npx -y @shoutkol/pumble-mcp-server

或者使用API密钥：

PUMBLE_API_KEY="your-api-key-here" npx -y @shoutkol/pumble-mcp-server

克劳德桌面

查找您的Claude Desktop配置文件：
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- 视窗: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
添加Pumble MCP服务器配置：

使用npx（推荐）：

{
  "mcpServers": {
    "pumble": {
      "command": "npx",
      "args": ["-y", "@shoutkol/pumble-mcp-server"],
      "initializationOptions": {
        "apiKey": "your-pumble-api-key"
      }
    }
  }
}

使用本地安装：

{
  "mcpServers": {
    "pumble": {
      "command": "node",
      "args": ["/absolute/path/to/pumble-mcp-server/dist/index.js"],
      "initializationOptions": {
        "apiKey": "your-pumble-api-key"
      }
    }
  }
}

使用环境变量：

{
  "mcpServers": {
    "pumble": {
      "command": "npx",
      "args": ["-y", "@shoutkol/pumble-mcp-server"],
      "env": {
        "PUMBLE_API_KEY": "your-pumble-api-key"
      }
    }
  }
}

重新启动克劳德桌面 加载新配置。
验证连接： 打开Claude Desktop，检查MCP工具列表中是否有Pumble工具。

Cline（VS代码扩展）

安装Cline 来自VS Code市场。
打开VS代码设置 （Cmd/Ctrl+，）并搜索“Cline”。
添加MCP服务器配置 在您的VS代码设置.json中：

{
  "cline.mcpServers": {
    "pumble": {
      "command": "npx",
      "args": ["-y", "@shoutkol/pumble-mcp-server"],
      "env": {
        "PUMBLE_API_KEY": "your-pumble-api-key"
      }
    }
  }
}

重新加载VS代码 以激活配置。

其他MCP客户端

对于其他兼容MCP的客户端，请使用stdio传输配置服务器：

命令: npx （或 node 用于本地安装）
参数: ["-y", "@shoutkol/pumble-mcp-server"] （或 ["/path/to/dist/index.js"] 本地）
API密钥：通过提供 initializationOptions.apiKey 或 PUMBLE_API_KEY 环境变量

使用工具

配置后，您可以通过MCP客户端使用Pumble工具：

发送消息 到频道
回复消息 在线程中
添加反应 到消息
创建频道 （公共或私人）
列出频道、用户和消息
删除消息

这些工具将出现在MCP客户端的工具列表中，可以通过自然语言或直接工具调用调用。

部署

本地部署

先决条件：

Node.js v18或更高版本
全球安装的pnpm

步骤：

克隆或下载存储库：

git clone <repository-url>
cd pumble-mcp-server

安装依赖项：

pnpm install

构建项目：

pnpm build

设置API密钥：

export PUMBLE_API_KEY="your-api-key-here"

运行服务器：

pnpm start

服务器在stdio传输上运行，并通过标准输入/输出与MCP客户端通信。

发布到npm

使能够 npx 用法，将包发布到npm：

手动发布：

构建项目：
```
pnpm build
```
登录到npm：
```
npm login
```
发布：
```
npm publish
```
验证它是否有效：
```
npx -y @shoutkol/pumble-mcp-server
```

使用GitHub操作自动发布：

该存储库包括一个GitHub Actions工作流，用于自动发布到npm：

设置npm令牌：
- 首选https://www.npmjs.com/settings/shoutkol/packages
- 创建“自动化”访问令牌
- 将其添加为名为的秘密 NPM_TOKEN 在GitHub存储库设置中：
  - 转到：设置→ 秘密和变量→ 行动
  - 点击“新建存储库密钥”
  - 姓名： NPM_TOKEN
  - 价值：你的npm自动化令牌
  - 点击“添加秘密”
创建发布：
- 首选https://github.com/shoutkol/pumble-mcp-server/releases/new
- 创建具有版本标签的新版本（例如。， v0.1.0)
- 工作流将自动执行以下操作：
  - 运行测试
  - 构建项目
  - 发布到npm注册表https://www.npmjs.com/settings/shoutkol/packages
手动触发：
- 转到操作→ 发布到npm→ 运行工作流
- 输入版本号并运行

工作流程确保只有经过测试和构建的代码才会发布到npm。

生产注意事项

安全：
- 永远不要将API密钥提交到版本控制
- 使用环境变量或秘密管理服务
- 考虑使用不同的API密钥进行开发和生产
监控：
- 为API调用和错误添加日志记录
- 监控API速率限制
- 设置故障警报
演出
- 服务器是轻量级的，在stdio上运行
- 无HTTP服务器开销
- 如果处理多个客户端，请考虑连接池
缩放比例：
- MCP服务器通常为每个客户端连接运行一个实例
- 对于多个客户端，运行多个实例
- 考虑使用PM2等流程管理器进行本地部署

环境变量

变量	描述	必填
`PUMBLE_API_KEY`	您的Pumble API密钥	是

故障排除

服务器无法启动：

验证Node.js版本（v18+）
检查一下 dist/index.js 存在（运行 pnpm build)
验证API密钥设置是否正确

工具未出现：

检查MCP客户端日志中的连接错误
验证配置中的服务器路径是否为绝对路径（如果使用本地安装）
确保服务器进程具有执行权限

API错误：

使用验证API密钥 pumble_validate_api_key 工具
检查API费率限制
验证与Pumble API的网络连接

连接问题：

确保stdio传输配置正确
检查服务器进程是否正在运行
查看MCP客户端日志以了解详细的错误消息

CI/CD

本项目使用GitHub Actions进行持续集成和部署：

工作流

CI(ci.yml)：对每个推送和拉取请求运行
- 运行测试
- 构建项目
- 类型检查代码
发布到npm(publish-npm.yml)：在发布时运行
- 运行测试
- 构建项目
- 发布到npm注册表https://www.npmjs.com/settings/shoutkol/packages

设置自动发布

创建npm访问令牌：
- 首选https://www.npmjs.com/settings/shoutkol/packages
- 创建新的“自动化”访问令牌
- 复制令牌
将secret添加到GitHub：
- 转到您的存储库→ 设置→ 秘密和变量→ 行动
- 点击“新建存储库密钥”
- 姓名： NPM_TOKEN
- 值：你的npm令牌
- 点击“添加秘密”
创建发布：
- 转到发布→ 创建新版本
- 标签： v1.0.0 （或您的版本）
- 标题： Release v1.0.0
- 说明：发行说明
- 点击“发布发布”
- 工作流将自动发布到npm

项目结构

.
├── .github/
│   └── workflows/
│       ├── ci.yml              # CI workflow
│       └── publish-npm.yml    # npm publishing workflow
├── src/
│   ├── index.ts               # Main server entry point
│   ├── pumble-client.ts       # Pumble API client
│   └── __tests__/
│       └── index.test.ts      # Test suite
├── dist/                      # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
├── vitest.config.ts          # Vitest configuration
└── README.md

错误处理

服务器提供全面的错误处理：

缺少API密钥：如果未配置API密钥，则清除错误消息
API错误：来自Pumble API的带有状态代码的详细错误消息
网络错误：优雅地处理网络故障
无效参数：验证所需参数并提供有用的错误消息

API 参考

此服务器与Pumble API插件集成。有关Pumble API的更多信息，请参阅官方文件.

基本URL: https://pumble-api-keys.addons.marketplace.cake.com

身份验证： 所有请求都使用 Api-Key 头与您生成的API密钥。

Docker部署

此MCP服务器可以部署为具有HTTP/Streamable HTTP传输支持的Docker容器，类似于 gitlab mcp.

构建Docker镜像

docker build -t pumble-mcp-server .

使用Docker运行

docker run -i --rm \
  -p 3000:3000 \
  -e PUMBLE_API_KEY=your-api-key \
  pumble-mcp-server

服务器将在以下位置可用：

可流式传输的HTTP端点: http://localhost:3000/mcp
健康检查: http://localhost:3000/health

使用HTTP传输

HTTP服务器使用Streamable HTTP传输，这允许MCP客户端通过HTTP而不是stdio进行连接。

Claude桌面配置

{
  "mcpServers": {
    "pumble": {
      "type": "streamable-http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key"
      }
    }
  }
}

临床（VS代码）配置

{
  "cline.mcpServers": {
    "pumble": {
      "type": "streamable-http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

备注：对于HTTP传输，设置 PUMBLE_API_KEY Docker容器中的环境变量或通过 Authorization 头球

部署到Docker Hub

登录Docker Hub:
```
docker login
```

设置您的Docker Hub用户名:

export DOCKER_USERNAME=your-dockerhub-username

使用脚本构建和推送:

./deploy-dockerhub.sh

或手动：

# Build the image
docker build -t your-username/pumble-mcp-server:latest .

# Push to Docker Hub
docker push your-username/pumble-mcp-server:latest

从Docker Hub运行:

docker run -p 3000:3000 \
  -e PUMBLE_API_KEY=your-api-key \
  your-username/pumble-mcp-server:latest

部署到Google Cloud Run

设置环境变量:

export GCP_PROJECT_ID=your-project-id
export PUMBLE_API_KEY=your-api-key

使用脚本进行部署:

./deploy-gcp.sh

或手动：

# Build and push
docker build -t gcr.io/YOUR_PROJECT_ID/pumble-api-server .
docker push gcr.io/YOUR_PROJECT_ID/pumble-api-server

# Deploy to Cloud Run
gcloud run deploy pumble-api-server \
  --image gcr.io/YOUR_PROJECT_ID/pumble-api-server \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars PUMBLE_API_KEY=your-api-key \
  --port 3000

运行模式

服务器支持两种模式：

标准模式 （默认）：适用于本地MCP客户端
```
pnpm start
# or
node dist/index.js
```
HTTP模式：用于远程访问和Docker部署
```
pnpm start:http
# or
node dist/http-server.js
```

许可证

麻省理工学院

使用说明

Pumble MCP服务器

概述

先决条件

安装

使用npm（推荐）

地方发展

API密钥设置

配置

发展

MCP检验员测试

测试

运行测试

TDD工作流程

可用工具

pumble_validate_api_key

pumble_send_message

pumble_send_reply

pumble_add_reaction

pumble_create_channel

pumble_delete_message

pumble_list_messages

pumble_list_channels

pumble_list_users

用法

通过npm（npx）安装

克劳德桌面

Cline（VS代码扩展）

其他MCP客户端

使用工具

部署

本地部署

发布到npm

生产注意事项

环境变量

故障排除

CI/CD

工作流

设置自动发布

项目结构

错误处理

API 参考

Docker部署

构建Docker镜像

使用Docker运行

使用HTTP传输

Claude桌面配置

临床（VS代码）配置

部署到Docker Hub

部署到Google Cloud Run

运行模式

许可证

相关 MCP

AKShare One MCP 股市数据服务

实时网络搜索服务

arXiv 论文检索 MCP 服务器

移动自动化MCP服务器

AI持久记忆服务器

Git仓库管理MCP服务器

`pumble_validate_api_key`

`pumble_send_message`

`pumble_send_reply`

`pumble_add_reaction`

`pumble_create_channel`

`pumble_delete_message`

`pumble_list_messages`

`pumble_list_channels`

`pumble_list_users`