@sendora/mcp 1.0.0

package/dist/tools/messages.js

@@ -0,0 +1,145 @@
+import { z } from 'zod';
+import { toolError } from '../errors.js';
+import { READING } from '../tool.js';
+import { serverConnectionOf } from './server.js';
+const recipientStatus = z.enum(['queued', 'delivered', 'deferred', 'bounced', 'expired']);
+export const messageOutput = z.object({
+    messageId: z.string().describe('The id the log, the events and the webhooks refer to.'),
+    streamId: z.string().describe('The stream the message went on.'),
+    broadcastId: z
+        .string()
+        .nullable()
+        .describe('The broadcast the message belongs to; null for a message sent on its own.'),
+    status: z
+        .enum(['accepted', 'injected', 'failed'])
+        .describe('accepted until it leaves Sendora, injected once handed to delivery, failed if never.'),
+    from: z.string().describe('The sender.'),
+    subject: z.string().describe('The subject line.'),
+    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.'),
+    submittedAt: z.string().describe('When the API accepted it.'),
+    test: z.boolean().describe('True for a test server’s message: its events were simulated.'),
+    recipients: z
+        .array(z.object({
+        address: z.string().describe('The recipient.'),
+        kind: z.enum(['to', 'cc', 'bcc']).describe('Whether it was in to, cc or bcc.'),
+        status: recipientStatus.describe('queued until the receiver answers; delivered, bounced or expired once it has settled; deferred while it is retried.'),
+    }))
+        .describe('Each recipient and its state: queued, delivered, deferred, bounced or expired.'),
+});
+export const messageEventOutput = z.object({
+    recipient: z
+        .string()
+        .nullable()
+        .describe('The recipient the event is about; null when it concerns the message as a whole.'),
+    type: z
+        .enum([
+        'Reception',
+        'Delivery',
+        'Bounce',
+        'TransientFailure',
+        'Expiration',
+        'AdminBounce',
+        'OOB',
+        'Feedback',
+        'AdminRebind',
+        'DeferredInjectionRebind',
+        'Rejection',
+        'Delayed',
+    ])
+        .describe('Reception when the mail server took it, Delivery, TransientFailure for a deferral, Bounce, OOB for a bounce report by mail, Feedback for a spam complaint, and the rest.'),
+    at: z.string().describe('When it happened.'),
+    code: z.number().int().nullable().describe('The SMTP status code the receiver answered.'),
+    details: z.string().nullable().describe("The receiver's response text."),
+    classification: z
+        .string()
+        .nullable()
+        .describe('How a bounce was classified, such as InvalidRecipient.'),
+});
+export const messageDetailOutput = messageOutput.extend({
+    attachments: z
+        .array(z.object({
+        name: z.string().describe('The file name.'),
+        contentType: z.string().describe('Its media type.'),
+        contentId: z.string().nullable().describe('Its cid, when the HTML shows it.'),
+        size: z.number().int().describe('Bytes before encoding.'),
+    }))
+        .describe('Each attachment described; the content is never returned.'),
+    events: z
+        .array(messageEventOutput)
+        .describe("The timeline, oldest event first, with the receiver's answer: Reception, Delivery, TransientFailure, Bounce, Feedback for a complaint and more."),
+});
+export const searchInput = z.object({
+    recipient: z.email().optional().describe('Messages to this address, in to, cc or bcc.'),
+    streamId: z.uuid().optional().describe('Messages on this stream of the server.'),
+    broadcastId: z.uuid().optional().describe('Messages of this broadcast.'),
+    tag: z.string().trim().min(1).max(100).optional().describe('Messages sent with this tag.'),
+    status: recipientStatus
+        .optional()
+        .describe('Messages with at least one recipient in this state.'),
+    from: z.iso
+        .datetime({ offset: true })
+        .optional()
+        .describe('Submitted at or after this time, ISO 8601.'),
+    to: z.iso.datetime({ offset: true }).optional().describe('Submitted before this time, ISO 8601.'),
+    limit: z.number().int().min(1).max(100).default(20).describe('Messages per page, 1 to 100.'),
+    after: z.uuid().optional().describe('The next value of the previous page.'),
+});
+/** `search_messages` (docs/design/mcp.md §4.2): the server's log, filtered, newest first. */
+export const searchMessagesTool = {
+    name: 'search_messages',
+    class: 'read',
+    reach: 'server',
+    operations: ['POST /v1/messages/search'],
+    register: (server, { connection }) => server.registerTool('search_messages', {
+        title: 'Search the message log',
+        description: "Searches this server's message log, newest first, by recipient, stream, broadcast, tag, a recipient's state and when the message was submitted. Answers each message with its recipients and their state, and next for the following page; get_message reads one message's timeline.",
+        inputSchema: searchInput,
+        outputSchema: z.object({
+            messages: z.array(messageOutput).describe('The page of messages, newest first.'),
+            next: z
+                .string()
+                .nullable()
+                .describe('Pass as after for the next page; null on the last.'),
+        }),
+        annotations: READING,
+    }, async (search) => {
+        try {
+            const page = await serverConnectionOf(connection).sendora.messages.search(search);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(page) }],
+                structuredContent: page,
+            };
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    }),
+};
+/** `get_message` (docs/design/mcp.md §4.2): one message, its recipients, attachments described and timeline. */
+export const getMessageTool = {
+    name: 'get_message',
+    class: 'read',
+    reach: 'server',
+    operations: ['GET /v1/messages/{id}'],
+    register: (server, { connection }) => server.registerTool('get_message', {
+        title: 'Read one message and its timeline',
+        description: "Reads one message of this server's log by its messageId: its recipients and their state, its attachments described but never their content, and every event on its timeline, oldest first, with the receiver's answer. The body is never returned.",
+        inputSchema: z.object({
+            messageId: z.uuid().describe('The message, from send_email or search_messages.'),
+        }),
+        outputSchema: messageDetailOutput,
+        annotations: READING,
+    }, async ({ messageId }) => {
+        try {
+            const message = await serverConnectionOf(connection).sendora.messages.get(messageId);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(message) }],
+                structuredContent: message,
+            };
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    }),
+};

