@sendora/mcp 1.0.0

package/dist/tools/broadcasts.js

@@ -0,0 +1,150 @@
+import { z } from 'zod';
+import { toolError } from '../errors.js';
+import { READING } from '../tool.js';
+import { broadcastInput } from './broadcast-input.js';
+import { serverConnectionOf, SIMULATOR_NOTE } from './server.js';
+export const acceptedBroadcastOutput = z.object({
+    broadcastId: z.string().describe('What get_broadcast, cancel_broadcast and the log refer to.'),
+    status: z.literal('accepted').describe('Accepted; its messages leave as the stream drains.'),
+    total: z.number().int().describe('Messages stored; each is a message in the log.'),
+    suppressed: z
+        .number()
+        .int()
+        .describe("Addresses dropped for standing on the stream's suppression list."),
+    submittedAt: z.string().describe('When the API accepted it.'),
+    test: z.boolean().describe('True when a test server took it: nobody receives it.'),
+});
+export const broadcastOutput = z.object({
+    broadcastId: z.string().describe('The broadcast.'),
+    streamId: z.string().describe('The broadcast stream its messages go on.'),
+    status: z
+        .enum(['accepted', 'processing', 'completed', 'cancelled'])
+        .describe('accepted until the first message leaves, processing while they leave, completed when none is left, cancelled once cancelled.'),
+    from: z.string().describe('The sender.'),
+    subject: z.string().describe('The subject line, before substitutions.'),
+    tag: z.string().nullable().describe('The label it was sent with.'),
+    metadata: z.record(z.string(), z.string()).describe('The key-value pairs it was sent with.'),
+    total: z.number().int().describe('Messages stored, after suppressed addresses were dropped.'),
+    released: z.number().int().describe('Messages handed over for delivery so far.'),
+    failed: z
+        .number()
+        .int()
+        .describe('Messages that could not be handed over, cancelled ones included.'),
+    suppressed: z
+        .number()
+        .int()
+        .describe("Addresses dropped for standing on the stream's suppression list."),
+    submittedAt: z.string().describe('When the API accepted it.'),
+    completedAt: z
+        .string()
+        .nullable()
+        .describe('When nothing was left to send, or it was cancelled.'),
+});
+/** The SDK's request for the tool's input. */
+export function broadcastRequestOf(input) {
+    const fields = {
+        streamId: input.streamId,
+        from: input.from,
+        subject: input.subject,
+        headers: input.headers,
+        attachments: input.attachments,
+        tag: input.tag,
+        metadata: input.metadata,
+        messages: input.messages,
+    };
+    if (input.text !== undefined) {
+        return { ...fields, text: input.text, html: input.html };
+    }
+    if (input.html !== undefined) {
+        return { ...fields, html: input.html };
+    }
+    throw new Error('the input schema let through a broadcast without text or html');
+}
+/** `send_broadcast` (docs/design/mcp.md §4.2): a broadcast of at most 100 messages, on a test server. */
+export const sendBroadcastTool = {
+    name: 'send_broadcast',
+    class: 'irreversible',
+    reach: 'server',
+    operations: ['POST /v1/broadcasts'],
+    register: (server, { connection }) => server.registerTool('send_broadcast', {
+        title: 'Send a test broadcast',
+        description: `Sends a broadcast from this test server, to try one before code sends the real list with the SDK: the content once and one message per entry, at most 100, on a broadcast stream (create_stream makes one). Put {{ unsubscribe_url }} in the text or HTML where each recipient's unsubscribe link goes, and {{ key }} for each entry's substitutions. Addresses on the stream's suppression list are dropped and counted. A broadcast sent cannot be taken back; cancel_broadcast stops what has not left. Follow it with get_broadcast. ${SIMULATOR_NOTE}`,
+        inputSchema: broadcastInput,
+        outputSchema: acceptedBroadcastOutput,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async (input) => {
+        try {
+            const accepted = await serverConnectionOf(connection).sendora.broadcasts.send(broadcastRequestOf(input));
+            return {
+                content: [{ type: 'text', text: JSON.stringify(accepted) }],
+                structuredContent: accepted,
+            };
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    }),
+};
+const broadcastIdInput = z.object({
+    broadcastId: z.uuid().describe('The broadcast, from send_broadcast.'),
+});
+/** `get_broadcast` (docs/design/mcp.md §4.2): a broadcast and how far it has come. */
+export const getBroadcastTool = {
+    name: 'get_broadcast',
+    class: 'read',
+    reach: 'server',
+    operations: ['GET /v1/broadcasts/{id}'],
+    register: (server, { connection }) => server.registerTool('get_broadcast', {
+        title: 'Read a broadcast',
+        description: 'Reads a broadcast of this server and how far it has come: released and failed move as its messages leave, and status is completed once none is left. Each of its messages is in the log; search_messages with its broadcastId finds them.',
+        inputSchema: broadcastIdInput,
+        outputSchema: broadcastOutput,
+        annotations: READING,
+    }, async ({ broadcastId }) => {
+        try {
+            const broadcast = await serverConnectionOf(connection).sendora.broadcasts.get(broadcastId);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(broadcast) }],
+                structuredContent: broadcast,
+            };
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    }),
+};
+/** `cancel_broadcast` (docs/design/mcp.md §4.2): what has not left, stopped, on a test server. */
+export const cancelBroadcastTool = {
+    name: 'cancel_broadcast',
+    class: 'irreversible',
+    reach: 'server',
+    operations: ['POST /v1/broadcasts/{id}/cancel'],
+    register: (server, { connection }) => server.registerTool('cancel_broadcast', {
+        title: 'Cancel a broadcast',
+        description: 'Cancels the messages of a broadcast of this test server that have not left yet, which then count as failed; those that left stay sent. A cancelled broadcast cannot be resumed.',
+        inputSchema: broadcastIdInput,
+        outputSchema: broadcastOutput,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ broadcastId }) => {
+        try {
+            const broadcast = await serverConnectionOf(connection).sendora.broadcasts.cancel(broadcastId);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(broadcast) }],
+                structuredContent: broadcast,
+            };
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    }),
+};

