groundmail-mcp 0.23.0 → 0.25.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 +180 -2
- 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), received emails (with replies linked to the email you sent), domains (add, apply DNS through Cloudflare, Vercel, GoDaddy, Netlify, DigitalOcean or DNSimple, verify), senders (saved names and addresses to send as), your brand (logo, colors and footer every template follows), 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), batch sends (status counts, cancel the scheduled emails in one call), received emails (with replies linked to the email you sent), domains (add, apply DNS through Cloudflare, Vercel, GoDaddy, Netlify, DigitalOcean or DNSimple, verify), senders (saved names and addresses to send as), your brand (logo, colors and footer every template follows), 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
|
@@ -88,6 +88,7 @@ var nullableString = (description) => ({ type: ["string", "null"], description }
|
|
|
88
88
|
var string = (description) => ({ type: "string", description });
|
|
89
89
|
var boolean = (description) => ({ type: "boolean", description });
|
|
90
90
|
var number = (description) => ({ type: "number", description });
|
|
91
|
+
var nullableNumber = (description) => ({ type: ["number", "null"], description });
|
|
91
92
|
var stringArray = (description) => ({
|
|
92
93
|
type: "array",
|
|
93
94
|
items: { type: "string" },
|
|
@@ -181,6 +182,7 @@ var emailItem = object(
|
|
|
181
182
|
bounced_at: nullableString("When the email bounced (ISO 8601)"),
|
|
182
183
|
opened_at: nullableString("First open (ISO 8601); needs open tracking on the sending domain"),
|
|
183
184
|
clicked_at: nullableString("First tracked-link click (ISO 8601); needs click tracking on the sending domain"),
|
|
185
|
+
batch_id: nullableString("The batch send it came from (batch_\u2026), for get_batch and cancel_batch; null for a single send"),
|
|
184
186
|
tenant: nullableString("External id of the tenant the email was sent as. Present only when it was sent as a tenant"),
|
|
185
187
|
stream: string("Mail stream it went out on: transactional, product or newsletter (each sends from its own IPs)")
|
|
186
188
|
},
|
|
@@ -250,11 +252,37 @@ var webhookItem = object(
|
|
|
250
252
|
events: stringArray("Event types delivered to this endpoint"),
|
|
251
253
|
enabled: boolean("Whether the endpoint receives events"),
|
|
252
254
|
tenants: stringArray("Present only when the endpoint receives email events for some tenants only: their external ids"),
|
|
255
|
+
health: {
|
|
256
|
+
type: "object",
|
|
257
|
+
description: "Delivery health: last_24h (total, delivered, failed, median_latency_ms), last_delivery_at, last_status, last_response_status, and failing (a delivery failed all 5 attempts in the last 24 hours)"
|
|
258
|
+
},
|
|
253
259
|
created_at: string("When the endpoint was created (ISO 8601)"),
|
|
254
260
|
updated_at: string("When the endpoint was last changed (ISO 8601)")
|
|
255
261
|
},
|
|
256
262
|
["id", "url", "events"]
|
|
257
263
|
);
|
|
264
|
+
var webhookDeliveryItem = object(
|
|
265
|
+
{
|
|
266
|
+
id: string("Delivery id"),
|
|
267
|
+
webhook_id: string("The endpoint it was sent to"),
|
|
268
|
+
event: string("Event type"),
|
|
269
|
+
status: string("pending, retrying, delivered or failed"),
|
|
270
|
+
attempt_count: number("Attempts made so far"),
|
|
271
|
+
max_attempts: number("Attempts this delivery gets"),
|
|
272
|
+
email_id: nullableString("The email this event is about"),
|
|
273
|
+
recipient: nullableString("The first recipient, or the contact"),
|
|
274
|
+
test: boolean("True for a simulated event"),
|
|
275
|
+
response_status: nullableNumber("HTTP status of the latest attempt"),
|
|
276
|
+
error_kind: nullableString("Why nothing answered: timeout or connection"),
|
|
277
|
+
latency_ms: nullableNumber("Response time of the latest attempt in ms"),
|
|
278
|
+
last_attempt_at: nullableString("When the latest attempt started (ISO 8601)"),
|
|
279
|
+
next_attempt_at: nullableString("When the next retry runs (ISO 8601)"),
|
|
280
|
+
resent_from: nullableString("The delivery this one resends"),
|
|
281
|
+
created_at: string("When the delivery was created (ISO 8601)"),
|
|
282
|
+
updated_at: string("When the delivery last changed (ISO 8601)")
|
|
283
|
+
},
|
|
284
|
+
["id", "webhook_id", "event", "status"]
|
|
285
|
+
);
|
|
258
286
|
var suppressionItem = object(
|
|
259
287
|
{
|
|
260
288
|
id: string("Suppression id"),
|
|
@@ -366,6 +394,28 @@ var validateEmailOutput = object(
|
|
|
366
394
|
["email", "verdict", "reasons", "suggestion", "disposable", "role"]
|
|
367
395
|
);
|
|
368
396
|
var getEmailOutput = object({ email: described(emailItem, "The email") }, ["email"]);
|
|
397
|
+
var batchOutput = object(
|
|
398
|
+
{
|
|
399
|
+
batch_id: string("Batch id (batch_\u2026)"),
|
|
400
|
+
created_at: string("When the batch's first email was created (ISO 8601)"),
|
|
401
|
+
total: number("Emails in the batch"),
|
|
402
|
+
counts: {
|
|
403
|
+
type: "object",
|
|
404
|
+
additionalProperties: { type: "number" },
|
|
405
|
+
description: 'Emails by current status, for example { "scheduled": 98, "sent": 2 }. Only statuses with an email appear'
|
|
406
|
+
}
|
|
407
|
+
},
|
|
408
|
+
["batch_id", "created_at", "total", "counts"]
|
|
409
|
+
);
|
|
410
|
+
var cancelBatchOutput = object(
|
|
411
|
+
{
|
|
412
|
+
batch_id: string("Batch id (batch_\u2026)"),
|
|
413
|
+
cancelled: number("Scheduled emails this call cancelled"),
|
|
414
|
+
already_cancelled: number("Emails that were already cancelled before this call"),
|
|
415
|
+
not_cancellable: number("Emails already queued, sent or finished, which can no longer be cancelled")
|
|
416
|
+
},
|
|
417
|
+
["batch_id", "cancelled", "already_cancelled", "not_cancellable"]
|
|
418
|
+
);
|
|
369
419
|
var domainWithRecordsOutput = object(
|
|
370
420
|
{
|
|
371
421
|
domain: described(domainItem, "The domain"),
|
|
@@ -423,6 +473,15 @@ var createWebhookOutput = object(
|
|
|
423
473
|
},
|
|
424
474
|
["webhook", "secret"]
|
|
425
475
|
);
|
|
476
|
+
var webhookDeliveryOutput = object(
|
|
477
|
+
{
|
|
478
|
+
delivery: {
|
|
479
|
+
...described(webhookDeliveryItem, "The delivery, with `attempts` and the `payload` sent"),
|
|
480
|
+
additionalProperties: true
|
|
481
|
+
}
|
|
482
|
+
},
|
|
483
|
+
["delivery"]
|
|
484
|
+
);
|
|
426
485
|
var suppressionOutput = object({ suppression: described(suppressionItem, "The suppression entry") }, ["suppression"]);
|
|
427
486
|
var templateOutput = object({ template: described(templateItem, "The template") }, ["template"]);
|
|
428
487
|
var testWebhookOutput = object(
|
|
@@ -532,7 +591,6 @@ var migrationOutput = object(
|
|
|
532
591
|
},
|
|
533
592
|
["migration"]
|
|
534
593
|
);
|
|
535
|
-
var nullableNumber = (description) => ({ type: ["number", "null"], description });
|
|
536
594
|
var tenantItem = object(
|
|
537
595
|
{
|
|
538
596
|
id: string("Groundmail tenant id"),
|
|
@@ -875,6 +933,16 @@ async function callMcpTool(client, name, args) {
|
|
|
875
933
|
if (!id) return textResult("Missing required argument: id", true);
|
|
876
934
|
return textResult(await client.emails.get(id));
|
|
877
935
|
}
|
|
936
|
+
case "get_batch": {
|
|
937
|
+
const id = optString(args, "batch_id");
|
|
938
|
+
if (!id) return textResult("Missing required argument: batch_id", true);
|
|
939
|
+
return textResult(await client.batches.get(id));
|
|
940
|
+
}
|
|
941
|
+
case "cancel_batch": {
|
|
942
|
+
const id = optString(args, "batch_id");
|
|
943
|
+
if (!id) return textResult("Missing required argument: batch_id", true);
|
|
944
|
+
return textResult(await client.batches.cancel(id));
|
|
945
|
+
}
|
|
878
946
|
case "list_received_emails": {
|
|
879
947
|
const inReplyToEmail = optString(args, "in_reply_to_email");
|
|
880
948
|
return textResult(
|
|
@@ -932,6 +1000,32 @@ async function callMcpTool(client, name, args) {
|
|
|
932
1000
|
})
|
|
933
1001
|
);
|
|
934
1002
|
}
|
|
1003
|
+
case "list_webhook_deliveries": {
|
|
1004
|
+
const webhookId = optString(args, "webhook_id");
|
|
1005
|
+
if (!webhookId) return textResult("Missing required argument: webhook_id", true);
|
|
1006
|
+
return textResult(
|
|
1007
|
+
await client.webhooks.deliveries.list(webhookId, {
|
|
1008
|
+
limit: optNumber(args, "limit"),
|
|
1009
|
+
cursor: optString(args, "cursor"),
|
|
1010
|
+
status: optString(args, "status"),
|
|
1011
|
+
event: optString(args, "event"),
|
|
1012
|
+
email_id: optString(args, "email_id"),
|
|
1013
|
+
q: optString(args, "q")
|
|
1014
|
+
})
|
|
1015
|
+
);
|
|
1016
|
+
}
|
|
1017
|
+
case "get_webhook_delivery": {
|
|
1018
|
+
const webhookId = optString(args, "webhook_id");
|
|
1019
|
+
const id = optString(args, "id");
|
|
1020
|
+
if (!webhookId || !id) return textResult("Missing required arguments: webhook_id and id", true);
|
|
1021
|
+
return textResult(await client.webhooks.deliveries.get(webhookId, id));
|
|
1022
|
+
}
|
|
1023
|
+
case "resend_webhook_delivery": {
|
|
1024
|
+
const webhookId = optString(args, "webhook_id");
|
|
1025
|
+
const id = optString(args, "id");
|
|
1026
|
+
if (!webhookId || !id) return textResult("Missing required arguments: webhook_id and id", true);
|
|
1027
|
+
return textResult(await client.webhooks.deliveries.resend(webhookId, id));
|
|
1028
|
+
}
|
|
935
1029
|
case "create_webhook": {
|
|
936
1030
|
const url = optString(args, "url");
|
|
937
1031
|
if (!url) return textResult("Missing required argument: url", true);
|
|
@@ -1413,6 +1507,38 @@ var MCP_TOOLS = [
|
|
|
1413
1507
|
outputSchema: getEmailOutput,
|
|
1414
1508
|
annotations: readOnly("Get email")
|
|
1415
1509
|
},
|
|
1510
|
+
{
|
|
1511
|
+
name: "get_batch",
|
|
1512
|
+
description: "Get a batch send (the batch_id a batch send returned, also on each of its emails as batch_id): how many emails it has and how many are in each status now.",
|
|
1513
|
+
inputSchema: {
|
|
1514
|
+
type: "object",
|
|
1515
|
+
properties: {
|
|
1516
|
+
batch_id: { type: "string", description: "Batch id (batch_\u2026)" }
|
|
1517
|
+
},
|
|
1518
|
+
required: ["batch_id"]
|
|
1519
|
+
},
|
|
1520
|
+
outputSchema: batchOutput,
|
|
1521
|
+
annotations: readOnly("Get batch")
|
|
1522
|
+
},
|
|
1523
|
+
{
|
|
1524
|
+
name: "cancel_batch",
|
|
1525
|
+
description: "Cancel every email in a batch send that is still scheduled. Emails already queued or sent are left alone and counted in not_cancellable. Safe to repeat: a second call cancels nothing more. Confirm with the user before cancelling.",
|
|
1526
|
+
inputSchema: {
|
|
1527
|
+
type: "object",
|
|
1528
|
+
properties: {
|
|
1529
|
+
batch_id: { type: "string", description: "Batch id (batch_\u2026)" }
|
|
1530
|
+
},
|
|
1531
|
+
required: ["batch_id"]
|
|
1532
|
+
},
|
|
1533
|
+
outputSchema: cancelBatchOutput,
|
|
1534
|
+
annotations: {
|
|
1535
|
+
title: "Cancel batch",
|
|
1536
|
+
readOnlyHint: false,
|
|
1537
|
+
destructiveHint: true,
|
|
1538
|
+
idempotentHint: true,
|
|
1539
|
+
openWorldHint: false
|
|
1540
|
+
}
|
|
1541
|
+
},
|
|
1416
1542
|
{
|
|
1417
1543
|
name: "list_received_emails",
|
|
1418
1544
|
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.",
|
|
@@ -1517,6 +1643,58 @@ var MCP_TOOLS = [
|
|
|
1517
1643
|
outputSchema: pagedOutput("webhooks", webhookItem, "Webhook endpoints on this page"),
|
|
1518
1644
|
annotations: readOnly("List webhooks")
|
|
1519
1645
|
},
|
|
1646
|
+
{
|
|
1647
|
+
name: "list_webhook_deliveries",
|
|
1648
|
+
description: "List the delivery log of one webhook endpoint, newest first: every event sent to it in the last 30 days with its status, attempts and response. Use it to find failed deliveries.",
|
|
1649
|
+
inputSchema: {
|
|
1650
|
+
type: "object",
|
|
1651
|
+
properties: {
|
|
1652
|
+
webhook_id: { type: "string", description: "Webhook id" },
|
|
1653
|
+
status: { type: "string", enum: ["pending", "retrying", "delivered", "failed"], description: "Only this status" },
|
|
1654
|
+
event: { type: "string", description: "Only this event type, for example email.delivered" },
|
|
1655
|
+
email_id: { type: "string", description: "Only deliveries for this email" },
|
|
1656
|
+
q: { type: "string", description: "An exact email id, or part of a recipient address" },
|
|
1657
|
+
...paginationProps
|
|
1658
|
+
},
|
|
1659
|
+
required: ["webhook_id"]
|
|
1660
|
+
},
|
|
1661
|
+
outputSchema: pagedOutput("deliveries", webhookDeliveryItem, "Deliveries on this page"),
|
|
1662
|
+
annotations: readOnly("List webhook deliveries")
|
|
1663
|
+
},
|
|
1664
|
+
{
|
|
1665
|
+
name: "get_webhook_delivery",
|
|
1666
|
+
description: "Get one webhook delivery: every attempt with its status code and latency, the payload sent, and what the endpoint replied (first 2 KB).",
|
|
1667
|
+
inputSchema: {
|
|
1668
|
+
type: "object",
|
|
1669
|
+
properties: {
|
|
1670
|
+
webhook_id: { type: "string", description: "Webhook id" },
|
|
1671
|
+
id: { type: "string", description: "Delivery id" }
|
|
1672
|
+
},
|
|
1673
|
+
required: ["webhook_id", "id"]
|
|
1674
|
+
},
|
|
1675
|
+
outputSchema: webhookDeliveryOutput,
|
|
1676
|
+
annotations: readOnly("Get webhook delivery")
|
|
1677
|
+
},
|
|
1678
|
+
{
|
|
1679
|
+
name: "resend_webhook_delivery",
|
|
1680
|
+
description: "Send a delivery again: the same payload as a new delivery, signed afresh, with the usual retries. The original stays as it was. The endpoint must be turned on; limited to 30 resends a minute.",
|
|
1681
|
+
inputSchema: {
|
|
1682
|
+
type: "object",
|
|
1683
|
+
properties: {
|
|
1684
|
+
webhook_id: { type: "string", description: "Webhook id" },
|
|
1685
|
+
id: { type: "string", description: "Delivery id to resend" }
|
|
1686
|
+
},
|
|
1687
|
+
required: ["webhook_id", "id"]
|
|
1688
|
+
},
|
|
1689
|
+
outputSchema: webhookDeliveryOutput,
|
|
1690
|
+
annotations: {
|
|
1691
|
+
title: "Resend webhook delivery",
|
|
1692
|
+
readOnlyHint: false,
|
|
1693
|
+
destructiveHint: false,
|
|
1694
|
+
idempotentHint: false,
|
|
1695
|
+
openWorldHint: true
|
|
1696
|
+
}
|
|
1697
|
+
},
|
|
1520
1698
|
{
|
|
1521
1699
|
name: "create_webhook",
|
|
1522
1700
|
description: "Create a webhook endpoint. Returns the endpoint plus a signing secret (shown once).",
|
|
@@ -2123,7 +2301,7 @@ function resolveApiKey() {
|
|
|
2123
2301
|
}
|
|
2124
2302
|
|
|
2125
2303
|
// src/server.ts
|
|
2126
|
-
var MCP_SERVER_VERSION = "0.
|
|
2304
|
+
var MCP_SERVER_VERSION = "0.25.0";
|
|
2127
2305
|
var MCP_SERVER_INSTRUCTIONS = [
|
|
2128
2306
|
"Groundmail sends transactional email from domains the user has verified.",
|
|
2129
2307
|
'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.',
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "groundmail-mcp",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.25.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.2",
|
|
44
|
-
"groundmail": "0.
|
|
44
|
+
"groundmail": "0.39.0"
|
|
45
45
|
},
|
|
46
46
|
"devDependencies": {
|
|
47
47
|
"tsup": "^8.5.0",
|