@sendora/mcp 1.0.0

package/dist/tools/suppressions.js

@@ -0,0 +1,102 @@
+import { z } from 'zod';
+import { toolError } from '../errors.js';
+import { READING } from '../tool.js';
+import { serverConnectionOf } from './server.js';
+export const suppressionOutput = z.object({
+    streamId: z.string().describe('The stream whose list the address is on.'),
+    address: z.string().describe('The recipient, lower-cased.'),
+    reason: z
+        .enum(['hard_bounce', 'spam_complaint', 'manual', 'unsubscribe'])
+        .describe('Why the server will not send to it.'),
+    messageId: z.string().nullable().describe('The message whose bounce or complaint put it here.'),
+    createdAt: z.string().describe('When it was put on the list.'),
+});
+export const removedOutput = z.object({
+    address: z.string().describe('The address lifted.'),
+    streamId: z
+        .string()
+        .nullable()
+        .describe('The stream whose list held it; null for the default transactional stream.'),
+});
+const STREAM = 'The stream whose list is meant, from get_server; the default transactional stream when left out.';
+/** `list_suppressions` (docs/design/mcp.md §4.2): a stream's suppression list, per stream. */
+export const listSuppressionsTool = {
+    name: 'list_suppressions',
+    class: 'read',
+    reach: 'server',
+    operations: ['GET /v1/suppressions'],
+    register: (server, { connection }) => server.registerTool('list_suppressions', {
+        title: "List a stream's suppression list",
+        description: 'Lists the addresses one stream of this server will not send to, and why: a hard bounce, a spam complaint, an unsubscribe or a manual entry. A send to one of them is refused with recipient_suppressed; a hard bounce or a manual entry can be lifted with remove_suppression.',
+        inputSchema: z.object({
+            streamId: z.uuid().optional().describe(STREAM),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .default(20)
+                .describe('Addresses per page, 1 to 100.'),
+            after: z.uuid().optional().describe('The next value of the previous page.'),
+        }),
+        outputSchema: z.object({
+            suppressions: z.array(suppressionOutput).describe('The page of the list.'),
+            next: z
+                .string()
+                .nullable()
+                .describe('Pass as after for the next page; null on the last.'),
+        }),
+        annotations: READING,
+    }, async (query) => {
+        try {
+            const page = await serverConnectionOf(connection).sendora.suppressions.list(query);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(page) }],
+                structuredContent: page,
+            };
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    }),
+};
+const REMOVE_DESCRIPTION = "Lifts an address from one stream's suppression list so this server may send to it again on that stream: a hard bounce or a manual entry. A spam complaint or an unsubscribe cannot be lifted, since the recipient asked.";
+/** `remove_suppression` (docs/design/mcp.md §4.2): a hard bounce or a manual entry lifted. */
+export const removeSuppressionTool = {
+    name: 'remove_suppression',
+    class: 'write',
+    reach: 'server',
+    operations: ['POST /v1/suppressions/delete'],
+    register: (server, { connection }) => {
+        const { kind, sendora } = serverConnectionOf(connection);
+        server.registerTool('remove_suppression', {
+            title: 'Lift a suppression',
+            description: kind === 'live'
+                ? `${REMOVE_DESCRIPTION} On this live server the address is a real person's: confirm with the user first.`
+                : REMOVE_DESCRIPTION,
+            inputSchema: z.object({
+                address: z.email().describe('The address to send to again.'),
+                streamId: z.uuid().optional().describe(STREAM),
+            }),
+            outputSchema: removedOutput,
+            annotations: {
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async ({ address, streamId }) => {
+            try {
+                await sendora.suppressions.delete({ address, streamId });
+            }
+            catch (error) {
+                return toolError(error);
+            }
+            const output = { address, streamId: streamId ?? null };
+            return {
+                content: [{ type: 'text', text: JSON.stringify(output) }],
+                structuredContent: output,
+            };
+        });
+    },
+};

package/dist/tools/webhooks.js

@@ -0,0 +1,251 @@
+import { z } from 'zod';
+import { toolError } from '../errors.js';
+import { READING } from '../tool.js';
+import { serverConnectionOf } from './server.js';
+const eventName = z.enum([
+    'delivered',
+    'bounced',
+    'deferred',
+    'spam_complaint',
+    'unsubscribed',
+    'cap_warning',
+    'cap_reached',
+    'inbound',
+]);
+export const webhookOutput = z.object({
+    webhookId: z.string().describe('What the deliveries and a delete refer to.'),
+    url: z.string().describe('Where the events are posted.'),
+    events: z.array(eventName).describe('The events it receives.'),
+    streamId: z
+        .string()
+        .nullable()
+        .describe('The one stream whose message events it receives; null for every stream.'),
+    enabled: z
+        .boolean()
+        .describe('False while switched off in the dashboard; nothing is queued for it then.'),
+    inboundContent: z
+        .enum(['full', 'reference'])
+        .describe('How the inbound event carries a received message: the parsed message, or a reference.'),
+    createdAt: z.string().describe('When it was created.'),
+    secrets: z
+        .array(z.object({
+        secretId: z.string().describe('The secret, by id; its value was shown once.'),
+        createdAt: z.string().describe('When it was made.'),
+    }))
+        .describe('The live signing secrets by id and age, oldest first; their values are never answered again.'),
+});
+export const createdWebhookOutput = webhookOutput.extend({
+    secret: z
+        .string()
+        .describe("The signing secret, shown this once: into the project's environment, never a file under version control."),
+});
+export const deliveryOutput = z.object({
+    deliveryId: z.string().describe('What a replay refers to.'),
+    event: eventName.describe('The event it carries.'),
+    messageId: z
+        .string()
+        .nullable()
+        .describe('The message it is about; null for an event about usage.'),
+    inboundMessageId: z
+        .string()
+        .nullable()
+        .describe('The received message an inbound event is about; null for every other event.'),
+    status: z
+        .enum(['pending', 'delivered', 'dead'])
+        .describe('pending until its next attempt; delivered; dead after its retries, and replayable.'),
+    attempts: z.number().int().describe('How many times it was posted.'),
+    nextAttemptAt: z.string().nullable().describe('When the next attempt is due, while pending.'),
+    lastStatusCode: z
+        .number()
+        .int()
+        .nullable()
+        .describe('The HTTP status the endpoint last answered.'),
+    lastError: z.string().nullable().describe('Why the last attempt failed, when it did.'),
+    deliveredAt: z.string().nullable().describe('When the endpoint took it.'),
+    createdAt: z.string().describe('When the event was queued.'),
+});
+const webhookId = z.uuid().describe('The webhook, from list_webhooks.');
+export const createWebhookInput = z.object({
+    url: z.string().describe('An https URL on a public host, without credentials or a fragment.'),
+    events: z
+        .array(eventName)
+        .min(1)
+        .optional()
+        .describe('The events to deliver; every event when left out.'),
+    streamId: z
+        .uuid()
+        .optional()
+        .describe('Limits the message events to one stream of the server; every stream when left out.'),
+    inboundContent: z
+        .enum(['full', 'reference'])
+        .optional()
+        .describe('How the inbound event carries a received message; full when left out.'),
+});
+/** `list_webhooks` (docs/design/mcp.md §4.2): the server's webhooks, their secrets by id and age alone. */
+export const listWebhooksTool = {
+    name: 'list_webhooks',
+    class: 'read',
+    reach: 'server',
+    operations: ['GET /v1/webhooks'],
+    register: (server, { connection }) => server.registerTool('list_webhooks', {
+        title: "List the server's webhooks",
+        description: "Lists this server's webhooks: where each posts, which events and stream, whether it is switched on, and its signing secrets by id and age. A secret's value is shown once, when it is made, and never answered again.",
+        inputSchema: z.object({}),
+        outputSchema: z.object({
+            webhooks: z.array(webhookOutput).describe("The server's webhooks."),
+        }),
+        annotations: READING,
+    }, async () => {
+        try {
+            const list = await serverConnectionOf(connection).sendora.webhooks.list();
+            return {
+                content: [{ type: 'text', text: JSON.stringify(list) }],
+                structuredContent: list,
+            };
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    }),
+};
+/** `list_webhook_deliveries` (docs/design/mcp.md §4.2): one webhook's deliveries, by status. */
+export const listWebhookDeliveriesTool = {
+    name: 'list_webhook_deliveries',
+    class: 'read',
+    reach: 'server',
+    operations: ['GET /v1/webhooks/{id}/deliveries'],
+    register: (server, { connection }) => server.registerTool('list_webhook_deliveries', {
+        title: "List a webhook's deliveries",
+        description: "Lists the events on their way to one webhook, newest first: pending with its next attempt, delivered, or dead after its retries, with the endpoint's last answer. A dead delivery can be sent again with replay_webhook_delivery.",
+        inputSchema: z.object({
+            webhookId,
+            status: z
+                .enum(['pending', 'delivered', 'dead'])
+                .optional()
+                .describe('Deliveries in this state only.'),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .default(20)
+                .describe('Deliveries per page, 1 to 100.'),
+            after: z.uuid().optional().describe('The next value of the previous page.'),
+        }),
+        outputSchema: z.object({
+            deliveries: z.array(deliveryOutput).describe('The page of deliveries, newest first.'),
+            next: z
+                .string()
+                .nullable()
+                .describe('Pass as after for the next page; null on the last.'),
+        }),
+        annotations: READING,
+    }, async ({ webhookId: id, ...query }) => {
+        try {
+            const page = await serverConnectionOf(connection).sendora.webhooks.deliveries(id, query);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(page) }],
+                structuredContent: page,
+            };
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    }),
+};
+/** `replay_webhook_delivery` (docs/design/mcp.md §4.2): an event queued for its webhook again. */
+export const replayWebhookDeliveryTool = {
+    name: 'replay_webhook_delivery',
+    class: 'write',
+    reach: 'server',
+    operations: ['POST /v1/webhooks/{id}/deliveries/{deliveryId}/replay'],
+    register: (server, { connection }) => server.registerTool('replay_webhook_delivery', {
+        title: 'Replay a webhook delivery',
+        description: 'Queues one delivery of a webhook again, whatever its state, with the same payload, a fresh signature and a fresh count of attempts: for an endpoint that was down or was fixed. Each replay posts the event once more.',
+        inputSchema: z.object({
+            webhookId,
+            deliveryId: z.uuid().describe('The delivery, from list_webhook_deliveries.'),
+        }),
+        outputSchema: deliveryOutput,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async ({ webhookId: id, deliveryId }) => {
+        try {
+            const delivery = await serverConnectionOf(connection).sendora.webhooks.replay(id, deliveryId);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(delivery) }],
+                structuredContent: delivery,
+            };
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    }),
+};
+/** `create_webhook` (docs/design/mcp.md §4.2): a webhook on a test server, its secret answered once. */
+export const createWebhookTool = {
+    name: 'create_webhook',
+    class: 'secret',
+    reach: 'server',
+    operations: ['POST /v1/webhooks'],
+    register: (server, { connection }) => server.registerTool('create_webhook', {
+        title: 'Add a webhook',
+        description: "Adds a webhook to this test server and answers its signing secret, shown this once: put it in the project's environment, such as SENDORA_WEBHOOK_SECRET in .env, never in a file under version control, and verify every delivery with the SDK's webhooks.receive or verifyWebhook. The API takes only a public https URL, so a local endpoint needs a tunnel. Events arrive as the simulator plays out each message.",
+        inputSchema: createWebhookInput,
+        outputSchema: createdWebhookOutput,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async (request) => {
+        try {
+            const created = await serverConnectionOf(connection).sendora.webhooks.create(request);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(created) }],
+                structuredContent: created,
+            };
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    }),
+};
+/** `delete_webhook` (docs/design/mcp.md §4.2): a test server's webhook removed, for good. */
+export const deleteWebhookTool = {
+    name: 'delete_webhook',
+    class: 'irreversible',
+    reach: 'server',
+    operations: ['DELETE /v1/webhooks/{id}'],
+    register: (server, { connection }) => server.registerTool('delete_webhook', {
+        title: 'Delete a webhook',
+        description: 'Deletes a webhook of this test server with its secrets and deliveries; nothing more is posted to it, and it cannot be restored.',
+        inputSchema: z.object({ webhookId }),
+        outputSchema: z.object({
+            webhookId: z.string().describe('The webhook deleted.'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ webhookId: id }) => {
+        try {
+            await serverConnectionOf(connection).sendora.webhooks.delete(id);
+        }
+        catch (error) {
+            return toolError(error);
+        }
+        const output = { webhookId: id };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(output) }],
+            structuredContent: output,
+        };
+    }),
+};