package/dist/tools/docs.js

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+import { INDEX_URI } from '../docs.js';
+import { READING } from '../tool.js';
+const hitSchema = z.object({
+    uri: z.string().describe('The document to read with read_doc.'),
+    title: z.string().describe("The document's title."),
+    section: z.string().describe('The heading of the section that matched.'),
+    snippet: z.string().describe('The words around the match, marked where they are cut.'),
+});
+/** `search_docs` and `read_doc`, listed on every connection, keyless included (docs/design/mcp.md §6.2). */
+export const docsTools = [
+    {
+        name: 'search_docs',
+        class: 'docs',
+        reach: 'all',
+        operations: [],
+        register: (server, { docs }) => server.registerTool('search_docs', {
+            title: 'Search the Sendora docs',
+            description: "Search Sendora's guides, API reference, error codes and SDK README. Use it before writing code against @sendora/sdk or the HTTP API, and whenever an error code or a limit needs explaining. Answers the best-matching sections with their document's uri; read the whole document with read_doc.",
+            inputSchema: z.object({
+                query: z
+                    .string()
+                    .min(1)
+                    .max(500)
+                    .describe('Words to look for, such as "verify webhook signature" or an error code such as recipient_suppressed.'),
+                limit: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(10)
+                    .default(5)
+                    .describe('How many sections, at most.'),
+            }),
+            outputSchema: z.object({
+                results: z.array(hitSchema).describe('The best-matching sections, the best first.'),
+            }),
+            annotations: READING,
+        }, ({ query, limit }) => {
+            const output = { results: docs.search(query, limit) };
+            return {
+                content: [{ type: 'text', text: JSON.stringify(output) }],
+                structuredContent: output,
+            };
+        }),
+    },
+    {
+        name: 'read_doc',
+        class: 'docs',
+        reach: 'all',
+        operations: [],
+        register: (server, { docs }) => server.registerTool('read_doc', {
+            title: 'Read a Sendora document',
+            description: `Read one of Sendora's documents whole, as Markdown: a guide (sendora://docs/…), an API operation (sendora://reference/…), the error codes (sendora://errors) or the SDK's README and rules for agents (sendora://sdk/readme, sendora://sdk/skill). ${INDEX_URI} lists every document; search_docs finds the right one.`,
+            inputSchema: z.object({
+                uri: z.string().min(1).describe(`A document's address, such as ${INDEX_URI}.`),
+            }),
+            annotations: READING,
+        }, ({ uri }) => {
+            const doc = docs.find(uri);
+            if (doc === undefined) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `No document at ${uri}. Find one with search_docs, or read ${INDEX_URI} for the list.`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            return { content: [{ type: 'text', text: doc.text }] };
+        }),
+    },
+];

