@mindstone-engineering/mcp-server-mixmax 0.1.0

package/dist/auth.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Mixmax authentication module.
+ *
+ * Manages the API token lifecycle — env var on startup, runtime update via
+ * configure tool, and bridge integration for host-app credential management.
+ */
+/**
+ * Returns the current API token.
+ */
+export declare function getApiToken(): string;
+/**
+ * Returns true if an API token is configured.
+ */
+export declare function isConfigured(): boolean;
+/**
+ * Update the API token at runtime (e.g. after configure_mixmax_api_key).
+ */
+export declare function setApiToken(token: string): void;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.js

@@ -0,0 +1,26 @@
+/**
+ * Mixmax authentication module.
+ *
+ * Manages the API token lifecycle — env var on startup, runtime update via
+ * configure tool, and bridge integration for host-app credential management.
+ */
+let apiToken = process.env.MIXMAX_API_TOKEN || '';
+/**
+ * Returns the current API token.
+ */
+export function getApiToken() {
+    return apiToken;
+}
+/**
+ * Returns true if an API token is configured.
+ */
+export function isConfigured() {
+    return apiToken.length > 0;
+}
+/**
+ * Update the API token at runtime (e.g. after configure_mixmax_api_key).
+ */
+export function setApiToken(token) {
+    apiToken = token;
+}
+//# sourceMappingURL=auth.js.map

package/dist/bridge.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Path to bridge state file, supporting both current and legacy env vars.
+ */
+export declare const BRIDGE_STATE_PATH: string;
+/**
+ * Send a request to the host app bridge.
+ *
+ * The bridge is an HTTP server running inside the host app (e.g. Rebel)
+ * that handles credential management and other cross-process operations.
+ */
+export declare const bridgeRequest: (urlPath: string, body: Record<string, unknown>) => Promise<{
+    success: boolean;
+    warning?: string;
+    error?: string;
+}>;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.js

