@mailloom/mcp 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,81 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @mailloom/mcp
+
+Official [Model Context Protocol](https://modelcontextprotocol.io) server for [Mailloom](https://mailloom.app) — manage email templates, brand kits, and assets from Cursor, Claude, and other MCP hosts.
+
+## Setup
+
+1. Sign in to Mailloom → **Account settings**.
+2. Ensure **Allow MCP / API write access** is on (default) if agents should mutate data.
+3. **Create key** and copy the `ml_live_…` secret once.
+
+API auth runs in the Supabase Edge Function `mailloom-api` (service role never leaves Supabase). Prefer the Next `/api/v1` base so `export_template` works; that route proxies CRUD to the edge function.
+
+### Cursor (`mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "mailloom": {
+      "command": "npx",
+      "args": ["-y", "@mailloom/mcp"],
+      "env": {
+        "MAILLOOM_API_KEY": "ml_live_…",
+        "MAILLOOM_API_BASE": "http://localhost:3847/api/v1"
+      }
+    }
+  }
+}
+```
+
+Production Next: `https://your-host/api/v1`.  
+Edge Function only (CRUD, no HTML export): `https://<project>.supabase.co/functions/v1/mailloom-api`.
+
+### Local package (unpublished)
+
+```bash
+cd packages/mailloom-mcp
+npm install
+npm run build
+```
+
+```json
+{
+  "mcpServers": {
+    "mailloom": {
+      "command": "node",
+      "args": ["/absolute/path/to/packages/mailloom-mcp/dist/index.js"],
+      "env": {
+        "MAILLOOM_API_KEY": "ml_live_…",
+        "MAILLOOM_API_BASE": "http://localhost:3847/api/v1"
+      }
+    }
+  }
+}
+```
+
+## Environment
+
+| Variable | Required | Default | Purpose |
+| --- | --- | --- | --- |
+| `MAILLOOM_API_KEY` | yes | — | `ml_live_…` from Account settings |
+| `MAILLOOM_API_BASE` | no | `http://localhost:3847/api/v1` | API origin including `/api/v1` |
+
+## Tools
+
+| Tool | Write? | Description |
+| --- | --- | --- |
+| `health_check` | | API liveness + write flag |
+| `get_account` | | Email, write flag, key metadata |
+| `list_templates` / `get_template` | | Templates (user + platform) |
+| `create_template` / `update_template` / `duplicate_template` / `delete_template` | ✓ | Mutate user templates |
+| `export_template` | | Render HTML (optional inline CSS) |
+| `list_brand_kits` / `get_brand_kit` | | Brand kits |
+| `create_brand_kit` / `update_brand_kit` / `delete_brand_kit` | ✓ | Mutate kits |
+| `list_assets` | | Assets |
+| `upload_asset` / `delete_asset` | ✓ | Upload (base64/url) / delete |
+
+When write access is disabled in Account settings, write tools return `403 write_disabled`. Platform templates stay read-only; duplicate them to edit.
+
+## License
+
+MIT

package/bin/mailloom-mcp.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/index.js'

