@mailsac/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mailsac
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# Mailsac MCP server
+
+The official [Model Context Protocol](https://modelcontextprotocol.io) server for [Mailsac](https://mailsac.com).
+It gives AI coding agents (Claude Code, Cursor, VS Code, Claude Desktop and other MCP clients) disposable
+test inboxes, so an agent can check the email your application sends: sign-up confirmations,
+password resets, magic links and one-time codes.
+
+A typical conversation:
+
+> Sign up for a new account on http://localhost:3000 and confirm it by email.
+
+The agent creates a unique address with Mailsac, fills in your sign-up form, waits for the confirmation
+email, follows the link, and tells you what it found. The same tools help it write and debug end-to-end
+tests for those flows.
+
+## Tools
+
+| Tool | What it does | Mailsac operations |
+|---|---|---|
+| `create_test_address` | A new unique address, e.g. `signup-mf3k2a1b-9c41d2@mailsac.com`. Nothing to create first. | none |
+| `wait_for_email` | Waits until a matching email arrives (optionally by subject, sender or time), then returns the subject, text, links, the most likely confirm/reset/login link (`actionLink`) and candidate one-time codes. | 1 per check, plus 1 to read |
+| `list_emails` | Emails stored at an address, newest first. | 1 |
+| `read_email` | One email as text (with links and codes), HTML, raw MIME or headers. | 1 |
+| `delete_emails` | Delete one email, or all emails at an address. | 1 per call or message |
+| `list_domains` | Your account's private domains, to use with `create_test_address`. | 1 |
+
+## Set up
+
+You need a Mailsac API key. The free plan works: [create an account](https://mailsac.com/register), then
+[create a key](https://mailsac.com/api-keys).
+
+**Claude Code**
+
+```bash
+claude mcp add mailsac -e MAILSAC_API_KEY=your-key -- npx -y @mailsac/mcp
+```
+
+**Cursor** (`.cursor/mcp.json`), **Claude Desktop** (`claude_desktop_config.json`) and other clients that use the
+same format:
+
+```json
+{
+  "mcpServers": {
+    "mailsac": {
+      "command": "npx",
+      "args": ["-y", "@mailsac/mcp"],
+      "env": { "MAILSAC_API_KEY": "your-key" }
+    }
+  }
+}
+```
+
+**VS Code** (`.vscode/mcp.json`):
+
+```json
+{
+  "servers": {
+    "mailsac": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@mailsac/mcp"],
+      "env": { "MAILSAC_API_KEY": "your-key" }
+    }
+  }
+}
+```
+
+### Settings
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `MAILSAC_API_KEY` | (required) | Your Mailsac API key |
+| `MAILSAC_DOMAIN` | `mailsac.com` | Domain for new test addresses. Set it to your private domain. |
+| `MAILSAC_API_URL` | `https://mailsac.com/api` | API base URL |
+
+## Public inboxes and private domains
+
+Addresses at `@mailsac.com` are public: anyone who guesses an address can read its mail. They are ideal for
+made-up test data and need no setup. For anything real, such as a staging environment that sends real
+customer names, use a private domain: your own subdomain (for example `test.example.com`) or a zero-setup
+`yourteam.msdc.co` subdomain from the [domains page](https://mailsac.com/domains). Set `MAILSAC_DOMAIN` and every
+new address uses it.
+
+## Operations and limits
+
+Each API call uses one [Mailsac operation](https://mailsac.com/pricing). `wait_for_email` checks every 3 seconds
+by default, so a message that arrives within a few seconds costs about 2 to 5 operations. The free plan
+includes 1,500 operations a month; paid plans start at 25,000.
+
+## How Mailsac knows this is the MCP server
+
+Requests from this server carry `Mailsac-Client: mcp` and a `mailsac-mcp/<version>` user agent. Mailsac
+counts these in aggregate to see how many people use Mailsac through AI agents. Email content is never part of that
+count.
+
+## Develop
+
+```bash
+npm install
+npm test          # builds, then runs the tests with a fake Mailsac API
+MAILSAC_API_KEY=your-key node dist/index.js   # runs the server over stdio
+```
+
+## License
+
+MIT

package/dist/extract.js

@@ -0,0 +1,37 @@
+// Pull the things a test usually needs out of an email: its links, the one that most likely
+// confirms or resets something, and one-time codes.
+const LINK_PATTERN = /https?:\/\/[^\s"'<>)\]]+/g;
+const ACTION_WORDS = /(verif|confirm|activat|reset|magic|login|log-in|sign-?in|sign-?up|invite|token|auth|validate|unsubscribe)/i;
+const CODE_CONTEXT = /(code|otp|one[- ]time|passcode|pin|verification|security|2fa|mfa|token)/i;
+export function extractLinks(text, known = []) {
+    const found = [...known, ...(text.match(LINK_PATTERN) || [])]
+        .map((link) => link.replace(/[.,;:!?]+$/, ''));
+    return [...new Set(found)];
+}
+/** The link most likely to be the one a signup or reset test should follow, if any. */
+export function pickActionLink(links) {
+    const scored = links
+        .filter((link) => !/unsubscribe|preferences|privacy|terms/i.test(link))
+        .map((link) => ({ link, score: ACTION_WORDS.test(link) ? 2 : 0 }))
+        .filter((item) => item.score > 0);
+    return scored.length ? scored[0].link : null;
+}
+/**
+ * Candidate one-time codes: standalone 4–8 digit numbers, plus short uppercase letter/digit codes
+ * near words like "code" or "OTP". Codes on a line that mentions a code come first.
+ */
+export function extractCodes(text) {
+    const withContext = [];
+    const without = [];
+    for (const line of text.split(/\r?\n/)) {
+        const hasContext = CODE_CONTEXT.test(line);
+        const digits = line.match(/(?<![\d.,/:#$-])\d{4,8}(?!\d|[.,/:-]\d)/g) || [];
+        const mixed = hasContext ? line.match(/\b(?=[A-Z0-9-]*\d)(?=[A-Z0-9-]*[A-Z])[A-Z0-9]{3,4}-?[A-Z0-9]{3,4}\b/g) || [] : [];
+        for (const code of [...digits, ...mixed]) {
+            if (/^(19|20)\d{2}$/.test(code) && !hasContext)
+                continue; // likely a year
+            (hasContext ? withContext : without).push(code);
+        }
+    }
+    return [...new Set([...withContext, ...without])].slice(0, 10);
+}

package/dist/index.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { Mailsac, VERSION } from './mailsac.js';
+import { createServer } from './server.js';
+const apiKey = process.env.MAILSAC_API_KEY;
+if (process.argv.includes('--version')) {
+    console.log(VERSION);
+    process.exit(0);
+}
+if (!apiKey) {
+    console.error('Set MAILSAC_API_KEY to a Mailsac API key (free at https://mailsac.com/register, then https://mailsac.com/api-keys).');
+    process.exit(1);
+}
+const server = createServer({
+    client: new Mailsac(apiKey, process.env.MAILSAC_API_URL || 'https://mailsac.com/api'),
+    defaultDomain: (process.env.MAILSAC_DOMAIN || 'mailsac.com').toLowerCase(),
+});
+await server.connect(new StdioServerTransport());

package/dist/mailsac.js

@@ -0,0 +1,91 @@
+// A small Mailsac REST client. Every request identifies itself as the official MCP server
+// (Mailsac-Client: mcp), which Mailsac counts in aggregate, never alongside message content.
+import { randomBytes } from 'node:crypto';
+export const VERSION = '0.1.0';
+export class MailsacError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+export class Mailsac {
+    apiKey;
+    fetchImpl;
+    baseUrl;
+    constructor(apiKey, baseUrl = 'https://mailsac.com/api', fetchImpl = fetch) {
+        this.apiKey = apiKey;
+        this.fetchImpl = fetchImpl;
+        this.baseUrl = baseUrl.replace(/\/+$/, '');
+    }
+    async request(path, init = {}) {
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            ...init,
+            headers: {
+                'Mailsac-Key': this.apiKey,
+                'Mailsac-Client': 'mcp',
+                'User-Agent': `mailsac-mcp/${VERSION} (+https://github.com/mailsac/mailsac-mcp)`,
+                Accept: 'application/json',
+                ...(init.headers || {}),
+            },
+        });
+        if (!res.ok) {
+            let detail = '';
+            try {
+                const body = await res.json();
+                detail = body?.message || '';
+            }
+            catch {
+                /* not JSON */
+            }
+            throw new MailsacError(explain(res.status, detail), res.status);
+        }
+        return res;
+    }
+    async listMessages(address) {
+        const res = await this.request(`/addresses/${encodeURIComponent(address)}/messages`);
+        return (await res.json());
+    }
+    async readText(address, messageId, format = 'text') {
+        const route = { text: 'text', html: 'body', raw: 'raw' }[format];
+        const res = await this.request(`/${route}/${encodeURIComponent(address)}/${encodeURIComponent(messageId)}`, {
+            headers: { Accept: 'text/plain, text/html, */*' },
+        });
+        return res.text();
+    }
+    async readHeaders(address, messageId) {
+        const res = await this.request(`/addresses/${encodeURIComponent(address)}/messages/${encodeURIComponent(messageId)}/headers`);
+        return res.json();
+    }
+    async deleteMessage(address, messageId) {
+        await this.request(`/addresses/${encodeURIComponent(address)}/messages/${encodeURIComponent(messageId)}`, {
+            method: 'DELETE',
+        });
+    }
+    async deleteAllMessages(address) {
+        await this.request(`/addresses/${encodeURIComponent(address)}/messages`, { method: 'DELETE' });
+    }
+    async listDomains() {
+        const res = await this.request('/domains');
+        return (await res.json());
+    }
+}
+function explain(status, detail) {
+    const suffix = detail ? ` Mailsac said: ${detail}` : '';
+    if ((status === 401 || status === 403) && detail)
+        return `Not allowed (HTTP ${status}): ${detail}`;
+    if (status === 401 || status === 403) {
+        return `Mailsac rejected the API key (HTTP ${status}). Check MAILSAC_API_KEY; create a key at https://mailsac.com/api-keys.`;
+    }
+    if (status === 404)
+        return `Not found (HTTP 404). The address or message may not exist, or the message was already deleted.${suffix}`;
+    if (status === 429) {
+        return `Mailsac is limiting requests (HTTP 429): the account may have used its monthly operations, or is sending requests too fast. See https://mailsac.com/pricing.${suffix}`;
+    }
+    return `Mailsac API error (HTTP ${status}).${suffix}`;
+}
+/** A unique, lower-case address such as signup-mf3k2a1b-9c41d2@mailsac.com. */
+export function uniqueAddress(domain, prefix = 'test') {
+    const clean = prefix.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^[-.]+|[-.]+$/g, '').slice(0, 30) || 'test';
+    return `${clean}-${Date.now().toString(36)}-${randomBytes(3).toString('hex')}@${domain.toLowerCase()}`;
+}

package/dist/server.js

@@ -0,0 +1,220 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { extractCodes, extractLinks, pickActionLink } from './extract.js';
+import { MailsacError, uniqueAddress, VERSION } from './mailsac.js';
+const MAX_TEXT = 12_000;
+const PUBLIC_DOMAIN = 'mailsac.com';
+const text = (value) => ({
+    content: [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }],
+});
+const failure = (err) => ({
+    isError: true,
+    content: [{ type: 'text', text: err instanceof MailsacError ? err.message : `Error: ${err?.message || err}` }],
+});
+const truncate = (value) => value.length > MAX_TEXT ? `${value.slice(0, MAX_TEXT)}\n…[truncated ${value.length - MAX_TEXT} characters]` : value;
+function summarize(message) {
+    return {
+        messageId: message._id,
+        subject: message.subject,
+        from: message.from?.[0]?.address || null,
+        received: message.received,
+        attachments: message.attachments?.length || 0,
+    };
+}
+function matches(message, subjectContains, fromContains, receivedAfter) {
+    if (subjectContains && !(message.subject || '').toLowerCase().includes(subjectContains.toLowerCase()))
+        return false;
+    if (fromContains && !(message.from || []).some((f) => f.address?.toLowerCase().includes(fromContains.toLowerCase()))) {
+        return false;
+    }
+    if (receivedAfter && new Date(message.received).getTime() < receivedAfter)
+        return false;
+    return true;
+}
+async function withContent(client, message) {
+    const body = await client.readText(message.inbox, message._id, 'text');
+    const links = extractLinks(body, message.links || []);
+    return {
+        ...summarize(message),
+        address: message.inbox,
+        actionLink: pickActionLink(links),
+        codes: extractCodes(body),
+        links,
+        text: truncate(body),
+    };
+}
+export function createServer({ client, defaultDomain, sleep, now }) {
+    const wait = sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const clock = now || Date.now;
+    const server = new McpServer({ name: 'mailsac', version: VERSION }, {
+        instructions: 'Mailsac test inboxes for checking the email an application sends. Typical flow: create_test_address, ' +
+            'use the address in the app (sign up, reset a password, request a code), wait_for_email, then follow ' +
+            'actionLink or enter one of codes, and delete_emails when done. Addresses on mailsac.com are public: ' +
+            'anyone who guesses the address can read it, so only use made-up data there, or use a private domain ' +
+            '(see list_domains). Every API call, including each poll while waiting, uses Mailsac operations.',
+    });
+    server.registerTool('create_test_address', {
+        title: 'Create a test email address',
+        description: 'Return a new, unique address that can receive email immediately, with nothing to set up. ' +
+            'Use one address per test so tests never read each other\'s mail. Makes no API call.',
+        inputSchema: {
+            prefix: z.string().max(30).optional().describe('Readable start of the address, e.g. "signup"'),
+            domain: z
+                .string()
+                .optional()
+                .describe(`Domain to use. Defaults to ${defaultDomain}. Use a private domain for real or sensitive data.`),
+        },
+    }, async ({ prefix, domain }) => {
+        const chosen = (domain || defaultDomain).toLowerCase();
+        const address = uniqueAddress(chosen, prefix);
+        return text({
+            address,
+            public: chosen === PUBLIC_DOMAIN,
+            ...(chosen === PUBLIC_DOMAIN
+                ? {
+                    webInbox: `https://mailsac.com/inbox/${address}`,
+                    note: 'Public inbox: anyone who knows the address can read it. Use made-up data only.',
+                }
+                : {}),
+        });
+    });
+    server.registerTool('wait_for_email', {
+        title: 'Wait for an email',
+        description: 'Poll an address until a matching email arrives, then return its subject, sender, text, links, the ' +
+            'most likely confirm/reset/login link (actionLink) and candidate one-time codes. Each poll uses one ' +
+            'Mailsac operation.',
+        inputSchema: {
+            address: z.string().email().describe('Address to watch'),
+            subjectContains: z.string().optional().describe('Only match emails whose subject contains this text'),
+            fromContains: z.string().optional().describe('Only match emails whose sender contains this text'),
+            receivedAfter: z
+                .string()
+                .optional()
+                .describe('ISO timestamp; ignore emails received before it (useful when an address is reused)'),
+            timeoutSeconds: z.number().int().min(5).max(300).default(60).describe('Give up after this long'),
+            pollIntervalSeconds: z.number().int().min(2).max(30).default(3),
+        },
+    }, async ({ address, subjectContains, fromContains, receivedAfter, timeoutSeconds, pollIntervalSeconds }) => {
+        try {
+            const after = receivedAfter ? Date.parse(receivedAfter) : undefined;
+            if (receivedAfter && Number.isNaN(after))
+                throw new Error('receivedAfter must be an ISO date-time');
+            const deadline = clock() + timeoutSeconds * 1000;
+            let polls = 0;
+            for (;;) {
+                polls++;
+                const messages = await client.listMessages(address);
+                const found = messages
+                    .filter((m) => matches(m, subjectContains, fromContains, after))
+                    .sort((a, b) => Date.parse(b.received) - Date.parse(a.received))[0];
+                if (found)
+                    return text({ ...(await withContent(client, found)), polls });
+                if (clock() + pollIntervalSeconds * 1000 > deadline)
+                    break;
+                await wait(pollIntervalSeconds * 1000);
+            }
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: `No matching email reached ${address} within ${timeoutSeconds} seconds (${polls} checks). ` +
+                            'Check that the app sent to exactly this address, that its mail provider is configured, ' +
+                            'and try a longer timeout for real delivery.',
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return failure(err);
+        }
+    });
+    server.registerTool('list_emails', {
+        title: 'List emails at an address',
+        description: 'List the emails currently stored for an address, newest first (no bodies). One operation.',
+        inputSchema: { address: z.string().email() },
+    }, async ({ address }) => {
+        try {
+            const messages = await client.listMessages(address);
+            return text(messages
+                .sort((a, b) => Date.parse(b.received) - Date.parse(a.received))
+                .map(summarize));
+        }
+        catch (err) {
+            return failure(err);
+        }
+    });
+    server.registerTool('read_email', {
+        title: 'Read an email',
+        description: 'Read one email. format "text" (default) also returns links, actionLink and codes; "html" returns the ' +
+            'HTML body; "raw" the full MIME source; "headers" the parsed headers.',
+        inputSchema: {
+            address: z.string().email(),
+            messageId: z.string().min(1),
+            format: z.enum(['text', 'html', 'raw', 'headers']).default('text'),
+        },
+    }, async ({ address, messageId, format }) => {
+        try {
+            if (format === 'headers')
+                return text(await client.readHeaders(address, messageId));
+            const body = await client.readText(address, messageId, format);
+            if (format !== 'text')
+                return text(truncate(body));
+            const links = extractLinks(body);
+            return text({ messageId, actionLink: pickActionLink(links), codes: extractCodes(body), links, text: truncate(body) });
+        }
+        catch (err) {
+            return failure(err);
+        }
+    });
+    server.registerTool('delete_emails', {
+        title: 'Delete emails',
+        description: 'Delete one email (messageId) or every email at an address (omit messageId). Clean up after a test.',
+        inputSchema: { address: z.string().email(), messageId: z.string().optional() },
+        annotations: { destructiveHint: true },
+    }, async ({ address, messageId }) => {
+        try {
+            if (messageId) {
+                await client.deleteMessage(address, messageId);
+                return text({ deleted: 1, address });
+            }
+            try {
+                await client.deleteAllMessages(address);
+                return text({ deleted: 'all', address });
+            }
+            catch (err) {
+                // Deleting a whole inbox needs ownership (e.g. a public address); delete message by message instead.
+                if (!(err instanceof MailsacError) || (err.status !== 401 && err.status !== 403))
+                    throw err;
+                const messages = await client.listMessages(address);
+                for (const message of messages)
+                    await client.deleteMessage(address, message._id);
+                return text({ deleted: messages.length, address });
+            }
+        }
+        catch (err) {
+            return failure(err);
+        }
+    });
+    server.registerTool('list_domains', {
+        title: 'List private domains',
+        description: 'List the private domains on this Mailsac account. Mail to a private domain is visible only to the ' +
+            'account; pass one as `domain` to create_test_address.',
+        inputSchema: {},
+    }, async () => {
+        try {
+            const domains = await client.listDomains();
+            return text({
+                defaultDomain,
+                privateDomains: domains.map((d) => d._id || d.domain),
+                ...(domains.length
+                    ? {}
+                    : { note: 'No private domains. Add one, or a free yourteam.msdc.co subdomain, at https://mailsac.com/domains' }),
+            });
+        }
+        catch (err) {
+            return failure(err);
+        }
+    });
+    return server;
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@mailsac/mcp",
+  "version": "0.1.0",
+  "description": "Official Mailsac MCP server: give AI coding agents disposable test inboxes to check signup, password-reset and one-time-code emails.",
+  "license": "MIT",
+  "author": "Mailsac <support@team.mailsac.com>",
+  "homepage": "https://github.com/mailsac/mailsac-mcp#readme",
+  "repository": { "type": "git", "url": "git+https://github.com/mailsac/mailsac-mcp.git" },
+  "bugs": { "url": "https://github.com/mailsac/mailsac-mcp/issues" },
+  "keywords": ["mcp", "model-context-protocol", "mailsac", "email-testing", "test-email", "disposable-email", "claude", "cursor", "ai-agents", "qa"],
+  "type": "module",
+  "bin": { "mailsac-mcp": "dist/index.js" },
+  "main": "dist/index.js",
+  "files": ["dist", "README.md", "LICENSE"],
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/index.js",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepublishOnly": "npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.31.0",
+    "zod": "3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "22.18.6",
+    "typescript": "5.9.3"
+  }
+}