@cheerful/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,68 @@
+# @cheerful/mcp-server
+
+MCP server for the [Cheerful](https://cheerful.ai) platform. Manage campaigns, search creators, send emails, and monitor your inbox from AI coding assistants like Claude Code, Cursor, and Windsurf.
+
+## Setup
+
+1. Get your API key at [cheerful.ai/cc](https://cheerful.ai/cc)
+2. Add the server to your AI assistant (see below)
+
+### Claude Code
+
+```bash
+claude mcp add cheerful -e CHEERFUL_API_KEY=chrl_your_key_here -- npx @cheerful/mcp-server
+```
+
+### Cursor / Windsurf / VS Code
+
+Add to `.cursor/mcp.json` (or your IDE's MCP config):
+
+```json
+{
+  "mcpServers": {
+    "cheerful": {
+      "command": "npx",
+      "args": ["@cheerful/mcp-server"],
+      "env": {
+        "CHEERFUL_API_KEY": "chrl_your_key_here"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `CHEERFUL_API_KEY` | Yes | Your `chrl_`-prefixed API key |
+| `CHEERFUL_API_URL` | No | API base URL (defaults to production) |
+
+## Available Tools
+
+### Campaigns
+- **list_campaigns** -- List all your campaigns
+- **get_campaign** -- Get details for a specific campaign
+- **create_campaign** -- Create a new campaign with email templates
+- **add_recipients_to_campaign** -- Add creators to a campaign by email or social handle
+- **set_campaign_sender** -- Change the sender email account
+- **launch_campaign** -- Start sending emails for a campaign
+- **get_dashboard_analytics** -- Aggregated analytics across campaigns
+
+### Creators
+- **search_creators** -- Search for creators by keyword
+- **get_creator_profile** -- Get a creator's profile by handle
+- **list_creator_lists** -- List your saved creator lists
+
+### Email
+- **get_draft** -- Get the current draft for a thread
+- **update_draft** -- Edit a draft
+- **send_email** -- Send an email via a connected account
+
+### Inbox
+- **list_inbox** -- List and search email threads
+- **list_automations** -- List campaign automation rules
+
+## License
+
+MIT

package/dist/api-client.d.ts

@@ -0,0 +1,25 @@
+import type { Config } from "./config.js";
+export interface ApiError {
+    status: number;
+    statusText: string;
+    body: string;
+}
+export declare class CheerfulApiClient {
+    private baseUrl;
+    private apiKey;
+    constructor(config: Config);
+    private headers;
+    get<T>(path: string, params?: Record<string, string>): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    put<T>(path: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    delete(path: string): Promise<void>;
+    private toApiError;
+}
+export declare function formatError(error: unknown): {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError: true;
+};

package/dist/api-client.js

@@ -0,0 +1,88 @@
+export class CheerfulApiClient {
+    baseUrl;
+    apiKey;
+    constructor(config) {
+        this.baseUrl = config.apiBaseUrl;
+        this.apiKey = config.apiKey;
+    }
+    headers() {
+        return {
+            "Content-Type": "application/json",
+            Accept: "application/json",
+            "X-Cheerful-Api-Key": this.apiKey,
+        };
+    }
+    async get(path, params) {
+        const url = new URL(`/api${path}`, this.baseUrl);
+        if (params) {
+            for (const [k, v] of Object.entries(params)) {
+                if (v !== undefined && v !== "")
+                    url.searchParams.set(k, v);
+            }
+        }
+        const res = await fetch(url.toString(), { headers: this.headers() });
+        if (!res.ok)
+            throw await this.toApiError(res);
+        return (await res.json());
+    }
+    async post(path, body) {
+        const url = new URL(`/api${path}`, this.baseUrl);
+        const res = await fetch(url.toString(), {
+            method: "POST",
+            headers: this.headers(),
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (!res.ok)
+            throw await this.toApiError(res);
+        return (await res.json());
+    }
+    async put(path, body) {
+        const url = new URL(`/api${path}`, this.baseUrl);
+        const res = await fetch(url.toString(), {
+            method: "PUT",
+            headers: this.headers(),
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (!res.ok)
+            throw await this.toApiError(res);
+        return (await res.json());
+    }
+    async patch(path, body) {
+        const url = new URL(`/api${path}`, this.baseUrl);
+        const res = await fetch(url.toString(), {
+            method: "PATCH",
+            headers: this.headers(),
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (!res.ok)
+            throw await this.toApiError(res);
+        return (await res.json());
+    }
+    async delete(path) {
+        const url = new URL(`/api${path}`, this.baseUrl);
+        const res = await fetch(url.toString(), {
+            method: "DELETE",
+            headers: this.headers(),
+        });
+        if (!res.ok)
+            throw await this.toApiError(res);
+    }
+    async toApiError(res) {
+        const body = await res.text();
+        return { status: res.status, statusText: res.statusText, body };
+    }
+}
+export function formatError(error) {
+    let message;
+    if (typeof error === "object" && error !== null && "status" in error) {
+        const e = error;
+        message = `API error ${e.status} ${e.statusText}: ${e.body}`;
+    }
+    else if (error instanceof Error) {
+        message = error.message;
+    }
+    else {
+        message = String(error);
+    }
+    return { content: [{ type: "text", text: message }], isError: true };
+}

package/dist/config.d.ts

@@ -0,0 +1,5 @@
+export interface Config {
+    apiKey: string;
+    apiBaseUrl: string;
+}
+export declare function loadConfig(): Config;

package/dist/config.js

@@ -0,0 +1,9 @@
+export function loadConfig() {
+    const apiKey = process.env.CHEERFUL_API_KEY ?? "";
+    const apiBaseUrl = process.env.CHEERFUL_API_URL ?? "https://prd-cheerful.fly.dev";
+    if (!apiKey) {
+        throw new Error("CHEERFUL_API_KEY environment variable is required. " +
+            "Get your key at https://cheerful.ai/cc and configure it in your MCP client.");
+    }
+    return { apiKey, apiBaseUrl };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { createRequire } from "module";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { CheerfulApiClient } from "./api-client.js";
+import { registerCampaignTools } from "./tools/campaigns.js";
+import { registerCreatorTools } from "./tools/creators.js";
+import { registerEmailTools } from "./tools/email.js";
+import { registerInboxTools } from "./tools/inbox.js";
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
+async function main() {
+    const config = loadConfig();
+    const api = new CheerfulApiClient(config);
+    const server = new McpServer({
+        name: "cheerful",
+        version,
+    });
+    registerCampaignTools(server, api);
+    registerCreatorTools(server, api);
+    registerEmailTools(server, api);
+    registerInboxTools(server, api);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Cheerful MCP server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error.message ?? error);
+    process.exit(1);
+});

package/dist/tools/campaigns.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CheerfulApiClient } from "../api-client.js";
+export declare function registerCampaignTools(server: McpServer, api: CheerfulApiClient): void;

package/dist/tools/campaigns.js

@@ -0,0 +1,195 @@
+import { z } from "zod";
+import { formatError } from "../api-client.js";
+export function registerCampaignTools(server, api) {
+    server.registerTool("list_campaigns", {
+        title: "List Campaigns",
+        description: "List all campaigns for the authenticated user. Returns campaign id, name, status, and type.",
+        inputSchema: {},
+    }, async () => {
+        try {
+            const campaigns = await api.get("/campaigns/");
+            if (campaigns.length === 0) {
+                return { content: [{ type: "text", text: "No campaigns found." }] };
+            }
+            const formatted = campaigns
+                .map((c) => `- **${c.name}** (${c.status})\n  ID: ${c.id} | Type: ${c.campaign_type ?? "N/A"} | Created: ${c.created_at}`)
+                .join("\n");
+            return {
+                content: [
+                    { type: "text", text: `Found ${campaigns.length} campaigns:\n\n${formatted}` },
+                ],
+            };
+        }
+        catch (error) {
+            return formatError(error);
+        }
+    });
+    server.registerTool("get_campaign", {
+        title: "Get Campaign",
+        description: "Get detailed information about a specific campaign by ID.",
+        inputSchema: {
+            campaign_id: z.string().uuid().describe("The campaign UUID"),
+        },
+    }, async ({ campaign_id }) => {
+        try {
+            const campaign = await api.get(`/campaigns/${campaign_id}`);
+            return {
+                content: [{ type: "text", text: JSON.stringify(campaign, null, 2) }],
+            };
+        }
+        catch (error) {
+            return formatError(error);
+        }
+    });
+    server.registerTool("create_campaign", {
+        title: "Create Campaign",
+        description: "Create a new campaign. Requires name, campaign_type, subject_template, and body_template.",
+        inputSchema: {
+            name: z.string().min(1).max(255).describe("Campaign name"),
+            campaign_type: z
+                .enum(["paid_promotion", "creator", "gifting", "sales", "other"])
+                .describe("Campaign type"),
+            subject_template: z.string().min(1).describe("Email subject template"),
+            body_template: z.string().min(1).describe("Email body template"),
+            description: z.string().optional().describe("Campaign description"),
+        },
+    }, async ({ name, campaign_type, subject_template, body_template, description }) => {
+        try {
+            const campaign = await api.post("/campaigns/", {
+                name,
+                campaign_type,
+                subject_template,
+                body_template,
+                description,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Campaign created!\n\nID: ${campaign.id}\nName: ${campaign.name}\nStatus: ${campaign.status}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return formatError(error);
+        }
+    });
+    server.registerTool("get_dashboard_analytics", {
+        title: "Get Dashboard Analytics",
+        description: "Get aggregated analytics across all campaigns for the authenticated user. Includes campaign counts, opt-in rates, recent opt-ins, and active campaign stats.",
+        inputSchema: {},
+    }, async () => {
+        try {
+            const analytics = await api.get(`/dashboard/analytics`);
+            return {
+                content: [{ type: "text", text: JSON.stringify(analytics, null, 2) }],
+            };
+        }
+        catch (error) {
+            return formatError(error);
+        }
+    });
+    server.registerTool("add_recipients_to_campaign", {
+        title: "Add Recipients to Campaign",
+        description: "Add recipients (creators) to a campaign. Provide email and/or social media handles. If no email is provided, enrichment will attempt to find it automatically.",
+        inputSchema: {
+            campaign_id: z.string().uuid().describe("The campaign UUID"),
+            recipients: z
+                .array(z.object({
+                email: z.string().email().optional().describe("Creator's email"),
+                name: z.string().optional().describe("Creator's name"),
+                social_media_handles: z
+                    .array(z.object({
+                    platform: z.string().describe("Social media platform"),
+                    handle: z.string().describe("Handle on the platform"),
+                    url: z.string().optional().describe("Profile URL"),
+                }))
+                    .optional()
+                    .default([])
+                    .describe("Social media handles"),
+                custom_fields: z
+                    .record(z.string(), z.any())
+                    .optional()
+                    .default({})
+                    .describe("Custom fields for the recipient"),
+            }))
+                .min(1)
+                .describe("List of recipients to add"),
+        },
+    }, async ({ campaign_id, recipients }) => {
+        try {
+            const results = await api.post(`/campaigns/${campaign_id}/recipients-from-search`, recipients);
+            const formatted = results
+                .map((r) => `- Recipient: ${r.recipient_id} | Creator: ${r.creator_id} | Email: ${r.email ?? "pending enrichment"} | ${r.already_existed ? "Already existed" : "New"}`)
+                .join("\n");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Added ${results.length} recipient(s):\n\n${formatted}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return formatError(error);
+        }
+    });
+    server.registerTool("set_campaign_sender", {
+        title: "Set Campaign Sender",
+        description: "Change the sender email account for a campaign. Both email addresses must be connected Gmail or SMTP accounts owned by the campaign owner.",
+        inputSchema: {
+            campaign_id: z.string().uuid().describe("The campaign UUID"),
+            old_sender_email: z.string().email().describe("Current sender email to replace"),
+            new_sender_email: z.string().email().describe("New sender email"),
+        },
+    }, async ({ campaign_id, old_sender_email, new_sender_email }) => {
+        try {
+            const result = await api.patch(`/campaigns/${campaign_id}/senders`, {
+                old_sender_email,
+                new_sender_email,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Success: ${result.success}\nAffected emails: ${result.affected_emails}\nMessage: ${result.message}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return formatError(error);
+        }
+    });
+    server.registerTool("launch_campaign", {
+        title: "Launch Campaign",
+        description: "Populate the outbound queue for a campaign and start sending. Emails are distributed round-robin across configured senders and sent automatically every 5 minutes. This is idempotent — only creates queue entries for recipients that don't already have one.",
+        inputSchema: {
+            campaign_id: z.string().uuid().describe("The campaign UUID"),
+            cc_emails: z
+                .array(z.string().email())
+                .optional()
+                .describe("Optional CC email addresses"),
+        },
+    }, async ({ campaign_id, cc_emails }) => {
+        try {
+            const body = {};
+            if (cc_emails)
+                body.cc_emails = cc_emails;
+            const result = await api.post(`/campaigns/${campaign_id}/outbound`, body);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Status: ${result.status}\nMessage: ${result.message}\nEntries created: ${result.entries_created}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return formatError(error);
+        }
+    });
+}

package/dist/tools/creators.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CheerfulApiClient } from "../api-client.js";
+export declare function registerCreatorTools(server: McpServer, api: CheerfulApiClient): void;

package/dist/tools/creators.js

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import { formatError } from "../api-client.js";
+export function registerCreatorTools(server, api) {
+    server.registerTool("search_creators", {
+        title: "Search Creators",
+        description: "Search for creators by keyword. Returns matching creator profiles. Private and inactive (no posts in 90 days) profiles are excluded by default.",
+        inputSchema: {
+            query: z.string().min(1).describe("Search query (keyword or handle)"),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .optional()
+                .describe("Max number of creators to return (default 50, max 50)"),
+        },
+    }, async ({ query, limit }) => {
+        try {
+            const results = await api.post("/v1/creator-search/keyword", { keyword: query, limit: limit ?? 50 });
+            return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
+        }
+        catch (error) {
+            return formatError(error);
+        }
+    });
+    server.registerTool("get_creator_profile", {
+        title: "Get Creator Profile",
+        description: "Get detailed profile for a creator by their handle.",
+        inputSchema: {
+            handle: z.string().min(1).describe("Creator social media handle"),
+        },
+    }, async ({ handle }) => {
+        try {
+            const profile = await api.get(`/v1/creators/profiles/${encodeURIComponent(handle)}`);
+            return { content: [{ type: "text", text: JSON.stringify(profile, null, 2) }] };
+        }
+        catch (error) {
+            return formatError(error);
+        }
+    });
+    server.registerTool("list_creator_lists", {
+        title: "List Creator Lists",
+        description: "List all saved creator lists for the authenticated user.",
+        inputSchema: {},
+    }, async () => {
+        try {
+            const lists = await api.get("/v1/lists/");
+            return { content: [{ type: "text", text: JSON.stringify(lists, null, 2) }] };
+        }
+        catch (error) {
+            return formatError(error);
+        }
+    });
+}

package/dist/tools/email.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CheerfulApiClient } from "../api-client.js";
+export declare function registerEmailTools(server: McpServer, api: CheerfulApiClient): void;

package/dist/tools/email.js

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { formatError } from "../api-client.js";
+export function registerEmailTools(server, api) {
+    server.registerTool("get_draft", {
+        title: "Get Draft",
+        description: "Get the current draft for a specific email thread.",
+        inputSchema: { thread_id: z.string().min(1).describe("The Gmail/SMTP/Instagram thread ID") },
+    }, async ({ thread_id }) => {
+        try {
+            const draft = await api.get(`/threads/${thread_id}/draft`);
+            return { content: [{ type: "text", text: JSON.stringify(draft, null, 2) }] };
+        }
+        catch (error) {
+            return formatError(error);
+        }
+    });
+    server.registerTool("update_draft", {
+        title: "Update Draft",
+        description: "Update the draft content for a specific email thread.",
+        inputSchema: {
+            thread_id: z.string().min(1).describe("The Gmail/SMTP/Instagram thread ID"),
+            gmail_thread_state_id: z.string().uuid().describe("Thread state UUID for optimistic concurrency (from get_draft response)"),
+            draft_subject: z.string().optional().describe("Email subject line"),
+            draft_body_text: z.string().optional().describe("Email body as plain text"),
+        },
+    }, async ({ thread_id, gmail_thread_state_id, draft_subject, draft_body_text }) => {
+        try {
+            const draft = await api.put(`/threads/${thread_id}/draft`, { gmail_thread_state_id, draft_subject, draft_body_text });
+            return {
+                content: [{ type: "text", text: `Draft updated.\n\n${JSON.stringify(draft, null, 2)}` }],
+            };
+        }
+        catch (error) {
+            return formatError(error);
+        }
+    });
+    server.registerTool("send_email", {
+        title: "Send Email",
+        description: "Send an email via a connected Gmail or SMTP account. Requires the sender account email, recipient, subject, and body.",
+        inputSchema: {
+            account_email: z.string().email().describe("Sender account email address (must be a connected Gmail or SMTP account)"),
+            to: z.array(z.string().email()).min(1).describe("Recipient email addresses"),
+            subject: z.string().min(1).describe("Email subject"),
+            body_html: z.string().optional().describe("Email body as HTML"),
+            body_text: z.string().optional().describe("Email body as plain text (provide body_html or body_text)"),
+            cc: z.array(z.string().email()).optional().describe("CC email addresses"),
+            thread_id: z.string().optional().describe("Gmail thread ID for replies"),
+            in_reply_to: z.string().optional().describe("Message-ID header of the message being replied to"),
+            references: z.string().optional().describe("References header for threading"),
+        },
+    }, async ({ account_email, to, subject, body_html, body_text, cc, thread_id, in_reply_to, references }) => {
+        try {
+            const result = await api.post("/emails/send", { account_email, to, subject, body_html, body_text, cc, thread_id, in_reply_to, references });
+            return {
+                content: [{ type: "text", text: `Email sent to ${to.join(", ")}.\n\n${JSON.stringify(result, null, 2)}` }],
+            };
+        }
+        catch (error) {
+            return formatError(error);
+        }
+    });
+}

package/dist/tools/inbox.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CheerfulApiClient } from "../api-client.js";
+export declare function registerInboxTools(server: McpServer, api: CheerfulApiClient): void;

package/dist/tools/inbox.js

@@ -0,0 +1,50 @@
+import { z } from "zod";
+import { formatError } from "../api-client.js";
+export function registerInboxTools(server, api) {
+    server.registerTool("list_inbox", {
+        title: "List Inbox",
+        description: "List email threads. Optionally filter by campaign ID, search text, or limit results.",
+        inputSchema: {
+            campaign_id: z.string().uuid().optional().describe("Filter by campaign UUID"),
+            search: z.string().optional().describe("Search in sender, recipient, or subject"),
+            limit: z.number().int().min(1).max(100).default(50).describe("Max threads to return"),
+            offset: z.number().int().min(0).default(0).describe("Pagination offset"),
+        },
+    }, async ({ campaign_id, search, limit, offset }) => {
+        try {
+            const params = {};
+            if (campaign_id)
+                params.campaign_id = campaign_id;
+            if (search)
+                params.search = search;
+            if (limit !== undefined)
+                params.limit = String(limit);
+            if (offset !== undefined)
+                params.offset = String(offset);
+            const threads = await api.get(`/threads/`, params);
+            return {
+                content: [
+                    { type: "text", text: `Found ${threads.length} threads:\n\n${JSON.stringify(threads, null, 2)}` },
+                ],
+            };
+        }
+        catch (error) {
+            return formatError(error);
+        }
+    });
+    server.registerTool("list_automations", {
+        title: "List Automations",
+        description: "List campaign automation rules.",
+        inputSchema: {
+            campaign_id: z.string().uuid().describe("Campaign UUID"),
+        },
+    }, async ({ campaign_id }) => {
+        try {
+            const automations = await api.get(`/v1/campaigns/${campaign_id}/workflows`);
+            return { content: [{ type: "text", text: JSON.stringify(automations, null, 2) }] };
+        }
+        catch (error) {
+            return formatError(error);
+        }
+    });
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@cheerful/mcp-server",
+  "version": "0.1.0",
+  "description": "Cheerful MCP server — manage campaigns, creators, and more from AI coding assistants",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://cheerful.ai/cc",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nuts-and-bolts-ai/cheerful.git",
+    "directory": "packages/mcp-server"
+  },
+  "bin": {
+    "cheerful-mcp-server": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build",
+    "inspect": "npx @modelcontextprotocol/inspector dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.28.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.0",
+    "typescript": "^5.9.0"
+  }
+}