package/dist/tools/send-input.js

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+import { address, attachment, attachmentBytes, builtSize, customHeaders, MAX_ATTACHMENT_BYTES, MAX_MESSAGE_BYTES, MAX_RECIPIENTS, metadata, tag, } from './message-fields.js';
+/*
+ * What send_email takes (docs/design/mcp.md §4.2): the API's send request as
+ * packages/domain/src/send-request.ts has it, on the rules of
+ * message-fields.ts, with the tool's own tighter bound on attachments and its
+ * wait. test/send-input.test.ts holds that the two refuse the same inputs
+ * with the same issues (§13 E05).
+ */
+const MAX_WAIT_SECONDS = 60;
+export const sendInput = z
+    .object({
+    from: address.describe('The sender, as an address or { email, name }. Its domain must be a verified sending domain of the account.'),
+    streamId: z
+        .uuid()
+        .optional()
+        .describe('The stream it goes on, from get_server; the default transactional stream when left out.'),
+    to: z.array(address).min(1).describe('Recipients; at most 50 across to, cc and bcc.'),
+    cc: z.array(address).optional().describe('Copied recipients, shown in the message.'),
+    bcc: z.array(address).optional().describe('Blind-copied recipients.'),
+    subject: z.string().min(1).max(998).describe('The subject line, 1 to 998 characters.'),
+    text: z.string().min(1).optional().describe('The plain-text part; text or html is required.'),
+    html: z.string().min(1).optional().describe('The HTML part.'),
+    headers: customHeaders
+        .optional()
+        .describe('Custom headers by name, at most 20. Headers Sendora sets itself, such as From, Subject and Content-*, are refused.'),
+    attachments: z
+        .array(attachment)
+        .max(20, 'at most 20 attachments per message')
+        .optional()
+        .describe('At most 20, together at most 5 MB decoded.'),
+    tag: tag.describe('A label of up to 100 characters, returned with the message and its events.'),
+    metadata: metadata
+        .optional()
+        .describe('Up to 20 key-value pairs of your own, returned with the message and its events.'),
+    waitSeconds: z
+        .number()
+        .int()
+        .min(0)
+        .max(MAX_WAIT_SECONDS)
+        .default(20)
+        .describe('How long to wait for every recipient to be delivered, bounced or expired before answering; 0 answers at once.'),
+})
+    .refine((input) => input.text !== undefined || input.html !== undefined, {
+    message: 'text or html is required',
+    path: ['text'],
+})
+    .refine((input) => input.to.length + (input.cc?.length ?? 0) + (input.bcc?.length ?? 0) <= MAX_RECIPIENTS, { message: 'at most 50 recipients per message', path: ['to'] })
+    .refine((input) => builtSize(input) <= MAX_MESSAGE_BYTES, {
+    message: 'the message would exceed 10 MB once built',
+    path: ['attachments'],
+})
+    .refine((input) => attachmentBytes(input) <= MAX_ATTACHMENT_BYTES, {
+    message: 'the attachments may be at most 5 MB decoded together',
+    path: ['attachments'],
+});

