@coldbirds/mcp-server 1.0.9 → 1.0.12

package/dist/mcp.fallback.json

@@ -102,6 +102,219 @@
         "path": "/api/v1/dashboard"
       }
     },
+    {
+      "name": "get_contact_list_analytics",
+      "title": "Get Contact List Analytics",
+      "description": "Returns deliverability, segmentation, and hygiene analytics for a contact list — the same multi-deck snapshot the in-app list dashboard shows. Includes the stoplight (sendable / risky / unsendable / unverified), validation status breakdown, provider mix (Google / Microsoft / other / unknown), validation freshness, top sending domains and free-mail count, suppression count, campaigns currently enrolling these contacts elsewhere (collision warning), standard + custom field coverage, top job titles, and contact-age cohorts. Use this to answer 'is this list ready to send?' or 'what does this list look like?' questions.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "listId": {
+            "type": "string",
+            "description": "Contact list ID."
+          }
+        },
+        "required": ["listId"],
+        "additionalProperties": false
+      },
+      "outputSchema": {
+        "type": "object",
+        "properties": {
+          "listId": { "type": "string" },
+          "listName": { "type": "string" },
+          "total": { "type": "integer", "description": "Total non-deleted contacts in the list." },
+          "stoplight": {
+            "type": "object",
+            "description": "High-level decision-driving counts.",
+            "properties": {
+              "total": { "type": "integer" },
+              "sendable": { "type": "integer", "description": "VALID contacts." },
+              "risky": { "type": "integer", "description": "CATCH_ALL + ROLE + DISPOSABLE." },
+              "unsendable": { "type": "integer", "description": "INVALID + BOUNCED + FAILED + UNSUBSCRIBED + COMPLAINED." },
+              "unverified": { "type": "integer", "description": "UNKNOWN + PENDING." }
+            },
+            "required": ["total", "sendable", "risky", "unsendable", "unverified"]
+          },
+          "validationStatus": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "status": { "type": "string", "description": "ContactStatus enum value." },
+                "count": { "type": "integer" }
+              },
+              "required": ["status", "count"]
+            }
+          },
+          "providers": {
+            "type": "array",
+            "description": "Email provider mix derived from MX lookups.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "provider": { "type": "string", "enum": ["GOOGLE", "MICROSOFT", "OTHER", "UNKNOWN"] },
+                "count": { "type": "integer" }
+              },
+              "required": ["provider", "count"]
+            }
+          },
+          "freshness": {
+            "type": "array",
+            "description": "How recently each contact's email was validated.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "bucket": { "type": "string", "enum": ["LT_30D", "D30_90", "GT_90D", "NEVER"] },
+                "count": { "type": "integer" }
+              },
+              "required": ["bucket", "count"]
+            }
+          },
+          "topDomains": {
+            "type": "array",
+            "description": "Top 10 email domains by contact count.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "domain": { "type": "string" },
+                "count": { "type": "integer" }
+              },
+              "required": ["domain", "count"]
+            }
+          },
+          "freeMailCount": { "type": "integer", "description": "Contacts on free providers (gmail/yahoo/outlook/...)." },
+          "suppressedCount": { "type": "integer", "description": "Suppressed (UNSUBSCRIBED / COMPLAINED / global suppression)." },
+          "activeEnrollmentsElsewhere": {
+            "type": "array",
+            "description": "Campaigns currently enrolling some of this list's contacts — useful to avoid collision.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "campaignId": { "type": "string" },
+                "campaignName": { "type": "string" },
+                "status": { "type": "string", "description": "CampaignStatus enum (DRAFT, ACTIVE, PAUSED)." },
+                "dailyLimit": { "type": "integer" },
+                "contactCount": { "type": "integer" }
+              },
+              "required": ["campaignId", "campaignName", "status", "dailyLimit", "contactCount"]
+            }
+          },
+          "fieldCoverage": {
+            "type": "array",
+            "description": "Standard field population counts.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "field": { "type": "string", "enum": ["firstName", "lastName", "company", "title"] },
+                "populated": { "type": "integer" }
+              },
+              "required": ["field", "populated"]
+            }
+          },
+          "customFields": {
+            "type": "array",
+            "description": "Custom field coverage and value distribution.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "key": { "type": "string" },
+                "populated": { "type": "integer" },
+                "distinct": { "type": "integer" },
+                "topValues": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "value": { "type": "string" },
+                      "count": { "type": "integer" }
+                    },
+                    "required": ["value", "count"]
+                  }
+                },
+                "categorical": { "type": "boolean", "description": "True when distinct <= 20." },
+                "numeric": {
+                  "type": "object",
+                  "nullable": true,
+                  "description": "Set when >= 80% of values parse as numbers.",
+                  "properties": {
+                    "min": { "type": "number" },
+                    "max": { "type": "number" },
+                    "median": { "type": "number" },
+                    "bins": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "from": { "type": "number" },
+                          "to": { "type": "number" },
+                          "count": { "type": "integer" }
+                        },
+                        "required": ["from", "to", "count"]
+                      }
+                    }
+                  },
+                  "required": ["min", "max", "median", "bins"]
+                }
+              },
+              "required": ["key", "populated", "distinct", "topValues", "categorical", "numeric"]
+            }
+          },
+          "topTitles": {
+            "type": "array",
+            "description": "Top 20 job titles by contact count.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "title": { "type": "string" },
+                "count": { "type": "integer" }
+              },
+              "required": ["title", "count"]
+            }
+          },
+          "addedAt": {
+            "type": "array",
+            "description": "When contacts were added to the list.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "bucket": { "type": "string", "enum": ["THIS_WEEK", "THIS_MONTH", "M1_3", "M3_6", "GT_6M"] },
+                "count": { "type": "integer" }
+              },
+              "required": ["bucket", "count"]
+            }
+          },
+          "computedAt": { "type": "string", "description": "ISO timestamp when this snapshot was computed (cached for 5 minutes)." }
+        },
+        "required": [
+          "listId",
+          "listName",
+          "total",
+          "stoplight",
+          "validationStatus",
+          "providers",
+          "freshness",
+          "topDomains",
+          "freeMailCount",
+          "suppressedCount",
+          "activeEnrollmentsElsewhere",
+          "fieldCoverage",
+          "customFields",
+          "topTitles",
+          "addedAt",
+          "computedAt"
+        ]
+      },
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true,
+        "openWorldHint": false
+      },
+      "_http": {
+        "method": "GET",
+        "path": "/api/v1/lists/{listId}/analytics"
+      }
+    },
     {
       "name": "get_account",
       "title": "Get Account",
@@ -3423,6 +3636,459 @@
         "method": "GET",
         "path": "/api/v1/campaigns/{campaignId}/variables"
       }
