groundmail-mcp 0.5.5 → 0.5.7

package/README.md

@@ -1,6 +1,6 @@
 # groundmail-mcp
 
-MCP server for [Groundmail](https://groundmail.dev) — send email and manage domains, webhooks, suppressions, and templates from Cursor, Claude Code, and other MCP clients.
+MCP server for [Groundmail](https://groundmail.dev): send email and manage domains, webhooks, suppressions and templates from Claude, Claude Code, ChatGPT, Cursor and other MCP clients.
 
 **Install:** `npx -y groundmail-mcp` · **Docs:** https://docs.groundmail.dev/ai/mcp
 
@@ -78,17 +78,20 @@ npx -y groundmail-mcp --http --port 3000
 ## Claude Code
 
 ```bash
-# stdio
-claude mcp add --transport stdio groundmail -- npx -y groundmail-mcp
+# Hosted, OAuth: then run /mcp, pick groundmail, Authenticate
+claude mcp add --transport http groundmail https://mcp.groundmail.dev/mcp
 
-# HTTP (local — after starting --http server)
-claude mcp add --transport http groundmail http://127.0.0.1:3000/mcp
+# Hosted, API key
+claude mcp add --transport http groundmail https://mcp.groundmail.dev/mcp \
+  --header "Authorization: Bearer $GROUNDMAIL_API_KEY"
 
-# HTTP (hosted)
-claude mcp add --transport http groundmail https://mcp.groundmail.dev/mcp
+# Local stdio
+claude mcp add groundmail --env GROUNDMAIL_API_KEY=gm_your_key_here -- npx -y groundmail-mcp
 ```
 
-Export `GROUNDMAIL_API_KEY` for stdio, or configure Bearer headers for HTTP.
+## Claude and ChatGPT
+
+Add a custom connector with the URL `https://mcp.groundmail.dev/mcp` and sign in to Groundmail when prompted (ChatGPT needs developer mode). Step-by-step: https://docs.groundmail.dev/ai/mcp
 
 ---
 

package/dist/index.js

@@ -318,10 +318,36 @@ async function callMcpTool(client, name, args) {
         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);
+    return textResult(formatToolError(error), true);
   }
 }
