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 
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 Server

快速接入

详细介绍

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

`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`