groundmail-mcp 0.16.1 → 0.17.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/dist/index.js +97 -6
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -55,7 +55,7 @@ When you connect, you choose the access: **Full**, **Send only** or **Read only*
|
|
|
55
55
|
>
|
|
56
56
|
> "How is my deliverability over the last 7 days?"
|
|
57
57
|
|
|
58
|
-
Tools cover emails (send, list, look up), domains (add, apply DNS through Cloudflare, Vercel, GoDaddy, Netlify, DigitalOcean or DNSimple, verify), templates, webhooks, suppressions, address validation, deliverability, DMARC monitoring, email testing (a test address per run, then wait for the email and read its code and links), imports from other providers and tenants (one per customer you send for: create, update, pause, resume, stats; `tenant` on sends, domains and suppressions). Each tool carries read-only and destructive annotations and an output schema. Full list: [docs.groundmail.dev/ai/mcp](https://docs.groundmail.dev/ai/mcp).
|
|
58
|
+
Tools cover emails (send, list, look up), received emails (with replies linked to the email you sent), domains (add, apply DNS through Cloudflare, Vercel, GoDaddy, Netlify, DigitalOcean or DNSimple, verify), templates, webhooks, suppressions, address validation, deliverability, DMARC monitoring, email testing (a test address per run, then wait for the email and read its code and links), imports from other providers and tenants (one per customer you send for: create, update, pause, resume, stats; `tenant` on sends, domains and suppressions). Each tool carries read-only and destructive annotations and an output schema. Full list: [docs.groundmail.dev/ai/mcp](https://docs.groundmail.dev/ai/mcp).
|
|
59
59
|
|
|
60
60
|
## Transports
|
|
61
61
|
|
package/dist/index.js
CHANGED
|
@@ -77,6 +77,7 @@ import { createServer } from "http";
|
|
|
77
77
|
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
|
|
78
78
|
|
|
79
79
|
// src/server.ts
|
|
80
|
+
import { AsyncLocalStorage } from "async_hooks";
|
|
80
81
|
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
|
|
81
82
|
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
82
83
|
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
|
|
@@ -611,6 +612,43 @@ var testEmailOutput = object(
|
|
|
611
612
|
},
|
|
612
613
|
["email"]
|
|
613
614
|
);
|
|
615
|
+
var inReplyToEmailItem = {
|
|
616
|
+
...object(
|
|
617
|
+
{
|
|
618
|
+
id: string("The sent email id (msg_\u2026)"),
|
|
619
|
+
subject: string("Its subject line"),
|
|
620
|
+
from: string("Its sender"),
|
|
621
|
+
to: stringArray("Its recipients"),
|
|
622
|
+
sent_at: string("When it was sent (ISO 8601)"),
|
|
623
|
+
tags: arrayOf(
|
|
624
|
+
object({ name: string("Tag name"), value: string("Tag value") }, ["name", "value"]),
|
|
625
|
+
"Its tags as sent"
|
|
626
|
+
),
|
|
627
|
+
tenant: nullableString("External id of the tenant it was sent as; null when it was not sent as a tenant")
|
|
628
|
+
},
|
|
629
|
+
["id"]
|
|
630
|
+
),
|
|
631
|
+
type: ["object", "null"],
|
|
632
|
+
description: "The email you sent through Groundmail that this one replies to, as it was when the reply arrived; null when it replies to none of your sent emails"
|
|
633
|
+
};
|
|
634
|
+
var receivedEmailItem = object(
|
|
635
|
+
{
|
|
636
|
+
id: string("Received email id (inb_\u2026)"),
|
|
637
|
+
domain_name: string("The receiving domain"),
|
|
638
|
+
rcpt_to: string("The address it was delivered to"),
|
|
639
|
+
from: string("Sender"),
|
|
640
|
+
to: stringArray("To addresses"),
|
|
641
|
+
cc: stringArray("Cc addresses"),
|
|
642
|
+
subject: string("Subject line"),
|
|
643
|
+
spam_status: nullableString("Content scanning verdict: clean, suspicious or spam; null when not scanned"),
|
|
644
|
+
message_id: nullableString("Its Message-ID header"),
|
|
645
|
+
in_reply_to: nullableString("Its In-Reply-To header"),
|
|
646
|
+
in_reply_to_email: inReplyToEmailItem,
|
|
647
|
+
attachment_count: number("Number of attachments"),
|
|
648
|
+
received_at: string("When it arrived (ISO 8601)")
|
|
649
|
+
},
|
|
650
|
+
["id", "from", "subject"]
|
|
651
|
+
);
|
|
614
652
|
|
|
615
653
|
// src/tools.ts
|
|
616
654
|
var DNS_PROVIDERS = ["cloudflare", "godaddy", "vercel", "netlify", "digitalocean", "dnsimple"];
|
|
@@ -740,6 +778,17 @@ async function callMcpTool(client, name, args) {
|
|
|
740
778
|
if (!id) return textResult("Missing required argument: id", true);
|
|
741
779
|
return textResult(await client.emails.get(id));
|
|
742
780
|
}
|
|
781
|
+
case "list_received_emails": {
|
|
782
|
+
const inReplyToEmail = optString(args, "in_reply_to_email");
|
|
783
|
+
return textResult(
|
|
784
|
+
await client.receivedEmails.list({
|
|
785
|
+
limit: optNumber(args, "limit"),
|
|
786
|
+
cursor: optString(args, "cursor"),
|
|
787
|
+
domain: optString(args, "domain"),
|
|
788
|
+
...inReplyToEmail ? { inReplyToEmail } : {}
|
|
789
|
+
})
|
|
790
|
+
);
|
|
791
|
+
}
|
|
743
792
|
case "apply_domain_dns": {
|
|
744
793
|
const domain = String(args.domain ?? "").trim();
|
|
745
794
|
if (!domain) {
|
|
@@ -1198,6 +1247,23 @@ var MCP_TOOLS = [
|
|
|
1198
1247
|
outputSchema: getEmailOutput,
|
|
1199
1248
|
annotations: readOnly("Get email")
|
|
1200
1249
|
},
|
|
1250
|
+
{
|
|
1251
|
+
name: "list_received_emails",
|
|
1252
|
+
description: "List emails received on domains with inbound enabled, newest first (bodies left out). A reply to an email you sent through Groundmail has in_reply_to_email: the sent email it answers. Pass in_reply_to_email: msg_\u2026 to list the replies to one sent email.",
|
|
1253
|
+
inputSchema: {
|
|
1254
|
+
type: "object",
|
|
1255
|
+
properties: {
|
|
1256
|
+
...paginationProps,
|
|
1257
|
+
domain: { type: "string", description: "Only messages received on this domain" },
|
|
1258
|
+
in_reply_to_email: {
|
|
1259
|
+
type: "string",
|
|
1260
|
+
description: "Only replies to this sent email (msg_\u2026)"
|
|
1261
|
+
}
|
|
1262
|
+
}
|
|
1263
|
+
},
|
|
1264
|
+
outputSchema: pagedOutput("received_emails", receivedEmailItem, "Received emails on this page, newest first"),
|
|
1265
|
+
annotations: readOnly("List received emails")
|
|
1266
|
+
},
|
|
1201
1267
|
{
|
|
1202
1268
|
name: "list_domains",
|
|
1203
1269
|
description: "List sending domains for this account.",
|
|
@@ -1815,7 +1881,7 @@ function resolveApiKey() {
|
|
|
1815
1881
|
}
|
|
1816
1882
|
|
|
1817
1883
|
// src/server.ts
|
|
1818
|
-
var MCP_SERVER_VERSION = "0.
|
|
1884
|
+
var MCP_SERVER_VERSION = "0.17.0";
|
|
1819
1885
|
var MCP_SERVER_INSTRUCTIONS = [
|
|
1820
1886
|
"Groundmail sends transactional email from domains the user has verified.",
|
|
1821
1887
|
'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.',
|
|
@@ -1823,10 +1889,30 @@ var MCP_SERVER_INSTRUCTIONS = [
|
|
|
1823
1889
|
"Confirm with the user before sending email to anyone other than themselves.",
|
|
1824
1890
|
"Errors include a stable code and a link to https://docs.groundmail.dev/errors#<code> that says how to fix them."
|
|
1825
1891
|
].join(" ");
|
|
1892
|
+
var currentTool = new AsyncLocalStorage();
|
|
1893
|
+
function agentToken(name) {
|
|
1894
|
+
const token = name?.trim().split(/[\s/]/)[0]?.replace(/[^\w.-]/g, "").slice(0, 60);
|
|
1895
|
+
return token || null;
|
|
1896
|
+
}
|
|
1897
|
+
function mcpUserAgent(agent) {
|
|
1898
|
+
const token = agentToken(agent);
|
|
1899
|
+
return `groundmail-mcp/${MCP_SERVER_VERSION}${token ? ` (agent ${token})` : ""} node/${process.versions.node}`;
|
|
1900
|
+
}
|
|
1901
|
+
function mcpFetch(getAgent) {
|
|
1902
|
+
return (input, init) => {
|
|
1903
|
+
const headers = new Headers(init?.headers);
|
|
1904
|
+
headers.set("User-Agent", mcpUserAgent(getAgent()));
|
|
1905
|
+
const tool = currentTool.getStore();
|
|
1906
|
+
if (tool) headers.set("X-Groundmail-Mcp-Tool", tool);
|
|
1907
|
+
return fetch(input, { ...init, headers });
|
|
1908
|
+
};
|
|
1909
|
+
}
|
|
1826
1910
|
function createMcpServer(apiKey, baseUrl, options = {}) {
|
|
1827
1911
|
const excluded = options.http ? HTTP_EXCLUDED_TOOLS : /* @__PURE__ */ new Set();
|
|
1828
|
-
|
|
1829
|
-
const
|
|
1912
|
+
let server = null;
|
|
1913
|
+
const fetchImpl = mcpFetch(() => options.agent ?? server?.getClientVersion()?.name ?? null);
|
|
1914
|
+
const client = new Groundmail(apiKey, baseUrl ? { baseUrl, fetch: fetchImpl } : { fetch: fetchImpl });
|
|
1915
|
+
server = new Server(
|
|
1830
1916
|
{ name: "groundmail-mcp", title: "Groundmail", version: MCP_SERVER_VERSION },
|
|
1831
1917
|
{ capabilities: { tools: {} }, instructions: MCP_SERVER_INSTRUCTIONS }
|
|
1832
1918
|
);
|
|
@@ -1842,8 +1928,10 @@ function createMcpServer(apiKey, baseUrl, options = {}) {
|
|
|
1842
1928
|
}));
|
|
1843
1929
|
server.setRequestHandler(CallToolRequestSchema, async (request) => {
|
|
1844
1930
|
if (excluded.has(request.params.name)) return textResult(HTTP_EXCLUDED_TOOL_MESSAGE, true);
|
|
1845
|
-
|
|
1846
|
-
|
|
1931
|
+
return currentTool.run(
|
|
1932
|
+
request.params.name,
|
|
1933
|
+
() => callMcpTool(client, request.params.name, request.params.arguments ?? {})
|
|
1934
|
+
);
|
|
1847
1935
|
});
|
|
1848
1936
|
return server;
|
|
1849
1937
|
}
|
|
@@ -2004,7 +2092,10 @@ async function handleHttpRequest(req, res, options = {}) {
|
|
|
2004
2092
|
);
|
|
2005
2093
|
return;
|
|
2006
2094
|
}
|
|
2007
|
-
const server = createMcpServer(apiKey, options.baseUrl, {
|
|
2095
|
+
const server = createMcpServer(apiKey, options.baseUrl, {
|
|
2096
|
+
http: true,
|
|
2097
|
+
agent: typeof req.headers["user-agent"] === "string" ? req.headers["user-agent"] : null
|
|
2098
|
+
});
|
|
2008
2099
|
const transport = new StreamableHTTPServerTransport({
|
|
2009
2100
|
sessionIdGenerator: void 0
|
|
2010
2101
|
});
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "groundmail-mcp",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.17.0",
|
|
4
4
|
"mcpName": "io.github.Groundmail/groundmail",
|
|
5
5
|
"description": "Groundmail MCP server: send transactional email, manage domains, templates, webhooks and suppressions from Claude, Cursor, ChatGPT and other MCP clients",
|
|
6
6
|
"license": "MIT",
|
|
@@ -41,7 +41,7 @@
|
|
|
41
41
|
},
|
|
42
42
|
"dependencies": {
|
|
43
43
|
"@modelcontextprotocol/sdk": "^1.32.1",
|
|
44
|
-
"groundmail": "0.
|
|
44
|
+
"groundmail": "0.29.0"
|
|
45
45
|
},
|
|
46
46
|
"devDependencies": {
|
|
47
47
|
"tsup": "^8.5.0",
|