+function formatToolError(error) {
+  if (!error || typeof error !== "object") return "Request failed";
+  const err = error;
+  const text = (value) => typeof value === "string" && value.trim() ? value.trim() : null;
+  const lines = [text(err.message) ?? "Request failed"];
+  const code = typeof err.code === "string" && /^[a-z_]+$/.test(err.code) ? err.code : null;
+  if (code) {
+    const status = typeof err.status === "number" ? ` (HTTP ${err.status})` : "";
+    lines.push(`code: ${code}${status}`);
+  }
+  const requiredScope = text(err.requiredScope);
+  if (requiredScope) lines.push(`required scope: ${requiredScope}`);
+  if (err.details !== void 0 && err.details !== null) {
+    lines.push(`details: ${JSON.stringify(err.details)}`);
+  }
+  const upgradeUrl = text(err.upgradeUrl);
+  if (upgradeUrl) {
+    lines.push(
+      `upgrade: ${/^https?:\/\//.test(upgradeUrl) ? upgradeUrl : `https://app.groundmail.dev${upgradeUrl.startsWith("/") ? "" : "/"}${upgradeUrl}`}`
+    );
+  }
+  const hint = text(err.hint);
+  if (hint) lines.push(`hint: ${hint}`);
+  const docsUrl = text(err.docsUrl) ?? (code ? `https://docs.groundmail.dev/errors#${code}` : null);
+  if (docsUrl) lines.push(`how to fix: ${docsUrl}`);
+  return lines.join("\n");
+}
 var paginationProps = {
   limit: { type: "number", description: "Page size (1\u2013100)" },
   cursor: { type: "string", description: "Opaque cursor for the next page" }
@@ -577,11 +603,19 @@ function resolveApiKey() {
 }
 
 // src/server.ts
+var MCP_SERVER_VERSION = "0.5.7";
+var MCP_SERVER_INSTRUCTIONS = [
+  "Groundmail sends transactional email from domains the user has verified.",
+  'To test before a domain is verified, call send_email with from "noreply@mail.groundmail.dev" and to set to the Groundmail account email; sandbox sends to any other address are rejected.',
+  "Sending to other recipients needs a verified domain (list_domains, create_domain, apply_domain_dns, verify_domain) and a payment method on the account (no charge on the Free plan).",
+  "Confirm with the user before sending email to anyone other than themselves.",
+  "Errors include a stable code and a link to https://docs.groundmail.dev/errors#<code> that says how to fix them."
+].join(" ");
 function createMcpServer(apiKey, baseUrl) {
   const client = new Groundmail(apiKey, baseUrl ? { baseUrl } : {});
   const server = new Server(
-    { name: "groundmail-mcp", version: "0.3.0" },
-    { capabilities: { tools: {} } }
+    { name: "groundmail-mcp", title: "Groundmail", version: MCP_SERVER_VERSION },
+    { capabilities: { tools: {} }, instructions: MCP_SERVER_INSTRUCTIONS }
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: MCP_TOOLS.map((tool) => ({
@@ -606,18 +640,43 @@ async function runStdioServer() {
 
 // src/oauth-metadata.ts
 var MCP_HTTP_PATH = "/mcp";
+var PROTECTED_RESOURCE_METADATA_PATH = "/.well-known/oauth-protected-resource";
+var PROTECTED_RESOURCE_METADATA_PATHS = /* @__PURE__ */ new Set([
+  PROTECTED_RESOURCE_METADATA_PATH,
+  `${PROTECTED_RESOURCE_METADATA_PATH}${MCP_HTTP_PATH}`
+]);
+var DOCS_URL = "https://docs.groundmail.dev/ai/mcp";
+var MCP_SCOPES_SUPPORTED = [
+  "full",
+  "emails:send",
+  "emails:read",
+  "domains:read",
+  "domains:write",
+  "webhooks:write",
+  "templates:write",
+  "suppressions:write",
+  "account:read"
+];
+function trimOrigin(origin) {
+  return origin.replace(/\/$/, "");
+}
 function buildProtectedResourceMetadata(origin) {
-  const resource = `${origin.replace(/\/$/, "")}${MCP_HTTP_PATH}`;
+  const resource = `${trimOrigin(origin)}${MCP_HTTP_PATH}`;
   const appOrigin = process.env.GROUNDMAIL_OAUTH_ISSUER?.trim() || process.env.GROUNDMAIL_APP_URL?.trim() || "https://app.groundmail.dev";
   return {
     resource,
+    resource_name: "Groundmail",
+    resource_documentation: DOCS_URL,
     authorization_servers: [appOrigin.replace(/\/$/, "")],
-    scopes_supported: ["full"],
+    scopes_supported: [...MCP_SCOPES_SUPPORTED],
     bearer_methods_supported: ["header"]
   };
 }
-function buildWwwAuthenticateChallenge(origin) {
-  const metadataUrl = `${origin.replace(/\/$/, "")}/.well-known/oauth-protected-resource`;
+function buildWwwAuthenticateChallenge(origin, options = {}) {
+  const metadataUrl = `${trimOrigin(origin)}${PROTECTED_RESOURCE_METADATA_PATH}`;
+  if (options.invalidToken === false) {
+    return `Bearer resource_metadata="${metadataUrl}"`;
+  }
   return `Bearer error="invalid_token", error_description="OAuth authentication required", resource_metadata="${metadataUrl}"`;
 }
 
@@ -644,15 +703,27 @@ async function resolveOAuthAccessToken(accessToken) {
 }
 
 // src/http.ts
+var CORS_HEADERS = {
+  "access-control-allow-origin": "*",
+  "access-control-expose-headers": "WWW-Authenticate, Mcp-Session-Id, Mcp-Protocol-Version"
+};
+var CORS_PREFLIGHT_HEADERS = {
+  ...CORS_HEADERS,
+  "access-control-allow-methods": "GET, POST, DELETE, OPTIONS",
+  "access-control-allow-headers": "Authorization, Content-Type, Accept, Mcp-Session-Id, Mcp-Protocol-Version, Last-Event-ID, X-Groundmail-Mcp-Resolve",
+  "access-control-max-age": "86400"
+};
 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),
+    ...CORS_HEADERS,
     ...headers
   });
   res.end(payload);
 }
+var UNAUTHORIZED_HINT = "Connect with OAuth: add https://mcp.groundmail.dev/mcp to your MCP client with no headers and sign in when it opens a browser. For scripts, send Authorization: Bearer gm_\u2026 with an API key from https://app.groundmail.dev/api-keys.";
 function firstHeaderValue(value) {
   if (!value) return void 0;
   const raw = Array.isArray(value) ? value[0] : value;
@@ -674,11 +745,7 @@ 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.writeHead(204, CORS_PREFLIGHT_HEADERS);
     res.end();
     return;
   }
@@ -686,7 +753,7 @@ async function handleHttpRequest(req, res, options = {}) {
     sendJson(res, 200, { ok: true, service: "groundmail-mcp" });
     return;
   }
-  if (url.pathname === "/.well-known/oauth-protected-resource") {
+  if (PROTECTED_RESOURCE_METADATA_PATHS.has(url.pathname)) {
     sendJson(res, 200, buildProtectedResourceMetadata(origin), {
       "cache-control": "public, max-age=300, s-maxage=3600"
     });
@@ -696,16 +763,25 @@ async function handleHttpRequest(req, res, options = {}) {
     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
-  );
+  const authorization = typeof req.headers.authorization === "string" ? req.headers.authorization : void 0;
+  const apiKey = await resolveApiKeyFromAuthorization(authorization, options.baseUrl);
   if (!apiKey) {
+    const message = "Missing or invalid Authorization. Use Bearer gm_\u2026 or complete MCP OAuth.";
     sendJson(
       res,
       401,
-      { error: "Missing or invalid Authorization. Use Bearer gm_\u2026 or complete MCP OAuth." },
-      { "www-authenticate": buildWwwAuthenticateChallenge(origin) }
+      {
+        error: message,
+        code: "unauthorized",
+        message,
+        hint: UNAUTHORIZED_HINT,
+        docs_url: "https://docs.groundmail.dev/errors#unauthorized"
+      },
+      {
+        "www-authenticate": buildWwwAuthenticateChallenge(origin, {
+          invalidToken: Boolean(parseBearerToken(authorization))
+        })
+      }
     );
     return;
   }
@@ -713,6 +789,9 @@ async function handleHttpRequest(req, res, options = {}) {
   const transport = new StreamableHTTPServerTransport({
     sessionIdGenerator: void 0
   });
+  for (const [name, value] of Object.entries(CORS_HEADERS)) {
+    res.setHeader(name, value);
+  }
   try {
     await server.connect(transport);
     await transport.handleRequest(req, res);

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "groundmail-mcp",
-  "version": "0.5.5",
-  "description": "Groundmail MCP server \u2014 stdio or local HTTP (--http) for Cursor and Claude",
+  "version": "0.5.7",
+  "mcpName": "io.github.Groundmail/groundmail",
+  "description": "Groundmail MCP server: send transactional email, manage domains, templates, webhooks and suppressions from Claude, Cursor, ChatGPT and other MCP clients",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -39,7 +40,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "groundmail": "0.14.1"
+    "groundmail": "0.14.2"
   },
   "devDependencies": {
     "tsup": "^8.5.0",

package/smithery.yaml

@@ -1,5 +1,6 @@
 # Smithery configuration for groundmail-mcp
-# https://smithery.ai — submit/list after publish: npx @smithery/cli publish (or dashboard)
+# Local stdio listing on https://smithery.ai. The hosted server (https://mcp.groundmail.dev/mcp)
+# is listed separately by URL; Smithery handles its OAuth.
 
 startCommand:
   type: stdio