groundmail-mcp 0.0.0-stage → 0.5.5

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# groundmail-mcp
 
-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.
+MCP server for [Groundmail](https://groundmail.dev) — send email and manage domains, webhooks, suppressions, and templates from Cursor, Claude Code, and other MCP clients.
+
+**Install:** `npx -y groundmail-mcp` · **Docs:** https://docs.groundmail.dev/ai/mcp
+
+## Transports
+
+| Mode | Command / URL | Auth |
+|------|---------------|------|
+| **stdio** (default) | `npx -y groundmail-mcp` | `GROUNDMAIL_API_KEY=gm_…` |
+| **HTTP** (local) | `npx -y groundmail-mcp --http --port 3000` | `Authorization: Bearer gm_…` on each request |
+| **HTTP** (hosted) | `https://mcp.groundmail.dev/mcp` | **OAuth** (recommended) or `Authorization: Bearer gm_…` |
+
+Optional: `GROUNDMAIL_API_URL` (e.g. `http://localhost:3003/api` for local API).
+
+Local HTTP endpoint: `http://127.0.0.1:3000/mcp` · health: `GET /health`  
+Hosted health: `GET https://mcp.groundmail.dev/health`
+
+Hosted OAuth: add only `"url": "https://mcp.groundmail.dev/mcp"` — the client runs the browser consent flow. Bearer `gm_…` still works for advanced setups.
+
+---
+
+## Cursor (stdio)
+
+`.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "groundmail": {
+      "command": "npx",
+      "args": ["-y", "groundmail-mcp"],
+      "env": {
+        "GROUNDMAIL_API_KEY": "gm_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Cursor (local HTTP)
+
+```bash
+npx -y groundmail-mcp --http --port 3000
+```
+
+```json
+{
+  "mcpServers": {
+    "groundmail": {
+      "url": "http://127.0.0.1:3000/mcp",
+      "headers": {
+        "Authorization": "Bearer gm_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Cursor (hosted)
+
+```json
+{
+  "mcpServers": {
+    "groundmail": {
+      "url": "https://mcp.groundmail.dev/mcp",
+      "headers": {
+        "Authorization": "Bearer gm_your_key_here"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Claude Code
+
+```bash
+# stdio
+claude mcp add --transport stdio groundmail -- npx -y groundmail-mcp
+
+# HTTP (local — after starting --http server)
+claude mcp add --transport http groundmail http://127.0.0.1:3000/mcp
+
+# HTTP (hosted)
+claude mcp add --transport http groundmail https://mcp.groundmail.dev/mcp
+```
+
+Export `GROUNDMAIL_API_KEY` for stdio, or configure Bearer headers for HTTP.
+
+---
+
+## Tools
+
+See https://docs.groundmail.dev/ai/mcp — emails, domains, webhooks, suppressions, templates, deliverability, webhook test.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/index.js

@@ -0,0 +1,763 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+var DEFAULT_HTTP_PORT = 3e3;
+var DEFAULT_HTTP_HOST = "127.0.0.1";
+function parseCliArgs(argv) {
+  const args = argv.slice(2);
+  if (args.includes("--help") || args.includes("-h")) {
+    return { mode: "help" };
+  }
+  const http = args.includes("--http");
+  if (!http) {
+    return { mode: "stdio" };
+  }
+  let port = DEFAULT_HTTP_PORT;
+  let host = DEFAULT_HTTP_HOST;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--port" || arg === "-p") {
+      const raw = args[i + 1];
+      const parsed = Number(raw);
+      if (!raw || !Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+        throw new Error(`Invalid --port value: ${raw ?? "(missing)"}`);
+      }
+      port = parsed;
+      i++;
+      continue;
+    }
+    if (arg?.startsWith("--port=")) {
+      const raw = arg.slice("--port=".length);
+      const parsed = Number(raw);
+      if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+        throw new Error(`Invalid --port value: ${raw}`);
+      }
+      port = parsed;
+      continue;
+    }
+    if (arg === "--host") {
+      const raw = args[i + 1]?.trim();
+      if (!raw) throw new Error("Missing --host value");
+      host = raw;
+      i++;
+      continue;
+    }
+    if (arg?.startsWith("--host=")) {
+      const raw = arg.slice("--host=".length).trim();
+      if (!raw) throw new Error("Missing --host value");
+      host = raw;
+    }
+  }
+  return { mode: "http", port, host };
+}
+function printHelp() {
+  console.error(`Usage:
+  groundmail-mcp                  # stdio (default)
+  groundmail-mcp --http [--port 3000] [--host 127.0.0.1]
+
+Environment:
+  GROUNDMAIL_API_KEY   Required for stdio (Bearer gm_\u2026 for HTTP)
+  GROUNDMAIL_API_URL   Optional API base (default https://api.groundmail.dev)
+
+HTTP auth:
+  Authorization: Bearer gm_\u2026 (API key) or MCP OAuth access token
+`);
+}
+function isGroundmailApiKey(token) {
+  return /^gm_[a-f0-9]{48}$/i.test(token.trim());
+}
+function parseBearerToken(authorization) {
+  if (!authorization) return null;
+  const match = /^Bearer\s+(\S+)/i.exec(authorization.trim());
+  return match?.[1] || null;
+}
+
+// src/http.ts
+import { createServer } from "http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+
+// src/server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { Groundmail } from "groundmail";
+
+// src/tools.ts
+function textResult(value, isError = false) {
+  return {
+    content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value, null, 2) }],
+    ...isError ? { isError: true } : {}
+  };
+}
+function optString(args, key) {
+  if (args[key] == null) return void 0;
+  const value = String(args[key]).trim();
+  return value || void 0;
+}
+function optNumber(args, key) {
+  if (args[key] == null || args[key] === "") return void 0;
+  const n = Number(args[key]);
+  return Number.isFinite(n) ? n : void 0;
+}
+function optBoolean(args, key) {
+  if (args[key] == null) return void 0;
+  if (typeof args[key] === "boolean") return args[key];
+  const raw = String(args[key]).trim().toLowerCase();
+  if (raw === "true" || raw === "1") return true;
+  if (raw === "false" || raw === "0") return false;
+  return void 0;
+}
+function optStringArray(args, key) {
+  const value = args[key];
+  if (value == null) return void 0;
+  if (Array.isArray(value)) return value.map((v) => String(v));
+  return void 0;
+}
+var EMAIL_WEBHOOK_EVENTS = /* @__PURE__ */ new Set([
+  "email.received",
+  "email.sent",
+  "email.delivered",
+  "email.delivery_delayed",
+  "email.bounced",
+  "email.complained",
+  "email.opened",
+  "email.clicked",
+  "email.failed",
+  "email.suppressed",
+  "email.scheduled"
+]);
+async function callMcpTool(client, name, args) {
+  try {
+    switch (name) {
+      case "send_email": {
+        const from = optString(args, "from");
+        const to = optString(args, "to");
+        const subject = optString(args, "subject");
+        const templateId = optString(args, "template_id") || optString(args, "template_alias");
+        if (!from) return textResult("Missing required argument: from", true);
+        if (!to) return textResult("Missing required argument: to", true);
+        if (!templateId && !subject) {
+          return textResult("Provide subject, or template_id / template_alias", true);
+        }
+        const variables = args.variables && typeof args.variables === "object" && !Array.isArray(args.variables) ? args.variables : void 0;
+        const result = await client.emails.send({
+          from,
+          to,
+          ...subject ? { subject } : {},
+          html: optString(args, "html"),
+          text: optString(args, "text"),
+          reply_to: optString(args, "reply_to"),
+          ...templateId ? { template: { id: templateId, ...variables ? { variables } : {} } } : {}
+        });
+        return textResult(result);
+      }
+      case "list_emails": {
+        const result = await client.emails.list({
+          limit: optNumber(args, "limit"),
+          cursor: optString(args, "cursor")
+        });
+        return textResult(result);
+      }
+      case "get_email": {
+        const id = optString(args, "id");
+        if (!id) return textResult("Missing required argument: id", true);
+        return textResult(await client.emails.get(id));
+      }
+      case "apply_domain_dns": {
+        const domain = String(args.domain ?? "").trim();
+        if (!domain) {
+          return textResult("Missing required argument: domain", true);
+        }
+        const providerRaw = typeof args.provider === "string" ? args.provider.trim().toLowerCase() : "";
+        if (providerRaw !== "cloudflare" && providerRaw !== "godaddy" && providerRaw !== "vercel") {
+          return textResult(
+            'Missing or invalid provider. Use provider "cloudflare", "godaddy", or "vercel".',
+            true
+          );
+        }
+        const credentials = args.credentials && typeof args.credentials === "object" ? args.credentials : void 0;
+        const result = await client.domains.apply(domain, {
+          provider: providerRaw,
+          ...credentials ? { credentials } : {}
+        });
+        return textResult(result);
+      }
+      case "verify_domain": {
+        const domain = optString(args, "domain");
+        if (!domain) return textResult("Missing required argument: domain", true);
+        const result = await client.domains.verify(domain);
+        return textResult(result);
+      }
+      case "list_domains": {
+        const result = await client.domains.list({
+          limit: optNumber(args, "limit"),
+          cursor: optString(args, "cursor")
+        });
+        return textResult(result);
+      }
+      case "create_domain": {
+        const domainName = optString(args, "name");
+        if (!domainName) return textResult("Missing required argument: name", true);
+        const inbound = optBoolean(args, "inbound_enabled");
+        return textResult(
+          await client.domains.create({
+            name: domainName,
+            ...inbound !== void 0 ? { inbound_enabled: inbound } : {}
+          })
+        );
+      }
+      case "list_webhooks": {
+        return textResult(
+          await client.webhooks.list({
+            limit: optNumber(args, "limit"),
+            cursor: optString(args, "cursor")
+          })
+        );
+      }
+      case "create_webhook": {
+        const url = optString(args, "url");
+        if (!url) return textResult("Missing required argument: url", true);
+        const events = optStringArray(args, "events");
+        return textResult(
+          await client.webhooks.create({
+            url,
+            ...events ? { events } : {}
+          })
+        );
+      }
+      case "delete_webhook": {
+        const id = optString(args, "id");
+        if (!id) return textResult("Missing required argument: id", true);
+        return textResult(await client.webhooks.delete(id));
+      }
+      case "list_suppressions": {
+        return textResult(
+          await client.suppressions.list({
+            limit: optNumber(args, "limit"),
+            cursor: optString(args, "cursor"),
+            email: optString(args, "email")
+          })
+        );
+      }
+      case "add_suppression": {
+        const email = optString(args, "email");
+        if (!email) return textResult("Missing required argument: email", true);
+        return textResult(
+          await client.suppressions.create({
+            email,
+            reason: optString(args, "reason")
+          })
+        );
+      }
+      case "remove_suppression": {
+        const idOrEmail = optString(args, "id") ?? optString(args, "email");
+        if (!idOrEmail) {
+          return textResult("Missing required argument: id or email", true);
+        }
+        return textResult(await client.suppressions.remove(idOrEmail));
+      }
+      case "list_templates": {
+        const status = optString(args, "status");
+        return textResult(
+          await client.templates.list({
+            limit: optNumber(args, "limit"),
+            cursor: optString(args, "cursor"),
+            ...status === "draft" || status === "published" ? { status } : {}
+          })
+        );
+      }
+      case "get_template": {
+        const idOrAlias = optString(args, "id") ?? optString(args, "alias");
+        if (!idOrAlias) return textResult("Missing required argument: id or alias", true);
+        return textResult(await client.templates.get(idOrAlias));
+      }
+      case "create_template": {
+        const name2 = optString(args, "name");
+        const subjectArg = optString(args, "subject");
+        if (!name2) return textResult("Missing required argument: name", true);
+        if (!subjectArg) return textResult("Missing required argument: subject", true);
+        const format = optString(args, "format");
+        return textResult(
+          await client.templates.create({
+            name: name2,
+            subject: subjectArg,
+            ...format === "blocks" || format === "html" ? { format } : {},
+            html: optString(args, "html"),
+            text: optString(args, "text"),
+            alias: optString(args, "alias")
+          })
+        );
+      }
+      case "publish_template": {
+        const idOrAlias = optString(args, "id") ?? optString(args, "alias");
+        if (!idOrAlias) return textResult("Missing required argument: id or alias", true);
+        return textResult(await client.templates.publish(idOrAlias));
+      }
+      case "send_test_webhook_event": {
+        const event = optString(args, "event");
+        if (!event || !EMAIL_WEBHOOK_EVENTS.has(event)) {
+          return textResult(
+            `Missing or invalid event. Use one of: ${[...EMAIL_WEBHOOK_EVENTS].join(", ")}`,
+            true
+          );
+        }
+        return textResult(
+          await client.emails.testWebhook({
+            event,
+            email_id: optString(args, "email_id"),
+            deliver: optBoolean(args, "deliver")
+          })
+        );
+      }
+      case "get_deliverability": {
+        const window = args.window === "7d" ? "7d" : "30d";
+        const result = await client.emails.insights(window);
+        return textResult(result);
+      }
+      default:
+        return textResult(`Unknown tool: ${name}`, true);
+    }
+  } catch (error) {
+    const message = error && typeof error === "object" && "message" in error ? String(error.message) : "Request failed";
+    return textResult(message, true);
+  }
+}
+var paginationProps = {
+  limit: { type: "number", description: "Page size (1\u2013100)" },
+  cursor: { type: "string", description: "Opaque cursor for the next page" }
+};
+var MCP_TOOLS = [
+  {
+    name: "send_email",
+    description: "Send a transactional email via Groundmail. Provide subject + html/text, or a published template_id / template_alias with optional variables.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        from: { type: "string", description: "Sender address (must match a verified domain or sandbox sender)" },
+        to: { type: "string", description: "Recipient email address" },
+        subject: { type: "string", description: "Optional when using a published template" },
+        html: { type: "string" },
+        text: { type: "string" },
+        reply_to: { type: "string" },
+        template_id: { type: "string", description: "Published template UUID" },
+        template_alias: { type: "string", description: "Published template alias" },
+        variables: {
+          type: "object",
+          description: "Template variables when using template_id or template_alias",
+          additionalProperties: true
+        }
+      },
+      required: ["from", "to"]
+    }
+  },
+  {
+    name: "list_emails",
+    description: "List recent emails sent from this account.",
+    inputSchema: {
+      type: "object",
+      properties: { ...paginationProps }
+    }
+  },
+  {
+    name: "get_email",
+    description: "Get a single email by public id (msg_\u2026).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Email id (msg_\u2026)" }
+      },
+      required: ["id"]
+    }
+  },
+  {
+    name: "list_domains",
+    description: "List sending domains for this account.",
+    inputSchema: {
+      type: "object",
+      properties: { ...paginationProps }
+    }
+  },
+  {
+    name: "create_domain",
+    description: "Add a sending domain. DNS must still be applied and verified before production sends.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Domain name (example.com)" },
+        inbound_enabled: { type: "boolean", description: "Enable inbound receiving on this domain" }
+      },
+      required: ["name"]
+    }
+  },
+  {
+    name: "apply_domain_dns",
+    description: "Apply Groundmail DNS records for a domain. Cloudflare and GoDaddy can use credentials stored in the dashboard; GoDaddy also accepts one-time credentials on the request.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        domain: { type: "string" },
+        provider: { type: "string", enum: ["cloudflare", "godaddy", "vercel"] },
+        credentials: {
+          type: "object",
+          description: "Optional inline registrar credentials (GoDaddy api key/secret)"
+        }
+      },
+      required: ["domain", "provider"]
+    }
+  },
+  {
+    name: "verify_domain",
+    description: "Verify DNS for a sending domain after records are applied.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        domain: { type: "string" }
+      },
+      required: ["domain"]
+    }
+  },
+  {
+    name: "list_webhooks",
+    description: "List webhook endpoints for this account.",
+    inputSchema: {
+      type: "object",
+      properties: { ...paginationProps }
+    }
+  },
+  {
+    name: "create_webhook",
+    description: "Create a webhook endpoint. Returns the endpoint plus a signing secret (shown once).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        url: { type: "string", description: "HTTPS URL that receives events" },
+        events: {
+          type: "array",
+          items: { type: "string" },
+          description: "Optional event types (defaults apply when omitted)"
+        }
+      },
+      required: ["url"]
+    }
+  },
+  {
+    name: "delete_webhook",
+    description: "Delete a webhook endpoint by id.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Webhook id (wh_\u2026)" }
+      },
+      required: ["id"]
+    }
+  },
+  {
+    name: "list_suppressions",
+    description: "List suppressed recipient addresses.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ...paginationProps,
+        email: { type: "string", description: "Optional filter by email" }
+      }
+    }
+  },
+  {
+    name: "add_suppression",
+    description: "Add an address to the suppression list.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        email: { type: "string" },
+        reason: { type: "string" }
+      },
+      required: ["email"]
+    }
+  },
+  {
+    name: "remove_suppression",
+    description: "Remove a suppression by id or email address.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Suppression id" },
+        email: { type: "string", description: "Email address (alternative to id)" }
+      }
+    }
+  },
+  {
+    name: "list_templates",
+    description: "List email templates.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ...paginationProps,
+        status: { type: "string", enum: ["draft", "published"] }
+      }
+    }
+  },
+  {
+    name: "get_template",
+    description: "Get a template by id or alias.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Template id (tpl_\u2026)" },
+        alias: { type: "string", description: "Published alias (alternative to id)" }
+      }
+    }
+  },
+  {
+    name: "create_template",
+    description: "Create a draft email template (html or blocks format).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        subject: { type: "string" },
+        format: { type: "string", enum: ["html", "blocks"] },
+        html: { type: "string" },
+        text: { type: "string" },
+        alias: { type: "string" }
+      },
+      required: ["name", "subject"]
+    }
+  },
+  {
+    name: "publish_template",
+    description: "Publish a template, snapshotting an immutable version for sends.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string" },
+        alias: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "send_test_webhook_event",
+    description: "Simulate a webhook event (POST /emails/test) for CI or local webhook testing. Optionally deliver to subscribed endpoints.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        event: {
+          type: "string",
+          enum: [...EMAIL_WEBHOOK_EVENTS],
+          description: "Webhook event type to simulate"
+        },
+        email_id: { type: "string", description: "Optional existing email id (msg_\u2026)" },
+        deliver: {
+          type: "boolean",
+          description: "When true (default), enqueue delivery to account webhooks"
+        }
+      },
+      required: ["event"]
+    }
+  },
+  {
+    name: "get_deliverability",
+    description: "Fetch best-effort deliverability metrics for recent sends (7d or 30d window).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        window: { type: "string", enum: ["7d", "30d"] }
+      }
+    }
+  }
+];
+function resolveApiKey() {
+  const key = process.env.GROUNDMAIL_API_KEY?.trim();
+  if (!key) {
+    throw new Error("GROUNDMAIL_API_KEY is required");
+  }
+  if (!key.startsWith("gm_")) {
+    throw new Error("GROUNDMAIL_API_KEY must start with gm_");
+  }
+  return key;
+}
+
+// src/server.ts
+function createMcpServer(apiKey, baseUrl) {
+  const client = new Groundmail(apiKey, baseUrl ? { baseUrl } : {});
+  const server = new Server(
+    { name: "groundmail-mcp", version: "0.3.0" },
+    { capabilities: { tools: {} } }
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: MCP_TOOLS.map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: tool.inputSchema
+    }))
+  }));
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const result = await callMcpTool(client, request.params.name, request.params.arguments ?? {});
+    return result;
+  });
+  return server;
+}
+async function runStdioServer() {
+  const apiKey = resolveApiKey();
+  const baseUrl = process.env.GROUNDMAIL_API_URL?.trim();
+  const server = createMcpServer(apiKey, baseUrl || void 0);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+// src/oauth-metadata.ts
+var MCP_HTTP_PATH = "/mcp";
+function buildProtectedResourceMetadata(origin) {
+  const resource = `${origin.replace(/\/$/, "")}${MCP_HTTP_PATH}`;
+  const appOrigin = process.env.GROUNDMAIL_OAUTH_ISSUER?.trim() || process.env.GROUNDMAIL_APP_URL?.trim() || "https://app.groundmail.dev";
+  return {
+    resource,
+    authorization_servers: [appOrigin.replace(/\/$/, "")],
+    scopes_supported: ["full"],
+    bearer_methods_supported: ["header"]
+  };
+}
+function buildWwwAuthenticateChallenge(origin) {
+  const metadataUrl = `${origin.replace(/\/$/, "")}/.well-known/oauth-protected-resource`;
+  return `Bearer error="invalid_token", error_description="OAuth authentication required", resource_metadata="${metadataUrl}"`;
+}
+
+// src/oauth-resolve.ts
+function getOAuthResolveUrl() {
+  const appBase = (process.env.GROUNDMAIL_APP_URL?.trim() || process.env.GROUNDMAIL_OAUTH_ISSUER?.trim() || "https://app.groundmail.dev").replace(/\/$/, "");
+  return `${appBase}/api/mcp/oauth/resolve`;
+}
+async function resolveOAuthAccessToken(accessToken) {
+  const resolveSecret = process.env.GROUNDMAIL_MCP_RESOLVE_SECRET?.trim() || process.env.GROUNDMAIL_CREDENTIALS_ENCRYPTION_KEY?.trim() || (process.env.NODE_ENV === "production" ? "" : "groundmail-dev-mcp-resolve");
+  if (!resolveSecret) return null;
+  const response = await fetch(getOAuthResolveUrl(), {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${accessToken}`,
+      "content-type": "application/json",
+      "x-groundmail-mcp-resolve": resolveSecret
+    }
+  });
+  if (!response.ok) return null;
+  const data = await response.json().catch(() => null);
+  const apiKey = data?.apiKey?.trim();
+  return apiKey || null;
+}
+
+// src/http.ts
+function sendJson(res, status, body, headers = {}) {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "content-length": Buffer.byteLength(payload),
+    ...headers
+  });
+  res.end(payload);
+}
+function firstHeaderValue(value) {
+  if (!value) return void 0;
+  const raw = Array.isArray(value) ? value[0] : value;
+  const trimmed = raw?.split(",")[0]?.trim();
+  return trimmed || void 0;
+}
+function getRequestOrigin(req) {
+  const host = firstHeaderValue(req.headers["x-forwarded-host"]) || firstHeaderValue(req.headers.host) || "127.0.0.1";
+  const proto = firstHeaderValue(req.headers["x-forwarded-proto"]) || "http";
+  return `${proto}://${host}`;
+}
+async function resolveApiKeyFromAuthorization(authorization, baseUrl) {
+  const bearer = parseBearerToken(authorization);
+  if (!bearer) return null;
+  if (isGroundmailApiKey(bearer)) return bearer;
+  return resolveOAuthAccessToken(bearer);
+}
+async function handleHttpRequest(req, res, options = {}) {
+  const origin = getRequestOrigin(req);
+  const url = new URL(req.url || "/", origin);
+  if (req.method === "OPTIONS") {
+    res.writeHead(204, {
+      "access-control-allow-origin": "*",
+      "access-control-allow-methods": "GET, POST, DELETE, OPTIONS",
+      "access-control-allow-headers": "Authorization, Content-Type, Accept, Mcp-Session-Id, X-Groundmail-Mcp-Resolve"
+    });
+    res.end();
+    return;
+  }
+  if (url.pathname === "/health") {
+    sendJson(res, 200, { ok: true, service: "groundmail-mcp" });
+    return;
+  }
+  if (url.pathname === "/.well-known/oauth-protected-resource") {
+    sendJson(res, 200, buildProtectedResourceMetadata(origin), {
+      "cache-control": "public, max-age=300, s-maxage=3600"
+    });
+    return;
+  }
+  if (url.pathname !== "/mcp" && url.pathname !== "/") {
+    sendJson(res, 404, { error: "Not found. MCP endpoint is POST/GET /mcp" });
+    return;
+  }
+  const apiKey = await resolveApiKeyFromAuthorization(
+    typeof req.headers.authorization === "string" ? req.headers.authorization : void 0,
+    options.baseUrl
+  );
+  if (!apiKey) {
+    sendJson(
+      res,
+      401,
+      { error: "Missing or invalid Authorization. Use Bearer gm_\u2026 or complete MCP OAuth." },
+      { "www-authenticate": buildWwwAuthenticateChallenge(origin) }
+    );
+    return;
+  }
+  const server = createMcpServer(apiKey, options.baseUrl);
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: void 0
+  });
+  try {
+    await server.connect(transport);
+    await transport.handleRequest(req, res);
+  } finally {
+    await transport.close().catch(() => void 0);
+    await server.close().catch(() => void 0);
+  }
+}
+async function runHttpServer(options) {
+  const host = options.host ?? "127.0.0.1";
+  const port = options.port;
+  const baseUrl = process.env.GROUNDMAIL_API_URL?.trim() || void 0;
+  const httpServer = createServer((req, res) => {
+    void handleHttpRequest(req, res, { baseUrl }).catch((error) => {
+      if (!res.headersSent) {
+        sendJson(res, 500, {
+          error: error instanceof Error ? error.message : "Internal server error"
+        });
+      } else {
+        res.end();
+      }
+    });
+  });
+  await new Promise((resolve, reject) => {
+    httpServer.once("error", reject);
+    httpServer.listen(port, host, () => resolve());
+  });
+  console.error(`Groundmail MCP HTTP listening on http://${host}:${port}/mcp`);
+  console.error("Authenticate with Bearer gm_\u2026 or MCP OAuth access token");
+}
+
+// src/index.ts
+async function main() {
+  const options = parseCliArgs(process.argv);
+  if (options.mode === "help") {
+    printHelp();
+    process.exit(0);
+  }
+  if (options.mode === "http") {
+    await runHttpServer({ port: options.port, host: options.host });
+    return;
+  }
+  await runStdioServer();
+}
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "groundmail-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.5",
+  "description": "Groundmail MCP server \u2014 stdio or local HTTP (--http) for Cursor and Claude",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "groundmail-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "smithery.yaml"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Groundmail/groundmail-sdks.git"
+  },
+  "homepage": "https://docs.groundmail.dev/ai/mcp",
+  "keywords": [
+    "mcp",
+    "email",
+    "transactional",
+    "groundmail",
+    "cursor",
+    "claude"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "groundmail": "0.14.1"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.0",
+    "typescript": "^5",
+    "vitest": "^3.2.4"
+  }
+}

package/smithery.yaml

@@ -0,0 +1,29 @@
+# Smithery configuration for groundmail-mcp
+# https://smithery.ai — submit/list after publish: npx @smithery/cli publish (or dashboard)
+
+startCommand:
+  type: stdio
+  configSchema:
+    type: object
+    required: [apiKey]
+    properties:
+      apiKey:
+        type: string
+        title: Groundmail API Key
+        description: API key starting with gm_
+      apiUrl:
+        type: string
+        title: API Base URL
+        description: Optional override (default https://api.groundmail.dev)
+  commandFunction: |-
+    (config) => ({
+      command: 'npx',
+      args: ['-y', 'groundmail-mcp'],
+      env: {
+        GROUNDMAIL_API_KEY: config.apiKey,
+        ...(config.apiUrl ? { GROUNDMAIL_API_URL: config.apiUrl } : {}),
+      },
+    })
+
+exampleConfig:
+  apiKey: gm_your_key_here