@multimail/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,89 @@
+# @multimail/mcp-server
+
+MCP server for [MultiMail](https://multimail.dev). Give any AI agent email capabilities through the Model Context Protocol.
+
+## Quick start
+
+```bash
+npx @multimail/mcp-server
+```
+
+Requires `MULTIMAIL_API_KEY` environment variable. Get one at [multimail.dev](https://multimail.dev).
+
+## Setup
+
+Any MCP-compatible client uses the same config. Add MultiMail to your client's MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "multimail": {
+      "command": "npx",
+      "args": ["-y", "@multimail/mcp-server"],
+      "env": {
+        "MULTIMAIL_API_KEY": "mm_live_...",
+        "MULTIMAIL_MAILBOX_ID": "01KJ1NHN8J..."
+      }
+    }
+  }
+}
+```
+
+### Where to add this
+
+| Client | Config file |
+|--------|------------|
+| Claude Code | `~/.claude/.mcp.json` |
+| Claude Desktop | `claude_desktop_config.json` |
+| Cursor | `.cursor/mcp.json` in your project |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+| Copilot (VS Code) | `.vscode/mcp.json` in your project |
+| OpenCode | `mcp.json` in your project |
+| ChatGPT Desktop | Settings > MCP Servers |
+| Any MCP client | Consult your client's docs for config location |
+
+## Environment variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `MULTIMAIL_API_KEY` | Yes | Your MultiMail API key (`mm_live_...`) |
+| `MULTIMAIL_MAILBOX_ID` | No | Default mailbox ID. If not set, pass `mailbox_id` to each tool or call `list_mailboxes` first. |
+| `MULTIMAIL_API_URL` | No | API base URL. Defaults to `https://api.multimail.dev`. |
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_mailboxes` | List all mailboxes available to this API key |
+| `send_email` | Send an email with a markdown body |
+| `check_inbox` | List emails (filterable by unread/read/archived) |
+| `read_email` | Get the full content of a specific email |
+| `reply_email` | Reply to an email in its existing thread |
+| `search_identity` | Look up the public identity of any MultiMail address |
+
+## How it works
+
+- You write email bodies in **markdown**. MultiMail converts to formatted HTML for delivery.
+- Incoming email arrives as **clean markdown**. No HTML parsing or MIME decoding.
+- Threading is automatic. Reply to an email and headers are set correctly.
+- If your mailbox uses gated oversight, sends return `pending_approval` status. Do not retry.
+- Verify other agents before communicating using `search_identity`.
+
+## Development
+
+```bash
+npm install
+npm run dev   # Run with tsx (no build needed)
+npm run build # Compile TypeScript
+npm start     # Run compiled version
+```
+
+## Testing
+
+```bash
+echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | MULTIMAIL_API_KEY=mm_live_... node dist/index.js
+```
+
+## License
+
+MIT

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+// --- Config ---
+const API_KEY = process.env.MULTIMAIL_API_KEY;
+const DEFAULT_MAILBOX_ID = process.env.MULTIMAIL_MAILBOX_ID;
+const BASE_URL = (process.env.MULTIMAIL_API_URL || "https://api.multimail.dev").replace(/\/$/, "");
+if (!API_KEY) {
+    console.error("MULTIMAIL_API_KEY environment variable is required.");
+    process.exit(1);
+}
+// --- API Client ---
+async function apiCall(method, path, body) {
+    const url = `${BASE_URL}${path}`;
+    const headers = {
+        "Authorization": `Bearer ${API_KEY}`,
+        "Content-Type": "application/json",
+    };
+    const res = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    const data = await res.json();
+    if (!res.ok) {
+        if (res.status === 401) {
+            throw new Error("Invalid API key. Check MULTIMAIL_API_KEY environment variable.");
+        }
+        if (res.status === 403) {
+            throw new Error(`API key lacks required scope for this operation. ${data.error || ""}`);
+        }
+        if (res.status === 429) {
+            const retryAfter = res.headers.get("retry-after") || "unknown";
+            throw new Error(`Rate limit exceeded. Retry after ${retryAfter} seconds.`);
+        }
+        throw new Error(`API error ${res.status}: ${JSON.stringify(data)}`);
+    }
+    return data;
+}
+async function publicFetch(path) {
+    const url = `${BASE_URL}${path}`;
+    const res = await fetch(url, { headers: { "Accept": "application/json" } });
+    const data = await res.json();
+    if (!res.ok) {
+        throw new Error(`API error ${res.status}: ${JSON.stringify(data)}`);
+    }
+    return data;
+}
+function getMailboxId(argsMailboxId) {
+    const id = argsMailboxId || DEFAULT_MAILBOX_ID;
+    if (!id) {
+        throw new Error("No mailbox_id provided and MULTIMAIL_MAILBOX_ID is not set. " +
+            "Either pass mailbox_id or set the MULTIMAIL_MAILBOX_ID environment variable. " +
+            "Use list_mailboxes to discover available mailboxes.");
+    }
+    return id;
+}
+// --- Server ---
+const server = new McpServer({
+    name: "multimail",
+    version: "0.1.0",
+});
+// Tool 1: list_mailboxes
+server.tool("list_mailboxes", "List all mailboxes available to this API key. Returns each mailbox's ID, email address, oversight mode, and display name. Use this to discover your mailbox ID if MULTIMAIL_MAILBOX_ID is not set.", {}, async () => {
+    const data = await apiCall("GET", "/v1/mailboxes");
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// Tool 2: send_email
+server.tool("send_email", "Send an email from your MultiMail address. The body is written in markdown and automatically converted to formatted HTML for delivery. If the mailbox uses gated oversight, the response status will be 'pending_approval' — this means the email is queued for human review. Do not retry or resend when you see pending_approval.", {
+    to: z.array(z.string()).describe("Recipient email addresses"),
+    subject: z.string().describe("Email subject line"),
+    markdown: z.string().describe("Email body in markdown format"),
+    cc: z.array(z.string()).optional().describe("CC email addresses"),
+    mailbox_id: z.string().optional().describe("Mailbox ID (uses MULTIMAIL_MAILBOX_ID env var if not provided)"),
+}, async ({ to, subject, markdown, cc, mailbox_id }) => {
+    const id = getMailboxId(mailbox_id);
+    const body = { to, subject, markdown };
+    if (cc?.length)
+        body.cc = cc;
+    const data = await apiCall("POST", `/v1/mailboxes/${encodeURIComponent(id)}/send`, body);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// Tool 3: check_inbox
+server.tool("check_inbox", "List emails in your inbox. Returns email summaries including id, from, to, subject, status, received_at, and has_attachments. Does NOT include the email body — call read_email with the email ID to get the full message content.", {
+    status: z.enum(["unread", "read", "archived"]).optional().describe("Filter by email status (default: all)"),
+    mailbox_id: z.string().optional().describe("Mailbox ID (uses MULTIMAIL_MAILBOX_ID env var if not provided)"),
+}, async ({ status, mailbox_id }) => {
+    const id = getMailboxId(mailbox_id);
+    const query = status ? `?status=${status}` : "";
+    const data = await apiCall("GET", `/v1/mailboxes/${encodeURIComponent(id)}/emails${query}`);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// Tool 4: read_email
+server.tool("read_email", "Get the full content of a specific email, including the markdown body and attachment metadata. Automatically marks unread emails as read. Use the email ID from check_inbox results.", {
+    email_id: z.string().describe("The email ID to read"),
+    mailbox_id: z.string().optional().describe("Mailbox ID (uses MULTIMAIL_MAILBOX_ID env var if not provided)"),
+}, async ({ email_id, mailbox_id }) => {
+    const id = getMailboxId(mailbox_id);
+    const data = await apiCall("GET", `/v1/mailboxes/${encodeURIComponent(id)}/emails/${encodeURIComponent(email_id)}`);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// Tool 5: reply_email
+server.tool("reply_email", "Reply to an email in its existing thread. Threading headers (In-Reply-To, References) are set automatically. The body is written in markdown. If the mailbox uses gated oversight, the response status will be 'pending_approval' — the reply is queued for human review. Do not retry or resend when you see pending_approval.", {
+    email_id: z.string().describe("The email ID to reply to"),
+    markdown: z.string().describe("Reply body in markdown format"),
+    cc: z.array(z.string()).optional().describe("CC email addresses"),
+    mailbox_id: z.string().optional().describe("Mailbox ID (uses MULTIMAIL_MAILBOX_ID env var if not provided)"),
+}, async ({ email_id, markdown, cc, mailbox_id }) => {
+    const id = getMailboxId(mailbox_id);
+    const body = { markdown };
+    if (cc?.length)
+        body.cc = cc;
+    const data = await apiCall("POST", `/v1/mailboxes/${encodeURIComponent(id)}/reply/${encodeURIComponent(email_id)}`, body);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// Tool 6: search_identity
+server.tool("search_identity", "Look up the public identity document for any MultiMail email address. Returns the agent's operator, oversight mode, capabilities, and whether the operator is verified. No authentication required. Use this to verify another agent's identity before sending sensitive information.", {
+    address: z.string().describe("The email address to look up (e.g. sandy@multimail.dev)"),
+}, async ({ address }) => {
+    const data = await publicFetch(`/.well-known/agent/${encodeURIComponent(address)}`);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// --- Start ---
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("Failed to start MCP server:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@multimail/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for MultiMail — email for AI agents",
+  "type": "module",
+  "bin": {
+    "multimail-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "keywords": ["mcp", "email", "ai-agents", "multimail", "model-context-protocol"],
+  "license": "MIT",
+  "author": {
+    "name": "MultiMail",
+    "email": "dev@multimail.dev",
+    "url": "https://multimail.dev"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/H179922/multimail.git",
+    "directory": "mcp"
+  },
+  "homepage": "https://multimail.dev",
+  "bugs": {
+    "email": "dev@multimail.dev"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.9.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+// --- Config ---
+
+const API_KEY = process.env.MULTIMAIL_API_KEY;
+const DEFAULT_MAILBOX_ID = process.env.MULTIMAIL_MAILBOX_ID;
+const BASE_URL = (process.env.MULTIMAIL_API_URL || "https://api.multimail.dev").replace(/\/$/, "");
+
+if (!API_KEY) {
+  console.error("MULTIMAIL_API_KEY environment variable is required.");
+  process.exit(1);
+}
+
+// --- API Client ---
+
+async function apiCall(method: string, path: string, body?: unknown): Promise<unknown> {
+  const url = `${BASE_URL}${path}`;
+  const headers: Record<string, string> = {
+    "Authorization": `Bearer ${API_KEY}`,
+    "Content-Type": "application/json",
+  };
+
+  const res = await fetch(url, {
+    method,
+    headers,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  const data = await res.json() as Record<string, unknown>;
+
+  if (!res.ok) {
+    if (res.status === 401) {
+      throw new Error("Invalid API key. Check MULTIMAIL_API_KEY environment variable.");
+    }
+    if (res.status === 403) {
+      throw new Error(`API key lacks required scope for this operation. ${(data as Record<string, unknown>).error || ""}`);
+    }
+    if (res.status === 429) {
+      const retryAfter = res.headers.get("retry-after") || "unknown";
+      throw new Error(`Rate limit exceeded. Retry after ${retryAfter} seconds.`);
+    }
+    throw new Error(`API error ${res.status}: ${JSON.stringify(data)}`);
+  }
+
+  return data;
+}
+
+async function publicFetch(path: string): Promise<unknown> {
+  const url = `${BASE_URL}${path}`;
+  const res = await fetch(url, { headers: { "Accept": "application/json" } });
+  const data = await res.json();
+  if (!res.ok) {
+    throw new Error(`API error ${res.status}: ${JSON.stringify(data)}`);
+  }
+  return data;
+}
+
+function getMailboxId(argsMailboxId?: string): string {
+  const id = argsMailboxId || DEFAULT_MAILBOX_ID;
+  if (!id) {
+    throw new Error(
+      "No mailbox_id provided and MULTIMAIL_MAILBOX_ID is not set. " +
+      "Either pass mailbox_id or set the MULTIMAIL_MAILBOX_ID environment variable. " +
+      "Use list_mailboxes to discover available mailboxes."
+    );
+  }
+  return id;
+}
+
+// --- Server ---
+
+const server = new McpServer({
+  name: "multimail",
+  version: "0.1.0",
+});
+
+// Tool 1: list_mailboxes
+server.tool(
+  "list_mailboxes",
+  "List all mailboxes available to this API key. Returns each mailbox's ID, email address, oversight mode, and display name. Use this to discover your mailbox ID if MULTIMAIL_MAILBOX_ID is not set.",
+  {},
+  async () => {
+    const data = await apiCall("GET", "/v1/mailboxes");
+    return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+// Tool 2: send_email
+server.tool(
+  "send_email",
+  "Send an email from your MultiMail address. The body is written in markdown and automatically converted to formatted HTML for delivery. If the mailbox uses gated oversight, the response status will be 'pending_approval' — this means the email is queued for human review. Do not retry or resend when you see pending_approval.",
+  {
+    to: z.array(z.string()).describe("Recipient email addresses"),
+    subject: z.string().describe("Email subject line"),
+    markdown: z.string().describe("Email body in markdown format"),
+    cc: z.array(z.string()).optional().describe("CC email addresses"),
+    mailbox_id: z.string().optional().describe("Mailbox ID (uses MULTIMAIL_MAILBOX_ID env var if not provided)"),
+  },
+  async ({ to, subject, markdown, cc, mailbox_id }) => {
+    const id = getMailboxId(mailbox_id);
+    const body: Record<string, unknown> = { to, subject, markdown };
+    if (cc?.length) body.cc = cc;
+    const data = await apiCall("POST", `/v1/mailboxes/${encodeURIComponent(id)}/send`, body);
+    return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+// Tool 3: check_inbox
+server.tool(
+  "check_inbox",
+  "List emails in your inbox. Returns email summaries including id, from, to, subject, status, received_at, and has_attachments. Does NOT include the email body — call read_email with the email ID to get the full message content.",
+  {
+    status: z.enum(["unread", "read", "archived"]).optional().describe("Filter by email status (default: all)"),
+    mailbox_id: z.string().optional().describe("Mailbox ID (uses MULTIMAIL_MAILBOX_ID env var if not provided)"),
+  },
+  async ({ status, mailbox_id }) => {
+    const id = getMailboxId(mailbox_id);
+    const query = status ? `?status=${status}` : "";
+    const data = await apiCall("GET", `/v1/mailboxes/${encodeURIComponent(id)}/emails${query}`);
+    return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+// Tool 4: read_email
+server.tool(
+  "read_email",
+  "Get the full content of a specific email, including the markdown body and attachment metadata. Automatically marks unread emails as read. Use the email ID from check_inbox results.",
+  {
+    email_id: z.string().describe("The email ID to read"),
+    mailbox_id: z.string().optional().describe("Mailbox ID (uses MULTIMAIL_MAILBOX_ID env var if not provided)"),
+  },
+  async ({ email_id, mailbox_id }) => {
+    const id = getMailboxId(mailbox_id);
+    const data = await apiCall("GET", `/v1/mailboxes/${encodeURIComponent(id)}/emails/${encodeURIComponent(email_id)}`);
+    return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+// Tool 5: reply_email
+server.tool(
+  "reply_email",
+  "Reply to an email in its existing thread. Threading headers (In-Reply-To, References) are set automatically. The body is written in markdown. If the mailbox uses gated oversight, the response status will be 'pending_approval' — the reply is queued for human review. Do not retry or resend when you see pending_approval.",
+  {
+    email_id: z.string().describe("The email ID to reply to"),
+    markdown: z.string().describe("Reply body in markdown format"),
+    cc: z.array(z.string()).optional().describe("CC email addresses"),
+    mailbox_id: z.string().optional().describe("Mailbox ID (uses MULTIMAIL_MAILBOX_ID env var if not provided)"),
+  },
+  async ({ email_id, markdown, cc, mailbox_id }) => {
+    const id = getMailboxId(mailbox_id);
+    const body: Record<string, unknown> = { markdown };
+    if (cc?.length) body.cc = cc;
+    const data = await apiCall("POST", `/v1/mailboxes/${encodeURIComponent(id)}/reply/${encodeURIComponent(email_id)}`, body);
+    return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+// Tool 6: search_identity
+server.tool(
+  "search_identity",
+  "Look up the public identity document for any MultiMail email address. Returns the agent's operator, oversight mode, capabilities, and whether the operator is verified. No authentication required. Use this to verify another agent's identity before sending sensitive information.",
+  {
+    address: z.string().describe("The email address to look up (e.g. sandy@multimail.dev)"),
+  },
+  async ({ address }) => {
+    const data = await publicFetch(`/.well-known/agent/${encodeURIComponent(address)}`);
+    return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+// --- Start ---
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error("Failed to start MCP server:", err);
+  process.exit(1);
+});

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "strict": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "declaration": true
+  },
+  "include": ["src/**/*.ts"]
+}