@coldbirds/mcp-server 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,594 @@
+# @coldbirds/mcp-server
+
+> **Control your ColdBirds Sequence cold-email workspace from any AI assistant that speaks the [Model Context Protocol](https://modelcontextprotocol.io).**
+
+Manage campaigns, contacts, mailboxes, enrollments, events, and webhooks by chatting with Claude Desktop, Cursor, Windsurf, Cline, Continue, or any custom MCP client — no manual API calls, no clicking through the UI.
+
+[![npm version](https://img.shields.io/npm/v/@coldbirds/mcp-server.svg)](https://www.npmjs.com/package/@coldbirds/mcp-server)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Node ≥18](https://img.shields.io/badge/node-%E2%89%A518-brightgreen)](https://nodejs.org)
+
+---
+
+## Table of Contents
+
+1. [What you get](#what-you-get)
+2. [Prerequisites](#prerequisites)
+3. [Quick start (60 seconds)](#quick-start-60-seconds)
+4. [Integration guides](#integration-guides)
+   - [Claude Desktop](#-claude-desktop)
+   - [Cursor](#-cursor)
+   - [Windsurf](#-windsurf)
+   - [Cline (VS Code)](#-cline-vs-code)
+   - [Continue (VS Code / JetBrains)](#-continue-vs-code--jetbrains)
+   - [Zed](#-zed)
+   - [Custom / CLI clients](#-custom--cli-clients)
+5. [Available tools](#available-tools)
+6. [Example prompts](#example-prompts)
+7. [Real-world use cases](#real-world-use-cases)
+8. [Configuration reference](#configuration-reference)
+9. [Troubleshooting](#troubleshooting)
+10. [How it works](#how-it-works)
+11. [Security notes](#security-notes)
+12. [Contributing](#contributing)
+
+---
+
+## What you get
+
+After installing this server, your AI assistant gains **40 typed tools** for ColdBirds Sequence:
+
+| Surface | Examples |
+|---|---|
+| **Campaigns** | list, get, pause, resume, duplicate, update settings, intelligence, variables |
+| **Steps** | list / create / update / delete steps in a sequence |
+| **Contacts** | list, get, create, update, delete + lists & list-membership |
+| **Enrollments** | enroll, list, pause/resume per-contact |
+| **Mailboxes** | list, get, create, update, delete sender mailboxes |
+| **Events** | list opens / clicks / replies / bounces / unsubscribes |
+| **Webhooks** | list, get, test |
+| **Account** | who-am-I |
+
+Each tool is backed by the official [ColdBirds public REST API](https://sequencer.coldbirds.com/api/docs) and uses the same authentication and rate limits as the dashboard.
+
+---
+
+## Prerequisites
+
+- **Node.js 18+** (run `node -v` to check)
+- **A ColdBirds account** — sign up free at [coldbirds.com](https://coldbirds.com)
+- **An API key** — generate one in [Settings → API Keys](https://sequencer.coldbirds.com/settings/api). Format: `sk_live_...`
+
+> Keys are workspace-scoped. The MCP server can only see / modify resources owned by the workspace that issued the key.
+
+---
+
+## Quick start (60 seconds)
+
+Install globally and verify the server starts:
+
+```bash
+npm install -g @coldbirds/mcp-server
+COLDBIRDS_API_KEY="sk_live_..." coldbirds-mcp
+```
+
+Or run on-demand without installing (recommended for MCP clients — they spawn a fresh process per session):
+
+```bash
+npx -y @coldbirds/mcp-server
+```
+
+You should see the server idle on stdio. Press `Ctrl+C` to stop. Now wire it into the AI client of your choice — see [Integration guides](#integration-guides).
+
+---
+
+## Integration guides
+
+> Every client below uses the same launch command: `npx -y @coldbirds/mcp-server`, with `COLDBIRDS_API_KEY` injected via environment.
+
+### 🤖 Claude Desktop
+
+**Config file path:**
+
+| OS | Path |
+|---|---|
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Linux | `~/.config/Claude/claude_desktop_config.json` |
+
+Add a `mcpServers` entry:
+
+```json
+{
+  "mcpServers": {
+    "coldbirds": {
+      "command": "npx",
+      "args": ["-y", "@coldbirds/mcp-server"],
+      "env": {
+        "COLDBIRDS_API_KEY": "sk_live_..."
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. Click the **🔌 plug icon** in the chat input — you should see `coldbirds` listed with 40 tools available.
+
+---
+
+### ⚡ Cursor
+
+Open **Settings → Cursor Settings → MCP** (or edit `~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "coldbirds": {
+      "command": "npx",
+      "args": ["-y", "@coldbirds/mcp-server"],
+      "env": {
+        "COLDBIRDS_API_KEY": "sk_live_..."
+      }
+    }
+  }
+}
+```
+
+Reload Cursor. In Composer / Chat, type `@coldbirds` to invoke tools manually, or just ask in plain English ("pause the Q3 outreach campaign") — Cursor will pick the right tool automatically.
+
+---
+
+### 🌊 Windsurf
+
+Edit `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "coldbirds": {
+      "command": "npx",
+      "args": ["-y", "@coldbirds/mcp-server"],
+      "env": {
+        "COLDBIRDS_API_KEY": "sk_live_..."
+      }
+    }
+  }
+}
+```
+
+Restart Windsurf. Tools appear in Cascade's tool picker.
+
+---
+
+### 🧩 Cline (VS Code)
+
+Install the [Cline extension](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev), then open the Cline panel → **MCP Servers** → **Edit Config**:
+
+```json
+{
+  "mcpServers": {
+    "coldbirds": {
+      "command": "npx",
+      "args": ["-y", "@coldbirds/mcp-server"],
+      "env": {
+        "COLDBIRDS_API_KEY": "sk_live_..."
+      },
+      "disabled": false,
+      "autoApprove": []
+    }
+  }
+}
+```
+
+> Leave `autoApprove: []` so destructive tools (`delete_contact`, `pause_campaign`, etc.) require an explicit confirmation click.
+
+---
+
+### 🔧 Continue (VS Code / JetBrains)
+
+Edit `~/.continue/config.json` and add to the `mcpServers` array:
+
+```json
+{
+  "mcpServers": [
+    {
+      "name": "coldbirds",
+      "command": "npx",
+      "args": ["-y", "@coldbirds/mcp-server"],
+      "env": {
+        "COLDBIRDS_API_KEY": "sk_live_..."
+      }
+    }
+  ]
+}
+```
+
+Reload Continue (`Cmd+Shift+P` → **Continue: Reload**).
+
+---
+
+### 📝 Zed
+
+Open `~/.config/zed/settings.json` and add:
+
+```json
+{
+  "context_servers": {
+    "coldbirds": {
+      "command": {
+        "path": "npx",
+        "args": ["-y", "@coldbirds/mcp-server"],
+        "env": {
+          "COLDBIRDS_API_KEY": "sk_live_..."
+        }
+      }
+    }
+  }
+}
+```
+
+Restart Zed. Use `/coldbirds` in the assistant panel.
+
+---
+
+### 🛠 Custom / CLI clients
+
+Any client that supports the MCP **stdio transport** will work. Spawn the server like this:
+
+```ts
+import { spawn } from "node:child_process";
+
+const server = spawn("npx", ["-y", "@coldbirds/mcp-server"], {
+  env: { ...process.env, COLDBIRDS_API_KEY: "sk_live_..." },
+  stdio: ["pipe", "pipe", "inherit"],
+});
+
+// Speak JSON-RPC 2.0 over server.stdin / server.stdout
+```
+
+Or use the official SDK directly:
+
+```ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const transport = new StdioClientTransport({
+  command: "npx",
+  args: ["-y", "@coldbirds/mcp-server"],
+  env: { COLDBIRDS_API_KEY: process.env.COLDBIRDS_API_KEY! },
+});
+
+const client = new Client({ name: "my-app", version: "1.0.0" });
+await client.connect(transport);
+
+const tools = await client.listTools();
+console.log(tools.tools.map((t) => t.name)); // 40 tool names
+
+const result = await client.callTool({
+  name: "list_campaigns",
+  arguments: { limit: 10, status: "ACTIVE" },
+});
+console.log(result.content);
+```
+
+For interactive exploration, install the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
+
+```bash
+npx @modelcontextprotocol/inspector npx -y @coldbirds/mcp-server
+```
+
+This opens a browser UI where you can call every tool and inspect inputs/outputs.
+
+---
+
+## Available tools
+
+40 tools, grouped by surface. Every tool's `inputSchema` is strict — unknown keys are rejected so your assistant gets accurate validation errors.
+
+<details>
+<summary><b>👤 Account (1)</b></summary>
+
+| Tool | Method | Path |
+|---|---|---|
+| `get_account` | GET | `/api/v1/me` |
+
+</details>
+
+<details>
+<summary><b>📣 Campaigns (10)</b></summary>
+
+| Tool | Method | Path |
+|---|---|---|
+| `list_campaigns` | GET | `/api/v1/campaigns` |
+| `get_campaign` | GET | `/api/v1/campaigns/{id}` |
+| `update_campaign` | PATCH | `/api/v1/campaigns/{id}` |
+| `pause_campaign` | POST | `/api/v1/campaigns/{id}/pause` |
+| `resume_campaign` | POST | `/api/v1/campaigns/{id}/resume` |
+| `duplicate_campaign` | POST | `/api/v1/campaigns/{id}/duplicate` |
+| `get_campaign_stats` | GET | `/api/v1/campaigns/{id}/stats` |
+| `get_campaign_settings` | GET | `/api/v1/campaigns/{id}/settings` |
+| `update_campaign_settings` | PATCH | `/api/v1/campaigns/{id}/settings` |
+| `get_campaign_intelligence` | GET | `/api/v1/campaigns/{id}/intelligence` |
+| `update_campaign_intelligence` | PATCH | `/api/v1/campaigns/{id}/intelligence` |
+
+</details>
+
+<details>
+<summary><b>🪜 Steps (4)</b></summary>
+
+| Tool | Method | Path |
+|---|---|---|
+| `list_campaign_steps` | GET | `/api/v1/campaigns/{campaignId}/steps` |
+| `create_campaign_step` | POST | `/api/v1/campaigns/{campaignId}/steps` |
+| `update_campaign_step` | PATCH | `/api/v1/campaigns/{campaignId}/steps/{stepId}` |
+| `delete_campaign_step` | DELETE | `/api/v1/campaigns/{campaignId}/steps/{stepId}` |
+
+</details>
+
+<details>
+<summary><b>👥 Contacts & Lists (9)</b></summary>
+
+| Tool | Method | Path |
+|---|---|---|
+| `list_contacts` | GET | `/api/v1/contacts` |
+| `get_contact` | GET | `/api/v1/contacts/{id}` |
+| `create_contact` | POST | `/api/v1/contacts` |
+| `update_contact` | PATCH | `/api/v1/contacts/{id}` |
+| `delete_contact` | DELETE | `/api/v1/contacts/{id}` |
+| `list_contact_lists` | GET | `/api/v1/lists` |
+| `create_contact_list` | POST | `/api/v1/lists` |
+| `list_contacts_in_list` | GET | `/api/v1/lists/{listId}/contacts` |
+| `remove_contact_from_list` | DELETE | `/api/v1/lists/{listId}/contacts/{contactId}` |
+
+</details>
+
+<details>
+<summary><b>📬 Enrollments (5)</b></summary>
+
+| Tool | Method | Path |
+|---|---|---|
+| `enroll_contacts` | POST | `/api/v1/campaigns/{campaignId}/enrollments` |
+| `list_enrollments` | GET | `/api/v1/campaigns/{campaignId}/enrollments` |
+| `get_enrollment` | GET | `/api/v1/enrollments/{id}` |
+| `pause_enrollment` | POST | `/api/v1/enrollments/{id}/pause` |
+| `resume_enrollment` | POST | `/api/v1/enrollments/{id}/resume` |
+
+</details>
+
+<details>
+<summary><b>📮 Mailboxes (5)</b></summary>
+
+| Tool | Method | Path |
+|---|---|---|
+| `list_mailboxes` | GET | `/api/v1/mailboxes` |
+| `get_mailbox` | GET | `/api/v1/mailboxes/{id}` |
+| `create_mailbox` | POST | `/api/v1/mailboxes` |
+| `update_mailbox` | PATCH | `/api/v1/mailboxes/{id}` |
+| `delete_mailbox` | DELETE | `/api/v1/mailboxes/{id}` |
+
+</details>
+
+<details>
+<summary><b>📊 Events & Webhooks (4)</b></summary>
+
+| Tool | Method | Path |
+|---|---|---|
+| `list_events` | GET | `/api/v1/events` |
+| `list_webhooks` | GET | `/api/v1/webhooks` |
+| `get_webhook` | GET | `/api/v1/webhooks/{id}` |
+| `test_webhook` | POST | `/api/v1/webhooks/{id}/test` |
+
+</details>
+
+<details>
+<summary><b>🧩 Misc (1)</b></summary>
+
+| Tool | Method | Path |
+|---|---|---|
+| `get_campaign_variables` | GET | `/api/v1/campaigns/{campaignId}/variables` |
+
+</details>
+
+The live, machine-readable tool catalogue lives at **<https://sequencer.coldbirds.com/mcp.json>**.
+
+---
+
+## Example prompts
+
+Just talk to your assistant in plain English. It will pick the right tool, ask for confirmation on destructive actions, and chain calls when needed.
+
+### 🔎 Insights
+
+> "Show me my top 5 campaigns by reply rate this month."
+
+> "Which mailboxes had deliverability issues in the last 7 days?"
+
+> "Summarise opens, clicks, and replies for the Q3 founder outreach campaign."
+
+> "Pull the 10 most recent bounces and group them by mailbox."
+
+### ✏️ Campaign management
+
+> "Pause all campaigns sending from `dharm@coldbirds.com` — that mailbox needs a break."
+
+> "Duplicate the 'SaaS CEOs - Cycle 4' campaign, rename to 'Cycle 5', and update step 2's subject to 'One quick question, {{first_name}}'."
+
+> "In the 'Series A Founders' sequence, change the wait between step 3 and step 4 from 3 days to 5 business days."
+
+> "Show me the variables available in campaign `cmp_abc123` and tell me which ones are unused in any step."
+
+### 👥 Contact ops
+
+> "Find every contact at `acme.com` and add them to the list 'ACME — Q3 push'."
+
+> "Create a new contact: Jane Doe, jane@example.com, CTO at Example Corp, then enroll her in campaign `cmp_xyz789` starting today."
+
+> "Delete contact `con_def456` — they unsubscribed via reply."
+
+### 📮 Mailbox ops
+
+> "List all mailboxes that aren't currently warming up."
+
+> "Update the daily-send-limit on every mailbox tagged `tier-1-senders` to 80."
+
+> "Connect a new SMTP mailbox: smtp.fastmail.com:465, user `outreach@mybrand.com`, then send a test."
+
+### 🛠 Webhook / integrations
+
+> "List my webhooks. For each, run `test_webhook` and report which ones don't return 200."
+
+### 🧠 Agentic workflows
+
+> "Every Monday at 9am, summarise last week's campaign performance, pause anything with <2% reply rate, and post a one-paragraph standup to my notes."
+
+> "I'm replying to a prospect. Pull their enrollment history, last event, and the original cold email I sent so I have full context."
+
+---
+
+## Real-world use cases
+
+### 1. Morning ops standup (read-only)
+
+> "Give me a 5-bullet brief: total sends yesterday, reply rate, any mailbox health alerts, top 3 replied campaigns, and any contacts that bounced more than once this week."
+
+The assistant chains `list_campaigns` → `get_campaign_stats` → `list_mailboxes` → `list_events?type=BOUNCED` and assembles a report in seconds.
+
+### 2. Reply triage from your inbox
+
+Pair the MCP server with a Gmail / Outlook tool in the same client. When a prospect replies, ask:
+
+> "@coldbirds find this contact, show their enrollment status, and pause any future steps for them in campaign X."
+
+### 3. Bulk campaign edits from spec
+
+Paste a markdown spec ("rewrite step 2 to be more concise, change wait to 4 days, add a P.S. line") and let the assistant call `update_campaign_step` to apply the edits — no copy-paste through the UI.
+
+### 4. List hygiene
+
+> "Find contacts in my workspace that have bounced in the last 30 days and remove them from all active lists."
+
+The assistant uses `list_events?type=BOUNCED` → `list_contact_lists` → `remove_contact_from_list` in a loop.
+
+### 5. Cross-tool agents (Notion / Linear / GitHub)
+
+Combine with other MCP servers — e.g. when a Linear issue tagged `outreach` is created, your agent can run `duplicate_campaign` + `enroll_contacts` based on the issue body.
+
+---
+
+## Configuration reference
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `COLDBIRDS_API_KEY` | ✅ | — | Your `sk_live_...` key from [Settings → API Keys](https://sequencer.coldbirds.com/settings/api). |
+| `COLDBIRDS_API_URL` | ❌ | `https://sequencer.coldbirds.com` | Override only for self-hosted or staging deployments. |
+
+The server **fetches its tool catalogue** from `${COLDBIRDS_API_URL}/mcp.json` at startup (5 s timeout). If the live manifest is unreachable or fails validation, it falls back to a snapshot bundled inside this package — so the server always starts even when offline.
+
+---
+
+## Troubleshooting
+
+<details>
+<summary><b>Claude Desktop shows 0 tools or the connector is red.</b></summary>
+
+1. Quit Claude Desktop completely (`Cmd+Q` on macOS, not just close the window).
+2. Verify the config JSON parses: `cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq .`
+3. Try the command in a terminal:
+   ```bash
+   COLDBIRDS_API_KEY="sk_live_..." npx -y @coldbirds/mcp-server
+   ```
+   It should print nothing and wait for input (that's normal — MCP servers talk over stdio).
+4. Check the log: `~/Library/Logs/Claude/mcp-server-coldbirds.log`.
+</details>
+
+<details>
+<summary><b>`npx` can't find <code>@coldbirds/mcp-server</code>.</b></summary>
+
+You're behind a registry proxy. Pre-install it once: `npm install -g @coldbirds/mcp-server`, then use `command: "coldbirds-mcp"` (without `npx`) in your client config.
+</details>
+
+<details>
+<summary><b>Server starts but every tool returns <code>401 Unauthorized</code>.</b></summary>
+
+The API key is wrong, revoked, or missing the `sk_live_` prefix. Regenerate at [Settings → API Keys](https://sequencer.coldbirds.com/settings/api) and update your client config.
+</details>
+
+<details>
+<summary><b>I see <code>[coldbirds-mcp] Falling back to bundled manifest</code> on startup.</b></summary>
+
+The live `mcp.json` couldn't be reached or didn't match the expected schema. The server still works — it's running off the snapshot bundled with the package version you installed. Run `npm install -g @coldbirds/mcp-server@latest` to get the newest snapshot.
+</details>
+
+<details>
+<summary><b>How do I see exactly which HTTP request a tool made?</b></summary>
+
+Run via the MCP Inspector:
+```bash
+npx @modelcontextprotocol/inspector npx -y @coldbirds/mcp-server
+```
+The Inspector shows every JSON-RPC request and response in real time. For deeper debugging, set `NODE_OPTIONS=--inspect` and attach Chrome DevTools.
+</details>
+
+---
+
+## How it works
+
+```
+┌──────────────────┐      stdio (JSON-RPC 2.0)      ┌────────────────────┐
+│ AI assistant     │ ◀────────────────────────────▶ │ @coldbirds/        │
+│ (Claude, Cursor, │                                │  mcp-server        │
+│  Cline, …)       │                                │                    │
+└──────────────────┘                                └─────────┬──────────┘
+                                                              │  HTTPS + Bearer
+                                                              ▼
+                                                    ┌────────────────────┐
+                                                    │ sequencer.         │
+                                                    │  coldbirds.com     │
+                                                    │  /api/v1/*         │
+                                                    └────────────────────┘
+```
+
+- **Single source of truth:** the tool catalogue is published at <https://sequencer.coldbirds.com/mcp.json> and the server registers tools in a loop. New ColdBirds API endpoints become MCP tools automatically — no code change in this package.
+- **Strict validation:** every tool's `inputSchema` is converted to a strict Zod schema before registration. Unknown keys are rejected at the SDK boundary so your assistant gets a clear error instead of a silent strip.
+- **Offline-safe:** a snapshot of the manifest is bundled at build time. If the live fetch fails, the server falls back to the snapshot and logs a one-line stderr warning.
+
+Architecture & contribution rules are documented in the root [`AGENTS.md` §21](https://github.com/elitale/coldbirds/blob/main/AGENTS.md#21-mcp-server-package-packagesmcp).
+
+---
+
+## Security notes
+
+- 🔐 **Treat your API key like a password.** Never paste it in chat, never commit it to git, never share it in screenshots.
+- 🛡 **Workspace-scoped:** keys can only see and modify the workspace that issued them. They cannot access other workspaces or platform-level resources.
+- ⚠️ **Destructive tools** (`delete_contact`, `delete_mailbox`, `delete_campaign_step`, `pause_campaign`, etc.) carry the MCP `destructiveHint: true` annotation. Configure your client to require explicit approval for them — do NOT add them to an auto-approve allow-list unless you fully trust the prompts.
+- 🚦 **Rate limits:** the same per-key limits as the dashboard apply (currently 60 req/min). The server doesn't add additional throttling — bursty agentic loops will hit `429` and back off.
+- 🔭 **Audit log:** every API call shows up in your workspace's audit log under the issuing key's name.
+
+---
+
+## Contributing
+
+This package is part of the [coldbirds/sequence](https://github.com/elitale/coldbird-sequncer) monorepo. PRs are welcome.
+
+- **Adding a tool** → just edit [`public/mcp.json`](https://github.com/elitale/coldbird-sequncer/blob/main/public/mcp.json) at the repo root; the dispatcher picks it up automatically. Full instructions in [`AGENTS.md` §21.2](https://github.com/elitale/coldbird-sequncer/blob/main/AGENTS.md#212-adding-a-new-tool).
+- **Bug reports / feature requests** → [open an issue](https://github.com/elitale/coldbird-sequncer/issues).
+- **Local dev:**
+  ```bash
+  git clone https://github.com/elitale/coldbird-sequncer.git
+  cd coldbird-sequncer
+  npm ci
+  cd packages/mcp
+  npm test         # 111 tests
+  npm run build
+  npm start
+  ```
+
+---
+
+## License
+
+[MIT](LICENSE) © Elitale Technologies
+
+---
+
+<sub>Built with ❤️ for cold-email marketers who would rather chat than click.</sub>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coldbirds/mcp-server",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "MCP server for ColdBirds Sequence — control campaigns, contacts, and mailboxes from AI assistants like Claude Desktop, Cursor, and Windsurf.",
   "keywords": [
     "coldbirds",
@@ -11,7 +11,7 @@
     "claude",
     "cursor"
   ],
-  "homepage": "https://github.com/elitale/coldbirds",
+  "homepage": "https://coldbirds.com",
   "license": "MIT",
   "author": "Elitale Technologies",
   "engines": {