package/dist/tools/domains.js

@@ -0,0 +1,133 @@
+import { z } from 'zod';
+import { toolError } from '../errors.js';
+import { READING } from '../tool.js';
+import { accountConnectionOf } from './servers.js';
+/** A DNS record a domain needs and whether it was seen, for a sending domain and a domain for receiving alike. */
+export function recordOutput(type, what) {
+    return z
+        .object({
+        type: z.literal(type).describe('The record type.'),
+        host: z.string().describe('The name to create the record under.'),
+        value: z.string().describe('The value the record must hold.'),
+        verified: z
+            .boolean()
+            .describe('Whether Sendora counts the record as found; a lookup that fails at the resolver never clears it.'),
+        verifiedAt: z
+            .string()
+            .nullable()
+            .describe('When Sendora began counting it as found; null while it does not.'),
+    })
+        .describe(what);
+}
+export const recordCheck = z.enum(['ok', 'missing', 'mismatch', 'dns_error']);
+export const domainOutput = z.object({
+    domainId: z.string().describe('What check_domain checks it by.'),
+    domain: z.string().describe('The domain mail is sent from.'),
+    verified: z
+        .boolean()
+        .describe('True while both records count as found; only then may mail go out from it. A lookup that fails at the resolver never changes it, and a record found missing starts a 24-hour warning (failingSince) through which the domain stays verified.'),
+    createdAt: z.string().describe('When it was added.'),
+    lastCheckedAt: z.string().nullable().describe('When the records were last looked up.'),
+    failingSince: z
+        .string()
+        .nullable()
+        .describe("When a check first found a record of this verified domain missing or wrong: mail keeps going out, the records are looked up hourly, and the first check 24 hours after this that still misses one ends the verification and the domain's mail with it. Null unless the domain is verified and in that warning; verified and each record tell the rest."),
+    returnPath: recordOutput('CNAME', 'The CNAME record for the return path, where bounces come back, which also satisfies SPF.'),
+    dkim: recordOutput('TXT', "The TXT record that publishes the domain's DKIM key."),
+});
+export const checkedDomainOutput = domainOutput.extend({
+    check: z
+        .object({
+        returnPath: recordCheck.describe('What the CNAME lookup found.'),
+        dkim: recordCheck.describe('What the TXT lookup found.'),
+    })
+        .describe('What each lookup found; dns_error is a resolver failure, such as a timeout, not an absent record.'),
+});
+/** `list_domains` (docs/design/mcp.md §4.2): the account's sending domains and their records. */
+export const listDomainsTool = {
+    name: 'list_domains',
+    class: 'read',
+    reach: 'account',
+    operations: ['GET /v1/domains'],
+    register: (server, { connection }) => server.registerTool('list_domains', {
+        title: 'List the sending domains',
+        description: "Lists the account's sending domains, which every server of the account sends from, each with the two DNS records it needs, a CNAME for the return path and a TXT record for the DKIM key, and whether each was seen. Mail goes out from a domain once both are; check_domain looks them up now.",
+        inputSchema: z.object({}),
+        outputSchema: z.object({
+            domains: z.array(domainOutput).describe('Every sending domain of the account.'),
+        }),
+        annotations: READING,
+    }, async () => {
+        try {
+            const list = await accountConnectionOf(connection).account.domains.list();
+            return {
+                content: [{ type: 'text', text: JSON.stringify(list) }],
+                structuredContent: list,
+            };
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    }),
+};
+/** `check_domain` (docs/design/mcp.md §4.2): the records looked up now, which changes only what Sendora knows of them. */
+export const checkDomainTool = {
+    name: 'check_domain',
+    class: 'read',
+    reach: 'account',
+    operations: ['POST /v1/domains/{id}/verify'],
+    register: (server, { connection }) => server.registerTool('check_domain', {
+        title: 'Check a sending domain',
+        description: "Looks up both records of one of the account's sending domains now and answers the domain as it stands, with what each lookup found: ok, missing, mismatch or dns_error. Mail may go out from the domain once both are ok; a record just added may take a while to be seen. A verified domain whose record is found missing keeps sending for 24 hours (failingSince), and a dns_error changes nothing. A check that begins that warning or ends the verification mails the account's administrators, as Sendora's own checks do.",
+        inputSchema: z.object({
+            domainId: z.uuid().describe('The domain, from list_domains or add_domain.'),
+        }),
+        outputSchema: checkedDomainOutput,
+        annotations: { ...READING, openWorldHint: true },
+    }, async ({ domainId }) => {
+        try {
+            const domain = await accountConnectionOf(connection).account.domains.verify(domainId);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(domain) }],
+                structuredContent: domain,
+            };
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    }),
+};
+/** `add_domain` (docs/design/mcp.md §4.2): a sending domain added with its DKIM key, and the records to publish. */
+export const addDomainTool = {
+    name: 'add_domain',
+    class: 'write',
+    reach: 'account',
+    operations: ['POST /v1/domains'],
+    register: (server, { connection }) => server.registerTool('add_domain', {
+        title: 'Add a sending domain',
+        description: "Adds a domain the account sends from, with a DKIM key of its own, and answers the two records for the user to add to the domain's DNS: a CNAME for the return path, which also satisfies SPF, and a TXT record with the DKIM key. check_domain then looks them up, and every server of the account may send from the domain once both are seen. A domain the account already has is refused with domain_exists.",
+        inputSchema: z.object({
+            domain: z
+                .string()
+                .describe('The domain mail is sent from, such as example.se; the part after the @.'),
+        }),
+        outputSchema: domainOutput,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async (request) => {
+        try {
+            const domain = await accountConnectionOf(connection).account.domains.create(request);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(domain) }],
+                structuredContent: domain,
+            };
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    }),
+};