@@ -0,0 +1,43 @@
+import * as fs from 'fs';
+import { REQUEST_TIMEOUT_MS } from './types.js';
+/**
+ * Path to bridge state file, supporting both current and legacy env vars.
+ */
+export const BRIDGE_STATE_PATH = process.env.MCP_HOST_BRIDGE_STATE || process.env.MINDSTONE_REBEL_BRIDGE_STATE || '';
+const loadBridgeState = () => {
+    if (!BRIDGE_STATE_PATH)
+        return null;
+    try {
+        const raw = fs.readFileSync(BRIDGE_STATE_PATH, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Send a request to the host app bridge.
+ *
+ * The bridge is an HTTP server running inside the host app (e.g. Rebel)
+ * that handles credential management and other cross-process operations.
+ */
+export const bridgeRequest = async (urlPath, body) => {
+    const bridge = loadBridgeState();
+    if (!bridge) {
+        return { success: false, error: 'Bridge not available' };
+    }
+    const response = await fetch(`http://127.0.0.1:${bridge.port}${urlPath}`, {
+        method: 'POST',
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${bridge.token}`,
+        },
+        body: JSON.stringify(body),
+    });
+    if (response.status === 401 || response.status === 403) {
+        return { success: false, error: `Bridge returned ${response.status}: unauthorized. Check host app authentication.` };
+    }
+    return response.json();
+};
+//# sourceMappingURL=bridge.js.map

package/dist/client.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Mixmax API HTTP client.
+ *
+ * Centralises X-API-Token header injection, error handling, and rate-limit
+ * messaging for all Mixmax API calls.
+ */
+/**
+ * Make an authenticated request to the Mixmax API.
+ *
+ * @param path  API path relative to base, e.g. `/sequences`
+ * @param options  Additional fetch options
+ * @returns Parsed JSON response
+ */
+export declare function mixmaxFetch<T>(path: string, options?: RequestInit): Promise<T>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -0,0 +1,62 @@
+/**
+ * Mixmax API HTTP client.
+ *
+ * Centralises X-API-Token header injection, error handling, and rate-limit
+ * messaging for all Mixmax API calls.
+ */
+import { getApiToken } from './auth.js';
+import { MixmaxError, MIXMAX_API_BASE, REQUEST_TIMEOUT_MS } from './types.js';
+/**
+ * Make an authenticated request to the Mixmax API.
+ *
+ * @param path  API path relative to base, e.g. `/sequences`
+ * @param options  Additional fetch options
+ * @returns Parsed JSON response
+ */
+export async function mixmaxFetch(path, options = {}) {
+    const token = getApiToken();
+    if (!token) {
+        throw new MixmaxError('Mixmax API token not configured', 'AUTH_REQUIRED', 'Use configure_mixmax_api_key to set your API token first.');
+    }
+    const url = `${MIXMAX_API_BASE}${path}`;
+    let response;
+    try {
+        response = await fetch(url, {
+            ...options,
+            signal: options.signal ?? AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            headers: {
+                'X-API-Token': token,
+                'Content-Type': 'application/json',
+                ...options.headers,
+            },
+        });
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'TimeoutError') {
+            throw new MixmaxError('Request to Mixmax API timed out', 'TIMEOUT', 'The request took too long. Try again or check if the Mixmax API is available.');
+        }
+        throw error;
+    }
+    if (response.status === 401 || response.status === 403) {
+        throw new MixmaxError('Authentication failed', 'AUTH_FAILED', 'Your Mixmax API token is invalid or revoked. Use configure_mixmax_api_key to set a new token.');
+    }
+    if (response.status === 429) {
+        const retryAfter = response.headers.get('Retry-After');
+        const parsed = retryAfter ? parseInt(retryAfter, 10) : NaN;
+        const waitSeconds = Number.isFinite(parsed) ? parsed : 60;
+        throw new MixmaxError(`Rate limited by Mixmax API. Please wait ${waitSeconds} seconds before retrying.`, 'RATE_LIMITED', `Wait ${waitSeconds} seconds and try again. Mixmax limits to 120 requests per minute.`);
+    }
+    if (response.status === 404) {
+        throw new MixmaxError('Resource not found', 'NOT_FOUND', 'The requested resource does not exist or you do not have permission to access it.');
+    }
+    if (!response.ok) {
+        const errorText = await response.text().catch(() => 'Unknown error');
+        throw new MixmaxError(`Mixmax API error (${response.status}): ${errorText}`, 'API_ERROR', 'Check the request parameters and try again.');
+    }
+    // Some endpoints (e.g. POST with 204) may return empty body
+    const text = await response.text();
+    if (!text)
+        return {};
+    return JSON.parse(text);
+}
+//# sourceMappingURL=client.js.map

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * Mixmax MCP Server
+ *
+ * Provides Mixmax email productivity integration via Model Context Protocol.
+ * Supports sequences (drip campaigns), email sending with tracking,
+ * templates (snippets), meeting scheduling, and user info.
+ *
+ * Environment variables:
+ * - MIXMAX_API_TOKEN: User's Mixmax API token — required for all operations
+ * - MCP_HOST_BRIDGE_STATE: Path to host app bridge state file (optional)
+ * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy bridge state path (optional)
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * Mixmax MCP Server
+ *
+ * Provides Mixmax email productivity integration via Model Context Protocol.
+ * Supports sequences (drip campaigns), email sending with tracking,
+ * templates (snippets), meeting scheduling, and user info.
+ *
+ * Environment variables:
+ * - MIXMAX_API_TOKEN: User's Mixmax API token — required for all operations
+ * - MCP_HOST_BRIDGE_STATE: Path to host app bridge state file (optional)
+ * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy bridge state path (optional)
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('Mixmax MCP server running on stdio');
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createServer(): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,16 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerConfigureTools, registerSequenceTools, registerMessageTools, registerSnippetTools, registerMeetingTools, registerUserTools, } from './tools/index.js';
+export function createServer() {
+    const server = new McpServer({
+        name: 'mixmax-mcp-server',
+        version: '0.1.0',
+    });
+    registerConfigureTools(server);
+    registerSequenceTools(server);
+    registerMessageTools(server);
+    registerSnippetTools(server);
+    registerMeetingTools(server);
+    registerUserTools(server);
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/tools/configure.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerConfigureTools(server: McpServer): void;
+//# sourceMappingURL=configure.d.ts.map

package/dist/tools/configure.js

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import { setApiToken } from '../auth.js';
+import { bridgeRequest, BRIDGE_STATE_PATH } from '../bridge.js';
+import { MixmaxError } from '../types.js';
+import { withErrorHandling } from '../utils.js';
+export function registerConfigureTools(server) {
+    server.registerTool('configure_mixmax_api_key', {
+        description: 'Configure the Mixmax API token. Call this tool when the user provides their Mixmax API token. ' +
+            'Get your token from https://app.mixmax.com/dashboard/settings/personal/integrations — ' +
+            'scroll to "API Key" section and click "Generate Token". ' +
+            'Requires a Mixmax Growth or Enterprise annual plan.',
+        inputSchema: z.object({
+            api_key: z.string().min(1).describe('The Mixmax API token from Settings > Integrations'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        const trimmedToken = args.api_key.trim();
+        // If bridge is available, persist via bridge
+        if (BRIDGE_STATE_PATH) {
+            try {
+                const result = await bridgeRequest('/bundled/mixmax/configure', { apiKey: trimmedToken });
+                if (result.success) {
+                    setApiToken(trimmedToken);
+                    const message = result.warning
+                        ? `Mixmax API token configured successfully. Note: ${result.warning}`
+                        : 'Mixmax API token configured successfully! You can now use Mixmax tools to manage sequences, emails, and templates.';
+                    return JSON.stringify({ ok: true, message });
+                }
+                // Bridge returned failure — surface as error, do NOT fall through
+                throw new MixmaxError(result.error || 'Bridge configuration failed', 'BRIDGE_ERROR', 'The host app bridge rejected the configuration request. Check the host app logs.');
+            }
+            catch (error) {
+                if (error instanceof MixmaxError)
+                    throw error;
+                // Bridge request failed (network, timeout, etc.) — surface as error
+                throw new MixmaxError(`Bridge request failed: ${error instanceof Error ? error.message : String(error)}`, 'BRIDGE_ERROR', 'Could not reach the host app bridge. Ensure the host app is running.');
+            }
+        }
+        // No bridge configured — configure in-memory only
+        setApiToken(trimmedToken);
+        return JSON.stringify({
+            ok: true,
+            message: 'Mixmax API token configured successfully! You can now use Mixmax tools to manage sequences, emails, and templates.',
+        });
+    }));
+}
+//# sourceMappingURL=configure.js.map

package/dist/tools/index.d.ts

@@ -0,0 +1,7 @@
+export { registerConfigureTools } from './configure.js';
+export { registerSequenceTools } from './sequences.js';
+export { registerMessageTools } from './messages.js';
+export { registerSnippetTools } from './snippets.js';
+export { registerMeetingTools } from './meetings.js';
+export { registerUserTools } from './user.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.js

@@ -0,0 +1,7 @@
+export { registerConfigureTools } from './configure.js';
+export { registerSequenceTools } from './sequences.js';
+export { registerMessageTools } from './messages.js';
+export { registerSnippetTools } from './snippets.js';
+export { registerMeetingTools } from './meetings.js';
+export { registerUserTools } from './user.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/meetings.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerMeetingTools(server: McpServer): void;
+//# sourceMappingURL=meetings.d.ts.map

package/dist/tools/meetings.js

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+import { mixmaxFetch } from '../client.js';
+import { withErrorHandling } from '../utils.js';
+import { isConfigured } from '../auth.js';
+function noApiTokenError() {
+    return JSON.stringify({
+        ok: false,
+        error: 'Mixmax API token not configured',
+        resolution: 'To use Mixmax, you need to configure an API token first.',
+        next_step: {
+            action: 'Ask the user for their Mixmax API token, then call configure_mixmax_api_key',
+            tool_to_call: 'configure_mixmax_api_key',
+            tool_parameters: { api_key: '<user_provided_token>' },
+            get_token_from: 'Mixmax Settings > Integrations > API Key section (requires Growth or Enterprise annual plan)',
+        },
+    });
+}
+export function registerMeetingTools(server) {
+    server.registerTool('list_mixmax_meeting_types', {
+        description: `List Mixmax meeting/scheduling link types configured by the user.
+
+Returns for each meeting type:
+- name: Meeting type label (e.g. "30 min intro call", "60 min deep dive")
+- duration: Length in minutes
+- location: Where the meeting happens (Zoom, Google Meet, phone, etc.)
+- slug / link: The booking URL that can be shared with contacts
+
+USE CASES:
+- "Share my scheduling link" — find the meeting type, give the user the booking URL to share
+- "What meeting types do I have?" — list them with durations and locations
+- "Send Alice my 30-min call link" — find the right type, then use the URL in send_mixmax_email`,
+        inputSchema: z.object({}),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async () => {
+        if (!isConfigured())
+            return noApiTokenError();
+        const data = await mixmaxFetch('/meetingtypes');
+        return JSON.stringify({
+            ok: true,
+            meetingTypes: data.results || data,
+            count: Array.isArray(data.results) ? data.results.length : undefined,
+        });
+    }));
+}
+//# sourceMappingURL=meetings.js.map

package/dist/tools/messages.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerMessageTools(server: McpServer): void;
+//# sourceMappingURL=messages.d.ts.map

package/dist/tools/messages.js

@@ -0,0 +1,96 @@
+import { z } from 'zod';
+import { mixmaxFetch } from '../client.js';
+import { withErrorHandling } from '../utils.js';
+import { isConfigured } from '../auth.js';
+function noApiTokenError() {
+    return JSON.stringify({
+        ok: false,
+        error: 'Mixmax API token not configured',
+        resolution: 'To use Mixmax, you need to configure an API token first.',
+        next_step: {
+            action: 'Ask the user for their Mixmax API token, then call configure_mixmax_api_key',
+            tool_to_call: 'configure_mixmax_api_key',
+            tool_parameters: { api_key: '<user_provided_token>' },
+            get_token_from: 'Mixmax Settings > Integrations > API Key section (requires Growth or Enterprise annual plan)',
+        },
+    });
+}
+export function registerMessageTools(server) {
+    server.registerTool('list_mixmax_messages', {
+        description: `List emails sent through Mixmax with open/click tracking data.
+
+Returns for each message:
+- _id, subject, recipients (to/cc/bcc)
+- sentAt / scheduledAt: When it was sent or is scheduled
+- opens: Number of times opened, with timestamps
+- clicks: Links clicked, with URLs and timestamps
+- state: "sent", "draft", or "scheduled"
+
+USE CASES:
+- "Show my recent emails" — call with no params
+- "Did they open my email?" — find the message, check opens count/timestamps
+- "What emails are scheduled?" — look for state: "scheduled"
+
+PAGINATION: Cursor-based. If hasNext is true, pass the "next" value as the next parameter.`,
+        inputSchema: z.object({
+            limit: z.number().min(1).max(100).default(25).describe('Maximum results to return (default: 25)'),
+            next: z.string().optional().describe('Cursor for next page (from previous response)'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        if (!isConfigured())
+            return noApiTokenError();
+        let path = `/messages?limit=${args.limit}`;
+        if (args.next)
+            path += `&next=${encodeURIComponent(args.next)}`;
+        const data = await mixmaxFetch(path);
+        return JSON.stringify({
+            ok: true,
+            messages: data.results || [],
+            count: (data.results || []).length,
+            hasNext: data.hasNext ?? false,
+            ...(data.next ? { next: data.next } : {}),
+        });
+    }));
+    server.registerTool('send_mixmax_email', {
+        description: `Send an email via Mixmax through the user's connected Gmail account. Open and click tracking is enabled automatically.
+
+IMPORTANT: Confirm with the user before sending — this sends a real email immediately.
+
+BODY FORMAT: HTML is supported. Use <p>, <br>, <b>, <ul>, etc. for formatting. Plain text also works.
+
+TRACKING: Mixmax automatically tracks opens and clicks. The user can check tracking data later via list_mixmax_messages.
+
+NOTE: This sends through Mixmax, not raw Gmail. The email will appear in the user's Gmail sent folder with Mixmax tracking pixels.`,
+        inputSchema: z.object({
+            to: z.array(z.string().email()).min(1).describe('Recipient email addresses'),
+            subject: z.string().min(1).describe('Email subject line'),
+            body: z.string().min(1).describe('Email body (HTML supported — use <p>, <br>, <b>, <ul> for formatting)'),
+            cc: z.array(z.string().email()).optional().describe('CC recipient email addresses (optional)'),
+            bcc: z.array(z.string().email()).optional().describe('BCC recipient email addresses (optional)'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        if (!isConfigured())
+            return noApiTokenError();
+        const payload = {
+            to: args.to.map((email) => ({ email })),
+            subject: args.subject,
+            body: args.body,
+        };
+        if (args.cc && args.cc.length > 0)
+            payload.cc = args.cc.map((email) => ({ email }));
+        if (args.bcc && args.bcc.length > 0)
+            payload.bcc = args.bcc.map((email) => ({ email }));
+        const data = await mixmaxFetch('/send', {
+            method: 'POST',
+            body: JSON.stringify(payload),
+        });
+        return JSON.stringify({
+            ok: true,
+            message: `Email sent to ${args.to.join(', ')}.`,
+            result: data,
+        });
+    }));
+}
+//# sourceMappingURL=messages.js.map

package/dist/tools/sequences.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerSequenceTools(server: McpServer): void;
+//# sourceMappingURL=sequences.d.ts.map

package/dist/tools/sequences.js

@@ -0,0 +1,109 @@
+import { z } from 'zod';
+import { mixmaxFetch } from '../client.js';
+import { withErrorHandling } from '../utils.js';
+import { isConfigured } from '../auth.js';
+function noApiTokenError() {
+    return JSON.stringify({
+        ok: false,
+        error: 'Mixmax API token not configured',
+        resolution: 'To use Mixmax, you need to configure an API token first.',
+        next_step: {
+            action: 'Ask the user for their Mixmax API token, then call configure_mixmax_api_key',
+            tool_to_call: 'configure_mixmax_api_key',
+            tool_parameters: { api_key: '<user_provided_token>' },
+            get_token_from: 'Mixmax Settings > Integrations > API Key section (requires Growth or Enterprise annual plan)',
+        },
+    });
+}
+export function registerSequenceTools(server) {
+    server.registerTool('list_mixmax_sequences', {
+        description: `List Mixmax sequences (automated email drip campaigns).
+
+Returns for each sequence:
+- _id: Use with get_mixmax_sequence for full details or add_mixmax_sequence_recipients to enroll people
+- name: Sequence name
+- numStages: Number of email stages in the drip
+- isPaused: Whether the sequence is currently active
+- numRecipients / numFinished / numBounced: Recipient stats
+
+TYPICAL WORKFLOW:
+1. list_mixmax_sequences to find the sequence
+2. get_mixmax_sequence with the _id to see stages/content
+3. add_mixmax_sequence_recipients to enroll contacts
+
+PAGINATION: Cursor-based. If hasNext is true, pass the "next" value as the next parameter to fetch more.`,
+        inputSchema: z.object({
+            limit: z.number().min(1).max(100).default(25).describe('Maximum results to return (default: 25)'),
+            next: z.string().optional().describe('Cursor for next page (from previous response)'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        if (!isConfigured())
+            return noApiTokenError();
+        let path = `/sequences?limit=${args.limit}`;
+        if (args.next)
+            path += `&next=${encodeURIComponent(args.next)}`;
+        const data = await mixmaxFetch(path);
+        return JSON.stringify({
+            ok: true,
+            sequences: data.results || [],
+            count: (data.results || []).length,
+            hasNext: data.hasNext ?? false,
+            ...(data.next ? { next: data.next } : {}),
+        });
+    }));
+    server.registerTool('get_mixmax_sequence', {
+        description: `Get full details for a single Mixmax sequence including all stages.
+
+Returns:
+- name, isPaused, createdAt
+- stages: Array of email steps, each with subject line, body content, delay settings, and send window
+- Recipient statistics (total, finished, bounced, paused)
+- Scheduling rules (send window, timezone, skip weekends)
+
+USE list_mixmax_sequences FIRST to find the _id.`,
+        inputSchema: z.object({
+            sequenceId: z.string().min(1).describe('The _id of the sequence (from list_mixmax_sequences)'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        if (!isConfigured())
+            return noApiTokenError();
+        const data = await mixmaxFetch(`/sequences/${encodeURIComponent(args.sequenceId)}?expand=stages`);
+        return JSON.stringify({ ok: true, sequence: data });
+    }));
+    server.registerTool('add_mixmax_sequence_recipients', {
+        description: `Add recipients to a Mixmax sequence, enrolling them in the automated email drip campaign.
+
+IMPORTANT: Confirm with the user before calling — this adds real people to a live sequence and they WILL receive emails starting from stage 1.
+
+WORKFLOW:
+1. list_mixmax_sequences to find the sequence _id
+2. Optionally get_mixmax_sequence to review the stages/content with the user
+3. Confirm recipient list with user
+4. Call this tool
+
+TEMPLATE VARIABLES: If the sequence stages use variables like {{first_name}}, pass them in the variables object for each recipient.`,
+        inputSchema: z.object({
+            sequenceId: z.string().min(1).describe('The _id of the sequence to add recipients to'),
+            recipients: z.array(z.object({
+                email: z.string().email().describe('Recipient email address'),
+                variables: z.record(z.unknown()).optional().describe('Template variables for personalisation'),
+            })).min(1).describe('Array of recipients to add (each must have an email)'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        if (!isConfigured())
+            return noApiTokenError();
+        const data = await mixmaxFetch(`/sequences/${encodeURIComponent(args.sequenceId)}/recipients`, {
+            method: 'POST',
+            body: JSON.stringify({ recipients: args.recipients }),
+        });
+        return JSON.stringify({
+            ok: true,
+            message: `Added ${args.recipients.length} recipient(s) to sequence.`,
+            result: data,
+        });
+    }));
+}
+//# sourceMappingURL=sequences.js.map

package/dist/tools/snippets.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerSnippetTools(server: McpServer): void;
+//# sourceMappingURL=snippets.d.ts.map

package/dist/tools/snippets.js

@@ -0,0 +1,92 @@
+import { z } from 'zod';
+import { mixmaxFetch } from '../client.js';
+import { withErrorHandling } from '../utils.js';
+import { isConfigured } from '../auth.js';
+function noApiTokenError() {
+    return JSON.stringify({
+        ok: false,
+        error: 'Mixmax API token not configured',
+        resolution: 'To use Mixmax, you need to configure an API token first.',
+        next_step: {
+            action: 'Ask the user for their Mixmax API token, then call configure_mixmax_api_key',
+            tool_to_call: 'configure_mixmax_api_key',
+            tool_parameters: { api_key: '<user_provided_token>' },
+            get_token_from: 'Mixmax Settings > Integrations > API Key section (requires Growth or Enterprise annual plan)',
+        },
+    });
+}
+export function registerSnippetTools(server) {
+    server.registerTool('list_mixmax_snippets', {
+        description: `List Mixmax email templates (called "snippets" in Mixmax).
+
+Returns for each snippet:
+- _id: Use with send_mixmax_snippet to send it
+- name: Template name
+- subject: Email subject line the template uses
+- body: HTML body content (check for template variables like {{first_name}})
+- isShared: Whether it's shared with the team or personal
+
+WORKFLOW FOR SENDING A TEMPLATE:
+1. list_mixmax_snippets to browse available templates
+2. Review the body for template variables (e.g. {{first_name}}, {{company}})
+3. send_mixmax_snippet with the _id, recipients, and matching variables
+
+PAGINATION: Cursor-based. If hasNext is true, pass the "next" value as the next parameter.`,
+        inputSchema: z.object({
+            limit: z.number().min(1).max(100).default(25).describe('Maximum results to return (default: 25)'),
+            next: z.string().optional().describe('Cursor for next page (from previous response)'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        if (!isConfigured())
+            return noApiTokenError();
+        let path = `/snippets?limit=${args.limit}`;
+        if (args.next)
+            path += `&next=${encodeURIComponent(args.next)}`;
+        const data = await mixmaxFetch(path);
+        return JSON.stringify({
+            ok: true,
+            snippets: data.results || [],
+            count: (data.results || []).length,
+            hasNext: data.hasNext ?? false,
+            ...(data.next ? { next: data.next } : {}),
+        });
+    }));
+    server.registerTool('send_mixmax_snippet', {
+        description: `Send a Mixmax template (snippet) to one or more recipients.
+
+IMPORTANT: Confirm with the user before sending — this sends a real email using the template content.
+
+WORKFLOW:
+1. list_mixmax_snippets to find the template and its _id
+2. Check the snippet body for template variables (e.g. {{first_name}}, {{company}})
+3. Confirm recipients and variable values with user
+4. Call this tool with matching variables
+
+NOTE: Variables are applied to ALL recipients equally. If you need different variables per recipient, send one at a time.`,
+        inputSchema: z.object({
+            snippetId: z.string().min(1).describe('The _id of the snippet/template (from list_mixmax_snippets)'),
+            to: z.array(z.string().email()).min(1).describe('Recipient email addresses'),
+            variables: z.record(z.unknown()).optional().describe('Template variables matching {{placeholders}} in the snippet body'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        if (!isConfigured())
+            return noApiTokenError();
+        const payload = {
+            to: args.to.map((email) => ({ email })),
+        };
+        if (args.variables)
+            payload.variables = args.variables;
+        const data = await mixmaxFetch(`/snippets/${encodeURIComponent(args.snippetId)}/send`, {
+            method: 'POST',
+            body: JSON.stringify(payload),
+        });
+        return JSON.stringify({
+            ok: true,
+            message: `Snippet sent to ${args.to.join(', ')}.`,
+            result: data,
+        });
+    }));
+}
+//# sourceMappingURL=snippets.js.map

package/dist/tools/user.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerUserTools(server: McpServer): void;
+//# sourceMappingURL=user.d.ts.map

package/dist/tools/user.js

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import { mixmaxFetch } from '../client.js';
+import { withErrorHandling } from '../utils.js';
+import { isConfigured } from '../auth.js';
+function noApiTokenError() {
+    return JSON.stringify({
+        ok: false,
+        error: 'Mixmax API token not configured',
+        resolution: 'To use Mixmax, you need to configure an API token first.',
+        next_step: {
+            action: 'Ask the user for their Mixmax API token, then call configure_mixmax_api_key',
+            tool_to_call: 'configure_mixmax_api_key',
+            tool_parameters: { api_key: '<user_provided_token>' },
+            get_token_from: 'Mixmax Settings > Integrations > API Key section (requires Growth or Enterprise annual plan)',
+        },
+    });
+}
+export function registerUserTools(server) {
+    server.registerTool('get_mixmax_user', {
+        description: `Get the current Mixmax user's profile and account info.
+
+Returns:
+- name, email: User identity
+- plan: Current Mixmax plan (Growth, Enterprise, etc.)
+- integrations: Connected services (Gmail, Salesforce, etc.)
+
+USE CASES:
+- Verify which account is connected
+- Check plan level (relevant if a feature requires Enterprise)
+- See what integrations the user has active`,
+        inputSchema: z.object({}),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async () => {
+        if (!isConfigured())
+            return noApiTokenError();
+        const data = await mixmaxFetch('/users/me');
+        return JSON.stringify({ ok: true, user: data });
+    }));
+}
+//# sourceMappingURL=user.js.map

package/dist/types.d.ts

@@ -0,0 +1,71 @@
+export declare const REQUEST_TIMEOUT_MS = 30000;
+export declare const MIXMAX_API_BASE = "https://api.mixmax.com/v1";
+export interface BridgeState {
+    port: number;
+    token: string;
+}
+export declare class MixmaxError extends Error {
+    readonly code: string;
+    readonly resolution: string;
+    constructor(message: string, code: string, resolution: string);
+}
+export interface SequenceItem {
+    _id: string;
+    name: string;
+    numStages?: number;
+    isPaused?: boolean;
+    numRecipients?: number;
+    numFinished?: number;
+    numBounced?: number;
+    createdAt?: string;
+}
+export interface SequencesResponse {
+    results: SequenceItem[];
+    hasNext?: boolean;
+    next?: string;
+}
+export interface MessagesResponse {
+    results: MessageItem[];
+    hasNext?: boolean;
+    next?: string;
+}
+export interface MessageItem {
+    _id: string;
+    subject?: string;
+    recipients?: {
+        to?: Array<{
+            email: string;
+        }>;
+        cc?: Array<{
+            email: string;
+        }>;
+        bcc?: Array<{
+            email: string;
+        }>;
+    };
+    sentAt?: string;
+    scheduledAt?: string;
+    opens?: number;
+    clicks?: number;
+    state?: string;
+}
+export interface SnippetsResponse {
+    results: SnippetItem[];
+    hasNext?: boolean;
+    next?: string;
+}
+export interface SnippetItem {
+    _id: string;
+    name?: string;
+    subject?: string;
+    body?: string;
+    isShared?: boolean;
+}
+export interface MeetingType {
+    name?: string;
+    duration?: number;
+    location?: string;
+    slug?: string;
+    link?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,13 @@
+export const REQUEST_TIMEOUT_MS = 30_000;
+export const MIXMAX_API_BASE = 'https://api.mixmax.com/v1';
+export class MixmaxError extends Error {
+    code;
+    resolution;
+    constructor(message, code, resolution) {
+        super(message);
+        this.code = code;
+        this.resolution = resolution;
+        this.name = 'MixmaxError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/utils.d.ts

@@ -0,0 +1,14 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+type ToolHandler<T> = (args: T, extra: unknown) => Promise<CallToolResult>;
+/**
+ * Wraps a tool handler with standard error handling.
+ *
+ * - On success: returns the string result as a text content block.
+ * - On MixmaxError: returns a structured JSON error with code and resolution.
+ * - On unknown error: returns a generic error message.
+ *
+ * Secrets are never exposed in error messages.
+ */
+export declare function withErrorHandling<T>(fn: (args: T, extra: unknown) => Promise<string>): ToolHandler<T>;
+export {};
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.js

@@ -0,0 +1,42 @@
+import { MixmaxError } from './types.js';
+/**
+ * Wraps a tool handler with standard error handling.
+ *
+ * - On success: returns the string result as a text content block.
+ * - On MixmaxError: returns a structured JSON error with code and resolution.
+ * - On unknown error: returns a generic error message.
+ *
+ * Secrets are never exposed in error messages.
+ */
+export function withErrorHandling(fn) {
+    return async (args, extra) => {
+        try {
+            const result = await fn(args, extra);
+            return { content: [{ type: 'text', text: result }] };
+        }
+        catch (error) {
+            if (error instanceof MixmaxError) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                ok: false,
+                                error: error.message,
+                                code: error.code,
+                                resolution: error.resolution,
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ ok: false, error: errorMessage }) }],
+                isError: true,
+            };
+        }
+    };
+}
+//# sourceMappingURL=utils.js.map

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@mindstone-engineering/mcp-server-mixmax",
+  "version": "0.1.0",
+  "description": "Mixmax email productivity MCP server for Model Context Protocol hosts",
+  "license": "FSL-1.1-MIT",
+  "type": "module",
+  "bin": {
+    "mcp-server-mixmax": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nspr-io/mcp-servers.git",
+    "directory": "connectors/mixmax"
+  },
+  "homepage": "https://github.com/nspr-io/mcp-servers/tree/main/connectors/mixmax",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && shx chmod +x dist/index.js",
+    "prepare": "npm run build",
+    "watch": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@mindstone-engineering/mcp-test-harness": "file:../../test-harness",
+    "@types/node": "^22",
+    "@vitest/coverage-v8": "^4.1.3",
+    "msw": "^2.13.2",
+    "shx": "^0.3.4",
+    "typescript": "^5.8.2",
+    "vitest": "^4.1.3"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}