package/dist/tools/send.js

@@ -0,0 +1,140 @@
+import { SendoraError } from '@sendora/sdk';
+import { z } from 'zod';
+import { toolError } from '../errors.js';
+import { messageDetailOutput } from './messages.js';
+import { sendInput } from './send-input.js';
+import { SIMULATOR_NOTE, serverConnectionOf } from './server.js';
+const SETTLED = new Set(['delivered', 'bounced', 'expired']);
+/** Every recipient delivered, bounced or expired: nothing more will change but a complaint. */
+export function settled(message) {
+    return message.recipients.every((recipient) => SETTLED.has(recipient.status));
+}
+/**
+ * When, in milliseconds after the send, the message is read while waiting
+ * up to `waitMs`: after half a second, one second and two, then every four,
+ * and once more when the wait is up (§4.2).
+ */
+export function readTimes(waitMs) {
+    if (waitMs <= 0) {
+        return [];
+    }
+    const times = [500, 1000, 2000].filter((at) => at < waitMs);
+    for (let at = 6000; at < waitMs; at += 4000) {
+        times.push(at);
+    }
+    return [...times, waitMs];
+}
+async function waitForOutcome(sendora, messageId, waitMs) {
+    let message = null;
+    let elapsed = 0;
+    for (const at of readTimes(waitMs)) {
+        await new Promise((resolve) => setTimeout(resolve, at - elapsed));
+        elapsed = at;
+        try {
+            message = await sendora.messages.get(messageId);
+        }
+        catch (error) {
+            if (!(error instanceof SendoraError)) {
+                throw error;
+            }
+            return { message, settled: false, unread: error };
+        }
+        if (settled(message)) {
+            return { message, settled: true, unread: undefined };
+        }
+    }
+    return { message, settled: false, unread: undefined };
+}
+/** The SDK's request for the tool's input: everything but the wait. */
+export function requestOf(input) {
+    const fields = {
+        from: input.from,
+        streamId: input.streamId,
+        to: input.to,
+        cc: input.cc,
+        bcc: input.bcc,
+        subject: input.subject,
+        headers: input.headers,
+        attachments: input.attachments,
+        tag: input.tag,
+        metadata: input.metadata,
+    };
+    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 message without text or html');
+}
+/** What the agent should know of the answer: why it is unsettled, and on a test server the simulator. */
+export function notesFor(outcome, test, waitSeconds) {
+    const notes = [];
+    if (outcome.unread !== undefined) {
+        notes.push(`The message was accepted, but reading its outcome failed (${outcome.unread.code}); read it later with get_message rather than send it again.`);
+    }
+    else if (!outcome.settled && waitSeconds > 0) {
+        notes.push(`Not every recipient was settled within ${String(waitSeconds)} ${waitSeconds === 1 ? 'second' : 'seconds'}; read it later with get_message rather than send it again.`);
+    }
+    if (test) {
+        notes.push(SIMULATOR_NOTE);
+    }
+    return notes;
+}
+const outputSchema = z.object({
+    messageId: z.string().describe('The id get_message and search_messages find it by.'),
+    submittedAt: z.string().describe('When the API accepted it.'),
+    test: z.boolean().describe('True when a test server took it: nobody receives it.'),
+    settled: z
+        .boolean()
+        .describe('Whether every recipient was delivered, bounced or expired before the answer.'),
+    message: messageDetailOutput
+        .nullable()
+        .describe('The message as last read, with its timeline; null when it was not read.'),
+    notes: z.array(z.string()).describe('What the agent should know of this answer.'),
+});
+const TEST_DESCRIPTION = `Sends one email from this test server and waits up to waitSeconds for its outcome, answering the message with every recipient's state and its timeline. ${SIMULATOR_NOTE} A retry after a lost answer sends once. For many messages, write code with the SDK instead.`;
+const LIVE_DESCRIPTION = "Sends one email from this live server, to real people, and waits up to waitSeconds for its outcome, answering the message with every recipient's state and its timeline. Confirm the recipients and the content with the user first. A retry after a lost answer sends once. For many messages, write code with the SDK instead.";
+/** `send_email` (docs/design/mcp.md §4.2): one message, and its outcome when it comes within the wait. */
+export const sendEmailTool = {
+    name: 'send_email',
+    class: 'write',
+    reach: 'server',
+    operations: ['POST /v1/email', 'GET /v1/messages/{id}'],
+    register: (server, { connection }) => {
+        const { kind, sendora } = serverConnectionOf(connection);
+        server.registerTool('send_email', {
+            title: 'Send one email',
+            description: kind === 'test' ? TEST_DESCRIPTION : LIVE_DESCRIPTION,
+            inputSchema: sendInput,
+            outputSchema,
+            annotations: {
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: false,
+                openWorldHint: kind === 'live',
+            },
+        }, async (input) => {
+            let accepted;
+            try {
+                accepted = await sendora.email.send(requestOf(input));
+            }
+            catch (error) {
+                return toolError(error);
+            }
+            const outcome = await waitForOutcome(sendora, accepted.messageId, input.waitSeconds * 1000);
+            const output = {
+                messageId: accepted.messageId,
+                submittedAt: accepted.submittedAt,
+                test: accepted.test,
+                settled: outcome.settled,
+                message: outcome.message,
+                notes: notesFor(outcome, accepted.test, input.waitSeconds),
+            };
+            return {
+                content: [{ type: 'text', text: JSON.stringify(output) }],
+                structuredContent: output,
+            };
+        });
+    },
+};