package/dist/tools/inbound-domains.js

@@ -0,0 +1,118 @@
+import { z } from 'zod';
+import { toolError } from '../errors.js';
+import { READING } from '../tool.js';
+import { recordCheck, recordOutput } from './domains.js';
+import { serverConnectionOf } from './server.js';
+export const inboundDomainOutput = z.object({
+    inboundDomainId: z.string().describe('What check_inbound_domain checks it by.'),
+    streamId: z.string().describe('The inbound stream the domain delivers to.'),
+    domain: z.string().describe('The domain, lower-cased and IDNA-encoded.'),
+    verified: z
+        .boolean()
+        .describe('True while both records are seen; only then is mail to the domain accepted.'),
+    createdAt: z.string().describe('When it was added.'),
+    lastCheckedAt: z.string().nullable().describe('When the records were last looked up.'),
+    unverifiedAt: z
+        .string()
+        .nullable()
+        .describe('When a verified domain lost its records: its mail is deferred for 72 hours from then and refused after, until they are back.'),
+    mx: recordOutput('MX', "The MX record that brings the domain's mail to Sendora, at any priority."),
+    txt: recordOutput('TXT', 'The TXT record that proves the claim.'),
+});
+export const checkedInboundDomainOutput = inboundDomainOutput.extend({
+    check: z
+        .object({
+        mx: recordCheck.describe('What the MX lookup found.'),
+        txt: recordCheck.describe('What the TXT lookup found.'),
+    })
+        .describe('What each lookup found; dns_error is a resolver failure, such as a timeout, not an absent record.'),
+});
+/** `list_inbound_domains` (docs/design/mcp.md §4.2): the live server's domains for receiving and their records. */
+export const listInboundDomainsTool = {
+    name: 'list_inbound_domains',
+    class: 'read',
+    reach: 'live',
+    operations: ['GET /v1/inbound/domains'],
+    register: (server, { connection }) => server.registerTool('list_inbound_domains', {
+        title: 'List the domains for receiving',
+        description: "Lists this live server's own domains for receiving, one per inbound stream, each catch-all, with the MX and TXT records it needs and whether they were seen.",
+        inputSchema: z.object({}),
+        outputSchema: z.object({
+            domains: z.array(inboundDomainOutput).describe('Every inbound domain of the server.'),
+        }),
+        annotations: READING,
+    }, async () => {
+        try {
+            const list = await serverConnectionOf(connection).sendora.inboundDomains.list();
+            return {
+                content: [{ type: 'text', text: JSON.stringify(list) }],
+                structuredContent: list,
+            };
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    }),
+};
+/** `check_inbound_domain` (docs/design/mcp.md §4.2): the records looked up now, which changes only what Sendora knows of them. */
+export const checkInboundDomainTool = {
+    name: 'check_inbound_domain',
+    class: 'read',
+    reach: 'live',
+    operations: ['POST /v1/inbound/domains/{id}/verify'],
+    register: (server, { connection }) => server.registerTool('check_inbound_domain', {
+        title: 'Check a domain for receiving',
+        description: 'Looks up both records of one of the domains for receiving now and answers the domain as it stands, with what each lookup found: ok, missing, mismatch or dns_error. Mail to the domain is accepted once both are ok.',
+        inputSchema: z.object({
+            inboundDomainId: z.uuid().describe('The domain, from list_inbound_domains.'),
+        }),
+        outputSchema: checkedInboundDomainOutput,
+        annotations: { ...READING, openWorldHint: true },
+    }, async ({ inboundDomainId }) => {
+        try {
+            const domain = await serverConnectionOf(connection).sendora.inboundDomains.verify(inboundDomainId);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(domain) }],
+                structuredContent: domain,
+            };
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    }),
+};
+/** `add_inbound_domain` (docs/design/mcp.md §4.2): a domain claimed for an inbound stream, and the records to add. */
+export const addInboundDomainTool = {
+    name: 'add_inbound_domain',
+    class: 'write',
+    reach: 'live',
+    operations: ['POST /v1/inbound/domains'],
+    register: (server, { connection }) => server.registerTool('add_inbound_domain', {
+        title: 'Add a domain for receiving',
+        description: "Claims a domain of yours for an inbound stream of this live server, which then receives all of the domain's mail. Answers the MX record that brings the mail to Sendora and the TXT record that proves the claim, for the user to add to the domain's DNS; check_inbound_domain then looks them up. A stream has at most one domain.",
+        inputSchema: z.object({
+            streamId: z.uuid().describe('An inbound stream of the server, from get_server.'),
+            domain: z
+                .string()
+                .describe('The domain, such as post.example.se; a name in Unicode is IDNA-encoded.'),
+        }),
+        outputSchema: inboundDomainOutput,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async (request) => {
+        try {
+            const domain = await serverConnectionOf(connection).sendora.inboundDomains.create(request);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(domain) }],
+                structuredContent: domain,
+            };
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    }),
+};