package/dist/version.js

@@ -0,0 +1,2 @@
+/** This package's version, held equal to its package.json by a test. */
+export const MCP_VERSION = '1.0.0';

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@sendora/mcp",
+  "version": "1.0.0",
+  "description": "The official MCP server for Sendora: its documentation and API for coding agents.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "sendora-mcp": "./dist/stdio.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.19"
+  },
+  "homepage": "https://sendora.se/docs/mcp",
+  "keywords": [
+    "sendora",
+    "mcp",
+    "email",
+    "transactional"
+  ],
+  "mcpName": "se.sendora/mcp",
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.1.0",
+    "zod": "^4.6.2",
+    "@sendora/sdk": "^3.6.1"
+  },
+  "devDependencies": {
+    "@anthropic-ai/mcpb": "2.1.2",
+    "@modelcontextprotocol/client": "^2.1.0",
+    "@modelcontextprotocol/conformance": "0.2.0-alpha.11",
+    "@modelcontextprotocol/node": "^2.1.0",
+    "esbuild": "^0.28.2",
+    "fast-check": "^4.10.2",
+    "fflate": "^0.8.3",
+    "typescript": "~7.0.2",
+    "vitest": "^4.1.11",
+    "@sendora/db": "0.0.0",
+    "@sendora/api": "0.0.0",
+    "@sendora/domain": "0.0.0",
+    "@sendora/observability": "0.0.0",
+    "@sendora/site": "0.0.0"
+  },
+  "scripts": {
+    "build": "pnpm --filter @sendora/sdk build && node scripts/build-docs.ts && node -e \"fs.rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json && node -e \"fs.mkdirSync('dist/generated',{recursive:true});fs.copyFileSync('src/generated/docs.json','dist/generated/docs.json')\""
+  }
+}