package/dist/client.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Thin Mailloom API client for MCP.
+ * Auth: Authorization Bearer ml_live_…
+ *
+ * Prefer Next /api/v1 (proxies to the mailloom-api Edge Function + HTML export).
+ * Or point at https://<project>.supabase.co/functions/v1/mailloom-api for CRUD only.
+ */
+export type ApiConfig = {
+    baseUrl: string;
+    apiKey: string;
+};
+export declare function loadConfig(): ApiConfig;
+export declare function apiRequest(config: ApiConfig, method: string, path: string, opts?: {
+    body?: unknown;
+    query?: Record<string, string | number | undefined | null>;
+}): Promise<unknown>;
+export declare function jsonResult(data: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function errorResult(err: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+};

package/dist/client.js

@@ -0,0 +1,78 @@
+/**
+ * Thin Mailloom API client for MCP.
+ * Auth: Authorization Bearer ml_live_…
+ *
+ * Prefer Next /api/v1 (proxies to the mailloom-api Edge Function + HTML export).
+ * Or point at https://<project>.supabase.co/functions/v1/mailloom-api for CRUD only.
+ */
+const DEFAULT_BASE = 'http://localhost:3847/api/v1';
+export function loadConfig() {
+    const apiKey = (process.env.MAILLOOM_API_KEY || '').trim();
+    if (!apiKey) {
+        throw new Error('MAILLOOM_API_KEY is required (ml_live_…). Create one in Mailloom → Account settings.');
+    }
+    if (!apiKey.startsWith('ml_live_')) {
+        throw new Error('MAILLOOM_API_KEY must start with ml_live_');
+    }
+    const baseUrl = (process.env.MAILLOOM_API_BASE || DEFAULT_BASE).replace(/\/$/, '');
+    return { baseUrl, apiKey };
+}
+export async function apiRequest(config, method, path, opts) {
+    const url = new URL(path.startsWith('http') ? path : `${config.baseUrl}${path.startsWith('/') ? path : `/${path}`}`);
+    if (opts?.query) {
+        for (const [k, v] of Object.entries(opts.query)) {
+            if (v !== undefined && v !== null && String(v) !== '') {
+                url.searchParams.set(k, String(v));
+            }
+        }
+    }
+    const headers = {
+        Authorization: `Bearer ${config.apiKey}`,
+        Accept: 'application/json',
+    };
+    if (opts?.body !== undefined) {
+        headers['Content-Type'] = 'application/json';
+    }
+    const res = await fetch(url, {
+        method,
+        headers,
+        body: opts?.body !== undefined ? JSON.stringify(opts.body) : undefined,
+    });
+    const text = await res.text();
+    let data = null;
+    if (text) {
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            data = { raw: text };
+        }
+    }
+    if (!res.ok) {
+        const msg = data && typeof data === 'object' && 'error' in data
+            ? String(data.error)
+            : `HTTP ${res.status}`;
+        const code = data && typeof data === 'object' && 'code' in data
+            ? String(data.code)
+            : undefined;
+        throw new Error(code ? `${msg} (${code})` : msg);
+    }
+    return data;
+}
+export function jsonResult(data) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+}
+export function errorResult(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+        content: [{ type: 'text', text: message }],
+        isError: true,
+    };
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+/**
+ * Official Mailloom MCP server — templates, brand kits, assets for AI hosts.
+ *
+ * Env:
+ *   MAILLOOM_API_KEY   required — ml_live_…
+ *   MAILLOOM_API_BASE  optional — default http://localhost:3847/api/v1
+ *
+ * Write tools require Account settings → Allow MCP / API write access (default on).
+ * When disabled, mutating tools return 403 write_disabled; reads still work.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { apiRequest, errorResult, jsonResult, loadConfig } from './client.js';
+const PACKAGE_VERSION = '0.1.0';
+const config = loadConfig();
+const server = new McpServer({
+    name: 'mailloom',
+    version: PACKAGE_VERSION,
+});
+function tool(name, description, schema, handler) {
+    server.tool(name, description, schema, async (args) => {
+        try {
+            const data = await handler(args);
+            return jsonResult(data);
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}
+// —— Account ——
+tool('health_check', 'Check Mailloom API liveness and whether write access is enabled.', {}, async () => apiRequest(config, 'GET', '/health'));
+tool('get_account', 'Get account email, MCP write-enabled flag, and current API key metadata (never the secret).', {}, async () => apiRequest(config, 'GET', '/me'));
+// —— Templates ——
+tool('list_templates', 'List user and platform email templates.', {}, async () => apiRequest(config, 'GET', '/templates'));
+tool('get_template', 'Get one template by id (includes full email document).', { id: z.string().uuid().describe('Template UUID') }, async (args) => apiRequest(config, 'GET', `/templates/${args.id}`));
+tool('create_template', 'Create a user template. Requires write access. document matches the editor shape (settings + blocks).', {
+    name: z.string().describe('Template name'),
+    document: z.record(z.unknown()).describe('Email document (settings + blocks)'),
+    brand_kit_id: z.string().uuid().nullable().optional().describe('Optional brand kit UUID'),
+}, async (args) => apiRequest(config, 'POST', '/templates', {
+    body: {
+        name: args.name,
+        document: args.document,
+        brand_kit_id: args.brand_kit_id,
+    },
+}));
+tool('update_template', 'Update a user template name and/or document. Platform templates are read-only — duplicate first. Requires write access.', {
+    id: z.string().uuid().describe('Template UUID'),
+    name: z.string().optional().describe('New name'),
+    document: z.record(z.unknown()).optional().describe('Full email document'),
+    brand_kit_id: z.string().uuid().nullable().optional().describe('Brand kit UUID or null'),
+}, async (args) => {
+    const { id, ...body } = args;
+    return apiRequest(config, 'PATCH', `/templates/${id}`, { body });
+});
+tool('duplicate_template', 'Copy a platform or user template into a new editable user template. Requires write access.', {
+    id: z.string().uuid().describe('Source template UUID'),
+    name: z.string().optional().describe('Name for the copy'),
+}, async (args) => apiRequest(config, 'POST', `/templates/${args.id}/duplicate`, {
+    body: { name: args.name },
+}));
+tool('delete_template', 'Delete a user template. Platform templates cannot be deleted. Requires write access.', { id: z.string().uuid().describe('Template UUID') }, async (args) => apiRequest(config, 'DELETE', `/templates/${args.id}`));
+tool('export_template', 'Render a template as email HTML (inline CSS by default). Read-only.', {
+    id: z.string().uuid().describe('Template UUID'),
+    inline: z.boolean().optional().describe('Inline CSS (default true)'),
+}, async (args) => apiRequest(config, 'POST', `/templates/${args.id}/export`, {
+    body: { inline: args.inline },
+}));
+// —— Brand kits ——
+tool('list_brand_kits', 'List brand kits for the account.', {}, async () => apiRequest(config, 'GET', '/brand-kits'));
+tool('get_brand_kit', 'Get one brand kit by id.', { id: z.string().uuid().describe('Brand kit UUID') }, async (args) => apiRequest(config, 'GET', `/brand-kits/${args.id}`));
+tool('create_brand_kit', 'Create a brand kit (colors, fonts, tone, logo_path). Requires write access.', {
+    name: z.string().describe('Kit name'),
+    data: z
+        .record(z.unknown())
+        .optional()
+        .describe('BrandKitData: colors, fonts, tone, company, socialDefaults, …'),
+    logo_path: z.string().nullable().optional().describe('Storage path in assets bucket'),
+}, async (args) => apiRequest(config, 'POST', '/brand-kits', {
+    body: { name: args.name, data: args.data, logo_path: args.logo_path },
+}));
+tool('update_brand_kit', 'Update a brand kit. Requires write access.', {
+    id: z.string().uuid().describe('Brand kit UUID'),
+    name: z.string().optional(),
+    data: z.record(z.unknown()).optional(),
+    logo_path: z.string().nullable().optional(),
+}, async (args) => {
+    const { id, ...body } = args;
+    return apiRequest(config, 'PATCH', `/brand-kits/${id}`, { body });
+});
+tool('delete_brand_kit', 'Delete a brand kit. Requires write access.', { id: z.string().uuid().describe('Brand kit UUID') }, async (args) => apiRequest(config, 'DELETE', `/brand-kits/${args.id}`));
+// —— Assets ——
+tool('list_assets', 'List uploaded assets for the account.', {}, async () => apiRequest(config, 'GET', '/assets'));
+tool('upload_asset', 'Upload an asset from base64 or a public URL. Requires write access.', {
+    filename: z.string().optional().describe('Original filename (for extension)'),
+    mime: z.string().optional().describe('MIME type'),
+    base64: z.string().optional().describe('Base64 or data-URL payload'),
+    url: z.string().url().optional().describe('Public URL to fetch and store'),
+}, async (args) => apiRequest(config, 'POST', '/assets', { body: args }));
+tool('delete_asset', 'Delete an asset by id. Requires write access.', { id: z.string().uuid().describe('Asset UUID') }, async (args) => apiRequest(config, 'DELETE', `/assets/${args.id}`));
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/package.json

@@ -1,6 +1,50 @@
-{
-  "name": "@mailloom/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@mailloom/mcp",
+  "version": "0.1.0",
+  "description": "Official Mailloom MCP server — manage email templates, brand kits, and assets via the Mailloom API.",
+  "type": "module",
+  "bin": {
+    "mailloom-mcp": "bin/mailloom-mcp.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "mailloom",
+    "mcp",
+    "model-context-protocol",
+    "cursor",
+    "claude",
+    "email",
+    "templates"
+  ],
+  "license": "MIT"
+}