+    },
+    {
+      "name": "list_inbox_messages",
+      "title": "List Inbox Messages",
+      "description": "Lists inbound email messages across all connected mailboxes. Supports folder filtering (inbox, replies, auto-replies, bounces, spam, starred, archived, all, warmup), free-text search, sender filter, mailbox/label filtering, read/unread state, starred flag, and date range. Cursor-paginated by receivedAt.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "folder": {
+            "type": "string",
+            "enum": ["inbox", "replies", "auto-replies", "bounces", "spam", "starred", "archived", "all", "warmup"],
+            "default": "inbox",
+            "description": "Folder to list. Virtual folders (starred, archived, all, warmup) filter across real folders."
+          },
+          "cursor": {
+            "type": "string",
+            "format": "date-time",
+            "description": "ISO-8601 cursor from the previous page's nextCursor."
+          },
+          "limit": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 100,
+            "default": 50,
+            "description": "Number of messages per page."
+          },
+          "q": {
+            "type": "string",
+            "description": "Free-text search across subject, snippet, body, and sender."
+          },
+          "from": {
+            "type": "string",
+            "description": "Filter by sender name or email (substring match)."
+          },
+          "mailboxIds": {
+            "type": "string",
+            "description": "Comma-separated mailbox IDs to restrict results."
+          },
+          "labelIds": {
+            "type": "string",
+            "description": "Comma-separated label IDs to filter by (OR semantics)."
+          },
+          "read": {
+            "type": "string",
+            "enum": ["read", "unread"],
+            "description": "Filter by read status."
+          },
+          "starred": {
+            "type": "string",
+            "enum": ["true"],
+            "description": "When 'true', only return starred messages."
+          },
+          "dateFrom": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Inclusive lower bound on receivedAt (ISO-8601)."
+          },
+          "dateTo": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Inclusive upper bound on receivedAt (ISO-8601)."
+          }
+        },
+        "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true,
+        "openWorldHint": false
+      },
+      "_http": {
+        "method": "GET",
+        "path": "/api/v1/inbox/messages"
+      }
+    },
+    {
+      "name": "get_inbox_message",
+      "title": "Get Inbox Message",
+      "description": "Returns full details of a single inbound message including HTML/text body, headers, and a presigned download URL for the raw RFC822. Automatically marks the message as read on first access.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Inbound message ID."
+          }
+        },
+        "required": ["id"],
+        "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": false,
+        "destructiveHint": false,
+        "idempotentHint": true,
+        "openWorldHint": false
+      },
+      "_http": {
+        "method": "GET",
+        "path": "/api/v1/inbox/messages/{id}"
+      }
+    },
+    {
+      "name": "update_inbox_message",
+      "title": "Update Inbox Message",
+      "description": "Updates mutable fields on an inbound message: mark as read/unread, star/unstar, archive/unarchive, or assign/clear a label. Only provided fields are changed.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Inbound message ID."
+          },
+          "read": {
+            "type": "boolean",
+            "description": "Set true to mark as read, false to mark unread."
+          },
+          "starred": {
+            "type": "boolean",
+            "description": "Set true to star, false to unstar."
+          },
+          "archived": {
+            "type": "boolean",
+            "description": "Set true to archive, false to unarchive."
+          },
+          "labelId": {
+            "type": ["string", "null"],
+            "description": "Inbox label ID to assign, or null to clear the label."
+          }
+        },
+        "required": ["id"],
+        "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": false,
+        "destructiveHint": false,
+        "idempotentHint": true,
+        "openWorldHint": false
+      },
+      "_http": {
+        "method": "PATCH",
+        "path": "/api/v1/inbox/messages/{id}"
+      }
+    },
+    {
+      "name": "reply_to_message",
+      "title": "Reply to Inbox Message",
+      "description": "Sends a reply to an inbound message using the mailbox that originally received it. Automatically threads via In-Reply-To/References headers and includes quoted context.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Inbound message ID to reply to."
+          },
+          "body": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 50000,
+            "description": "Reply body in HTML."
+          },
+          "subject": {
+            "type": "string",
+            "maxLength": 998,
+            "description": "Optional subject override. Defaults to 'Re: <original subject>'."
+          }
+        },
+        "required": ["id", "body"],
+        "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": false,
+        "destructiveHint": false,
+        "idempotentHint": false,
+        "openWorldHint": true
+      },
+      "_http": {
+        "method": "POST",
+        "path": "/api/v1/inbox/messages/{id}/reply"
+      }
+    },
+    {
+      "name": "list_message_replies",
+      "title": "List Message Replies",
+      "description": "Lists all outbound replies sent for a specific inbound message, ordered chronologically. Useful for viewing the full reply thread.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Inbound message ID."
+          }
+        },
+        "required": ["id"],
+        "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true,
+        "openWorldHint": false
+      },
+      "_http": {
+        "method": "GET",
+        "path": "/api/v1/inbox/messages/{id}/replies"
+      }
+    },
+    {
+      "name": "list_sent_messages",
+      "title": "List Sent Messages",
+      "description": "Lists outbound replies and composed emails sent by the user, collapsed by thread (toEmail + normalized subject). Cursor-paginated by sentAt.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "cursor": {
+            "type": "string",
+            "format": "date-time",
+            "description": "ISO-8601 cursor from the previous page's nextCursor."
+          },
+          "limit": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 100,
+            "default": 50,
+            "description": "Number of threads per page."
+          },
+          "q": {
+            "type": "string",
+            "description": "Free-text search across subject, body, and recipient."
+          }
+        },
+        "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true,
+        "openWorldHint": false
+      },
+      "_http": {
+        "method": "GET",
+        "path": "/api/v1/inbox/sent"
+      }
+    },
+    {
+      "name": "compose_email",
+      "title": "Compose Email",
+      "description": "Compose and send a new email from a connected mailbox. Not a reply — creates a fresh thread. The email is sent immediately via the mailbox's configured transport (SMTP / Google / Microsoft).",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "mailboxId": {
+            "type": "string",
+            "description": "ID of the sender mailbox to use."
+          },
+          "to": {
+            "type": "string",
+            "format": "email",
+            "description": "Recipient email address."
+          },
+          "subject": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 998,
+            "description": "Email subject line."
+          },
+          "body": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 50000,
+            "description": "Email body in HTML."
+          },
+          "cc": {
+            "type": "array",
+            "items": { "type": "string", "format": "email" },
+            "description": "CC recipients."
+          },
+          "bcc": {
+            "type": "array",
+            "items": { "type": "string", "format": "email" },
+            "description": "BCC recipients."
+          }
+        },
+        "required": ["mailboxId", "to", "subject", "body"],
+        "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": false,
+        "destructiveHint": false,
+        "idempotentHint": false,
+        "openWorldHint": true
+      },
+      "_http": {
+        "method": "POST",
+        "path": "/api/v1/inbox/compose"
+      }
+    },
+    {
+      "name": "get_inbox_counts",
+      "title": "Get Inbox Counts",
+      "description": "Returns total and unread message counts per folder (inbox, replies, auto-replies, bounces, spam, starred, archived, all, warmup, sent) plus per-label message counts. Powers the sidebar badges.",
+      "inputSchema": {
+        "type": "object",
+        "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true,
+        "openWorldHint": false
+      },
+      "_http": {
+        "method": "GET",
+        "path": "/api/v1/inbox/counts"
+      }
+    },
+    {
+      "name": "trigger_inbox_scan",
+      "title": "Trigger Inbox Scan",
+      "description": "Triggers an immediate IMAP scan to check for new messages. Optionally scope to a single mailbox by passing mailboxId; omit to scan all eligible mailboxes.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "mailboxId": {
+            "type": "string",
+            "description": "Optional mailbox ID to scan. Omit to scan all mailboxes."
+          }
+        },
+        "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": false,
+        "destructiveHint": false,
+        "idempotentHint": true,
+        "openWorldHint": false
+      },
+      "_http": {
+        "method": "POST",
+        "path": "/api/v1/inbox/scan"
+      }
+    },
+    {
+      "name": "list_inbox_labels",
+      "title": "List Inbox Labels",
+      "description": "Lists the user's inbox message labels (Auto-reply, OOO, Opportunity, Positive reply, Negative reply, custom labels) with message counts and classification rule counts.",
+      "inputSchema": {
+        "type": "object",
+        "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true,
+        "openWorldHint": false
+      },
+      "_http": {
+        "method": "GET",
+        "path": "/api/v1/inbox/labels"
+      }
+    },
+    {
+      "name": "create_inbox_label",
+      "title": "Create Inbox Label",
+      "description": "Creates a new inbox message label. Names must be unique per account.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 100,
+            "description": "Label name."
+          },
+          "color": {
+            "type": "string",
+            "description": "Hex color code (e.g. '#6b7280'). Defaults to gray."
+          }
+        },
+        "required": ["name"],
+        "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": false,
+        "destructiveHint": false,
+        "idempotentHint": false,
+        "openWorldHint": false
+      },
+      "_http": {
+        "method": "POST",
+        "path": "/api/v1/inbox/labels"
+      }
+    },
+    {
+      "name": "update_inbox_label",
+      "title": "Update Inbox Label",
+      "description": "Renames or recolors an inbox message label.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Label ID."
+          },
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 100,
+            "description": "New label name."
+          },
+          "color": {
+            "type": "string",
+            "description": "New hex color code."
+          }
+        },
+        "required": ["id"],
+        "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": false,
+        "destructiveHint": false,
+        "idempotentHint": true,
+        "openWorldHint": false
+      },
+      "_http": {
+        "method": "PATCH",
+        "path": "/api/v1/inbox/labels/{id}"
+      }
+    },
+    {
+      "name": "delete_inbox_label",
+      "title": "Delete Inbox Label",
+      "description": "Deletes an inbox message label. Messages tagged with this label will have their label cleared.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Label ID to delete."
+          }
+        },
+        "required": ["id"],
+        "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": false,
+        "destructiveHint": true,
+        "idempotentHint": true,
+        "openWorldHint": false
+      },
+      "_http": {
+        "method": "DELETE",
+        "path": "/api/v1/inbox/labels/{id}"
+      }
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coldbirds/mcp-server",
-  "version": "1.0.9",
+  "version": "1.0.12",
   "description": "MCP server for ColdBirds Sequence — control campaigns, contacts, and mailboxes from AI assistants like Claude Desktop, Cursor, and Windsurf.",
   "keywords": [
     "coldbirds",