pumble-mcp

git clone https://github.com/nitindermohan/pumble-mcp.git
cd pumble-mcp
npm install

npx pumble-cli login     # Authenticate with your Pumble account
npx pumble-cli create    # Register a new bot app

cp .env.example .env

PUMBLE_APP_ID=your_app_id
PUMBLE_APP_KEY=your_app_key
PUMBLE_APP_CLIENT_SECRET=your_client_secret
PUMBLE_APP_SIGNING_SECRET=your_signing_secret

npx pumble-cli

npm run build
node dist/index.js

{
  "mcpServers": {
    "pumble": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/pumble-mcp"
    }
  }
}

{
  "mcpServers": {
    "pumble": {
      "command": "node",
      "args": ["/absolute/path/to/pumble-mcp/dist/index.js"],
      "cwd": "/absolute/path/to/pumble-mcp"
    }
  }
}

POST http://localhost:3456/mcp
Authorization: Bearer YOUR_TOKEN

  AI Agent                   pumble-mcp                     Pumble
     │                           │                             │
     │── subscribe(NEW_MESSAGE) ─▶│                             │
     │◀── subscription_id ───────│                             │
     │                           │◀── WebSocket: NEW_MESSAGE ──│
     │                           │   (buffered in EventStore)  │
     │── poll(subscription_id) ──▶│                             │
     │◀── [event1, event2] ──────│                             │

// 1. Subscribe to events
pumble_subscribe_events({ event_types: ["NEW_MESSAGE", "REACTION_ADDED"] })
// → { subscription_id: "sub_a1b2c3d4", event_types: [...] }

// 2. Poll periodically
pumble_poll_events({ subscription_id: "sub_a1b2c3d4" })
// → { events: [{ eventType: "NEW_MESSAGE", payload: {...}, ... }], count: 3 }

// 3. Unsubscribe when done
pumble_unsubscribe_events({ subscription_id: "sub_a1b2c3d4" })
// → { unsubscribed: true }

                      ┌──────────────────────────────────────────────┐
                      │                 pumble-mcp                   │
                      │                                              │
  Claude/CLI ──stdio──▶  McpServer ──▶ 33 Tools ──▶ PumbleClient ──▶── Pumble API
                      │      │                          │            │
  N8N/HTTP ───http──▶  McpServer     EventStore ◀── SDK WebSocket ◀─── Pumble Events
                      │              (ring buffer)                   │
                      └──────────────────────────────────────────────┘

{
  "name": "my-custom-bot",
  "displayName": "My Custom Bot",
  "botTitle": "Team Assistant"
}

npx pumble-cli    # Pushes manifest changes to Pumble
# Wait for "App is updated", then Ctrl+C

messages:read    messages:write    messages:edit    messages:delete
channels:list    channels:read    channels:write
users:list       user:read
reaction:read    reaction:write
workspace:read   files:write       attachments:write   status:write

npm run dev           # Run with tsx (hot reload)
npm run build         # Compile TypeScript
npm test              # Run all 175 tests
npm run test:watch    # Watch mode
npm run test:coverage # Code coverage report
npm run typecheck     # Type check without emitting

npm test                              # Unit + integration (no network)
npx tsx tests/live/run-live-tests.ts  # Live tests (requires credentials)

src/
  index.ts              Entry point — boot sequence, console.log redirect
  server.ts             MCP server setup (stdio + Streamable HTTP transports)
  config.ts             Environment validation with Zod schemas
  logger.ts             stderr-only logger (stdout reserved for MCP JSON-RPC)
  main.ts               pumble-cli entry point for event registration
  pumble/
    auth.ts             OAuth2 setup, token mutex, SDK event handler wiring
    client.ts           PumbleClient — unified wrapper for all SDK operations
    resolvers.ts        Smart resolution: #channel-name → ID, email → user ID
  events/
    event-store.ts      Ring buffer (1000 capacity) with subscription-cursor polling
    event-listeners.ts  Bridges SDK event callbacks → EventStore.push()
  tools/
    index.ts            Tool registration hub (routes to all modules below)
    health.ts           pumble_health_check
    channels.ts         5 channel management tools
    users.ts            4 user and bot identity tools
    messages.ts         5 message read tools
    messages-mutate.ts  2 message write tools (edit, delete)
    reactions.ts        2 reaction tools
    dms.ts              2 direct message tools
    files.ts            3 file operation tools (SDK-exclusive)
    search.ts           1 search tool with multi-filter support
    scheduled.ts        4 scheduled message tools
    events.ts           4 real-time event subscription tools
tests/
  setup.ts              Mock PumbleClient and EventStore factories
  unit/                 Pure logic tests — no network, no SDK
  integration/          Full MCP pipeline tests via InMemoryTransport
  live/                 Real Pumble workspace end-to-end tests