package/dist/tools/server.js

@@ -0,0 +1,120 @@
+import { z } from 'zod';
+import { toolError } from '../errors.js';
+import { READING } from '../tool.js';
+export const SIMULATOR_NOTE = 'Nothing sent from this test server is delivered. At simulator.sendora.se, hardbounce@, softbounce@, deferred@ and complaint@ act out their outcome, a +label after the name kept; any other address is marked delivered.';
+export const LIVE_NOTE = 'This is a live server: mail sent from it reaches real people, and the log and the suppression list hold real addresses.';
+export const WRITES_OFF_NOTE = "Changes are off for this connection, so it only reads. The user turns them on with --allow-writes (or SENDORA_ALLOW_WRITES=true) where the server runs locally, or the header 'Sendora-Allow-Writes: true' on the hosted server.";
+export const limitOutput = z.object({
+    scope: z
+        .enum(['tenant', 'server', 'test'])
+        .describe("Whose limit it is: the account's, the server's own, or the cap the account's test servers share."),
+    period: z
+        .enum(['minute', 'month'])
+        .describe('The UTC minute or the calendar month in UTC the limit counts over.'),
+    limit: z.number().int().describe('Emails allowed in the period, one per recipient.'),
+    used: z.number().int().describe('Emails the period has taken so far.'),
+    resetsAt: z.string().describe('When the period ends and the count starts again.'),
+});
+export const streamOutput = z.object({
+    streamId: z.string().describe('What a send names as streamId.'),
+    kind: z
+        .enum(['transactional', 'broadcast', 'inbound'])
+        .describe('transactional for mail the recipient expects; broadcast for mail to many; inbound for mail the server receives.'),
+    name: z.string().describe('The name given at creation, unique within the server.'),
+    isDefault: z
+        .boolean()
+        .describe('The stream a send without a streamId goes on; one per server, transactional.'),
+    createdAt: z.string().describe('When it was created.'),
+    archivedAt: z
+        .string()
+        .nullable()
+        .describe('Set once archived; the stream then takes no new messages.'),
+    pausedAt: z
+        .string()
+        .nullable()
+        .describe('Set while Sendora has paused the stream after complaints; it takes no messages until support has resumed it.'),
+    inboundAddress: z
+        .string()
+        .nullable()
+        .describe('The address of an inbound stream, where mail sent is received on the stream. Null on every other kind.'),
+    contentRetentionDays: z
+        .number()
+        .int()
+        .nullable()
+        .describe('How many days an inbound stream keeps received content; null means the default of 30. Null on every other kind.'),
+});
+export const serverOutput = z.object({
+    serverId: z.string().describe('The id the server keys, streams and messages refer to.'),
+    name: z.string().describe('The name given at creation, unique within the account.'),
+    mode: z
+        .enum(['live', 'test'])
+        .describe('test for a server that delivers nothing, live for one that reaches real people.'),
+    createdAt: z.string().describe('When it was created.'),
+});
+const outputSchema = z.object({
+    server: serverOutput.describe('The server this key belongs to, and whether it is a test server.'),
+    limits: z
+        .array(limitOutput)
+        .describe('Every limit a send on the server is held to, with its use this minute or month.'),
+    streams: z.array(streamOutput).describe("The server's streams; a send names one as streamId."),
+    connection: z
+        .object({
+        kind: z.enum(['test', 'live']).describe("The kind of this connection's key."),
+        changes: z
+            .boolean()
+            .describe('Whether this connection may change things, such as send mail.'),
+    })
+        .describe("This connection's kind of key and whether it may change things."),
+    notes: z.array(z.string()).describe('What the agent should know before it acts.'),
+});
+/** A connection that holds a server key; a tool of that reach is listed on no other. */
+export function serverConnectionOf(connection) {
+    if (connection.kind !== 'test' && connection.kind !== 'live') {
+        throw new Error('a server tool was registered on a connection without a server key');
+    }
+    return connection;
+}
+/** `get_server` (docs/design/mcp.md §4.2): where the agent stands before it acts. */
+export const getServerTool = {
+    name: 'get_server',
+    class: 'read',
+    reach: 'server',
+    operations: ['GET /v1/server', 'GET /v1/streams'],
+    register: (server, { connection }) => server.registerTool('get_server', {
+        title: 'Read the server this key belongs to',
+        description: "Call this first. Answers the Sendora server this connection's key belongs to: whether it is a test server, where nothing is delivered, or a live one; every limit a send on it is held to, with this minute's and month's use; its streams; and whether this connection may change things.",
+        inputSchema: z.object({}),
+        outputSchema,
+        annotations: READING,
+    }, async () => {
+        const { kind, writes, sendora } = serverConnectionOf(connection);
+        const changes = kind === 'test' || writes;
+        try {
+            const [own, { streams }] = await Promise.all([
+                sendora.server.get(),
+                sendora.streams.list(),
+            ]);
+            const output = {
+                server: {
+                    serverId: own.serverId,
+                    name: own.name,
+                    mode: own.mode,
+                    createdAt: own.createdAt,
+                },
+                limits: own.limits,
+                streams,
+                connection: { kind: own.mode, changes },
+                notes: own.mode === 'test'
+                    ? [SIMULATOR_NOTE]
+                    : [LIVE_NOTE, ...(changes ? [] : [WRITES_OFF_NOTE])],
+            };
+            return {
+                content: [{ type: 'text', text: JSON.stringify(output) }],
+                structuredContent: output,
+            };
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    }),
+};

package/dist/tools/servers.js

@@ -0,0 +1,91 @@
+import { z } from 'zod';
+import { toolError } from '../errors.js';
+import { READING } from '../tool.js';
+import { serverOutput } from './server.js';
+/** A connection that holds the account key; a tool of that reach is listed on no other. */
+export function accountConnectionOf(connection) {
+    if (connection.kind !== 'account') {
+        throw new Error('an account tool was registered on a connection without the account key');
+    }
+    return connection;
+}
+/** `list_servers` (docs/design/mcp.md §4.2): the account's servers, each with its mode. */
+export const listServersTool = {
+    name: 'list_servers',
+    class: 'read',
+    reach: 'account',
+    operations: ['GET /v1/servers'],
+    register: (server, { connection }) => server.registerTool('list_servers', {
+        title: "List the account's servers",
+        description: "Lists the account's servers, oldest first, each with its mode: a test server delivers nothing, a live one reaches real people. Each server's own keys send its mail and read its log; the account key manages the servers and the sending domains and never sends.",
+        inputSchema: z.object({}),
+        outputSchema: z.object({
+            servers: z.array(serverOutput).describe('Every server of the account.'),
+        }),
+        annotations: READING,
+    }, async () => {
+        try {
+            const list = await accountConnectionOf(connection).account.servers.list();
+            return {
+                content: [{ type: 'text', text: JSON.stringify(list) }],
+                structuredContent: list,
+            };
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    }),
+};
+export const LIVE_SERVER_REFUSED = 'delete_test_server deletes test servers only, and this one is live: its mail reaches real people, so only an administrator deletes it, in the dashboard, https://app.sendora.se/servers.';
+function refusedLiveServer() {
+    return {
+        content: [{ type: 'text', text: `live_server: ${LIVE_SERVER_REFUSED}` }],
+        structuredContent: { error: { code: 'live_server', message: LIVE_SERVER_REFUSED } },
+        isError: true,
+    };
+}
+/**
+ * `delete_test_server` (docs/design/mcp.md §4.2): the API deletes any server
+ * the account key names, so the read is the guard; a server's mode never
+ * changes (D-250 (2)), so nothing can turn it live between the two calls.
+ */
+export const deleteTestServerTool = {
+    name: 'delete_test_server',
+    class: 'irreversible',
+    reach: 'account',
+    operations: ['GET /v1/servers/{id}', 'DELETE /v1/servers/{id}'],
+    register: (server, { connection }) => server.registerTool('delete_test_server', {
+        title: 'Delete a test server',
+        description: "Deletes one of the account's test servers with its keys, streams, messages, suppressions and webhooks; it cannot be undone. It reads the server first and refuses a live one, which only an administrator deletes, in the dashboard. Take the id from list_servers and confirm the server's name with the user first.",
+        inputSchema: z.object({
+            serverId: z.uuid().describe('The test server, from list_servers.'),
+        }),
+        outputSchema: z.object({
+            serverId: z.string().describe('The server deleted.'),
+            name: z.string().describe('Its name, to tell the user which server went.'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ serverId }) => {
+        const { account } = accountConnectionOf(connection);
+        try {
+            const found = await account.servers.get(serverId);
+            if (found.mode !== 'test') {
+                return refusedLiveServer();
+            }
+            await account.servers.delete(serverId);
+            const output = { serverId: found.serverId, name: found.name };
+            return {
+                content: [{ type: 'text', text: JSON.stringify(output) }],
+                structuredContent: output,
+            };
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    }),
+};

package/dist/tools/streams.js

@@ -0,0 +1,81 @@
+import { z } from 'zod';
+import { toolError } from '../errors.js';
+import { serverConnectionOf, streamOutput } from './server.js';
+/** `create_stream` (docs/design/mcp.md §4.2): transactional or broadcast, and inbound only on a live server. */
+export const createStreamTool = {
+    name: 'create_stream',
+    class: 'write',
+    reach: 'server',
+    operations: ['POST /v1/streams'],
+    register: (server, { connection }) => {
+        const { kind, sendora } = serverConnectionOf(connection);
+        const kinds = kind === 'live'
+            ? ['transactional', 'broadcast', 'inbound']
+            : ['transactional', 'broadcast'];
+        server.registerTool('create_stream', {
+            title: 'Add a stream',
+            description: kind === 'live'
+                ? 'Adds a stream to this live server: transactional for one-to-one mail, broadcast for mail to a list, or inbound to receive mail, one live per server. Answers the stream; a send names it by its streamId.'
+                : 'Adds a stream to this test server: transactional for one-to-one mail, or broadcast for mail to a list, which send_broadcast needs. Answers the stream; a send names it by its streamId. A test server receives no mail, so it has no inbound stream.',
+            inputSchema: z.object({
+                kind: z.enum(kinds).describe('What the stream carries.'),
+                name: z
+                    .string()
+                    .trim()
+                    .min(1)
+                    .max(100)
+                    .describe('1 to 100 characters, unique within the server.'),
+            }),
+            outputSchema: streamOutput,
+            annotations: {
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: false,
+                openWorldHint: false,
+            },
+        }, async (request) => {
+            try {
+                const stream = await sendora.streams.create(request);
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(stream) }],
+                    structuredContent: stream,
+                };
+            }
+            catch (error) {
+                return toolError(error);
+            }
+        });
+    },
+};
+/** `archive_stream` (docs/design/mcp.md §4.2): a test server's stream archived, for good. */
+export const archiveStreamTool = {
+    name: 'archive_stream',
+    class: 'irreversible',
+    reach: 'server',
+    operations: ['POST /v1/streams/{id}/archive'],
+    register: (server, { connection }) => server.registerTool('archive_stream', {
+        title: 'Archive a stream',
+        description: "Archives a stream of this test server: it takes no new messages from then on, and an archived stream cannot be restored. The server's default stream cannot be archived.",
+        inputSchema: z.object({
+            streamId: z.uuid().describe('The stream, from get_server.'),
+        }),
+        outputSchema: streamOutput,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ streamId }) => {
+        try {
+            const stream = await serverConnectionOf(connection).sendora.streams.archive(streamId);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(stream) }],
+                structuredContent: stream,
+            };
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    }),
+};