zapsmtp-mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZapSMTP
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,312 @@
-# Temporary Holding Version
+# ZapSMTP MCP server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The official [Model Context Protocol](https://modelcontextprotocol.io) server for
+[ZapSMTP](https://zapsmtp.com): let Claude, Cursor, VS Code, Codex and any other MCP client send,
+receive and track email, and manage templates, domains, webhooks and everything else the API does.
+
+- **The whole API**: one tool per API operation (112), generated from the API reference, so a new
+  endpoint becomes a tool with the next release. Clear descriptions and JSON Schemas with every
+  parameter, required field and allowed value.
+- **Safe to hand to an agent**: tool annotations (read-only, destructive, idempotent, open-world) for
+  clients that ask before acting, `--read-only`, toolsets, a recipient domain allowlist, and sends that
+  never repeat when retried. The API key never reaches the model.
+- **Made for agents**: `send_test_email` tries any delivery outcome on simulator addresses that never
+  leave ZapSMTP; `verify_webhook_signature` checks webhook requests; lists come back one page at a time
+  with a cursor for the next; errors carry the API's code, message and request id.
+- **stdio or Streamable HTTP**: run it next to your editor, or serve a team over HTTP where every client
+  brings its own API key.
+- **The docs as resources**: `llms.txt` and every guide, bundled in the package (nothing is fetched at
+  runtime).
+
+Node.js 18.3 or newer. Built on the official [Node.js SDK](https://www.npmjs.com/package/zapsmtp).
+
+## Quick start
+
+Create an API key in the [dashboard](https://zapsmtp.com) (a `zap_test_…` key runs everything without
+delivering anything), then add the server to your client.
+
+### Claude Code
+
+```bash
+claude mcp add zapsmtp -e ZAP_API_KEY=zap_... -- npx -y zapsmtp-mcp
+```
+
+With a default sender and only the tools you need:
+
+```bash
+claude mcp add zapsmtp -e ZAP_API_KEY=zap_... -e ZAP_SENDER="Acme <hello@acme.com>" \
+  -- npx -y zapsmtp-mcp --toolsets emails,templates,simulator
+```
+
+### Claude Desktop
+
+Settings → Developer → Edit Config (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "zapsmtp": {
+      "command": "npx",
+      "args": ["-y", "zapsmtp-mcp"],
+      "env": { "ZAP_API_KEY": "zap_..." }
+    }
+  }
+}
+```
+
+### Cursor
+
+`~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` (one project):
+
+```json
+{
+  "mcpServers": {
+    "zapsmtp": {
+      "command": "npx",
+      "args": ["-y", "zapsmtp-mcp"],
+      "env": { "ZAP_API_KEY": "zap_..." }
+    }
+  }
+}
+```
+
+### VS Code (GitHub Copilot agent mode)
+
+`.vscode/mcp.json`; VS Code asks for the key once and stores it securely:
+
+```json
+{
+  "inputs": [
+    { "type": "promptString", "id": "zapsmtp-key", "description": "ZapSMTP API key", "password": true }
+  ],
+  "servers": {
+    "zapsmtp": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "zapsmtp-mcp"],
+      "env": { "ZAP_API_KEY": "${input:zapsmtp-key}" }
+    }
+  }
+}
+```
+
+### OpenAI Codex
+
+```bash
+codex mcp add zapsmtp --env ZAP_API_KEY=zap_... -- npx -y zapsmtp-mcp
+```
+
+or in `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.zapsmtp]
+command = "npx"
+args = ["-y", "zapsmtp-mcp"]
+env = { ZAP_API_KEY = "zap_..." }
+```
+
+### Windsurf
+
+`~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "zapsmtp": {
+      "command": "npx",
+      "args": ["-y", "zapsmtp-mcp"],
+      "env": { "ZAP_API_KEY": "zap_..." }
+    }
+  }
+}
+```
+
+### Zed
+
+`settings.json`:
+
+```json
+{
+  "context_servers": {
+    "zapsmtp": {
+      "source": "custom",
+      "command": "npx",
+      "args": ["-y", "zapsmtp-mcp"],
+      "env": { "ZAP_API_KEY": "zap_..." }
+    }
+  }
+}
+```
+
+### Gemini CLI
+
+`~/.gemini/settings.json` (Gemini CLI expands `$ZAP_API_KEY` from your environment):
+
+```json
+{
+  "mcpServers": {
+    "zapsmtp": {
+      "command": "npx",
+      "args": ["-y", "zapsmtp-mcp"],
+      "env": { "ZAP_API_KEY": "$ZAP_API_KEY" }
+    }
+  }
+}
+```
+
+### Any other client
+
+Run `npx -y zapsmtp-mcp` over stdio with `ZAP_API_KEY` in its environment, or connect to the HTTP
+server below.
+
+## Streamable HTTP
+
+```bash
+npx -y zapsmtp-mcp --http                  # http://127.0.0.1:3000/mcp
+npx -y zapsmtp-mcp --http --port 8080 --host 0.0.0.0
+```
+
+The HTTP server holds no API key. Every client sends its own as `Authorization: Bearer <key>`, and each
+request gets its own SDK client and MCP server (the server is stateless), so one client's key is never
+used for another's calls. A request without a key gets `401`.
+
+```bash
+claude mcp add --transport http zapsmtp http://127.0.0.1:3000/mcp --header "Authorization: Bearer zap_..."
+```
+
+```json
+{
+  "mcpServers": {
+    "zapsmtp": { "url": "http://127.0.0.1:3000/mcp", "headers": { "Authorization": "Bearer zap_..." } }
+  }
+}
+```
+
+- It listens on `127.0.0.1` unless `--host` says otherwise, and while on loopback it refuses requests
+  whose `Host` or `Origin` is not local (DNS rebinding).
+- Beyond your machine, put it behind HTTPS (a reverse proxy): the key travels in a header.
+- `GET /health` answers `{"status": "ok"}` for load balancers. Request bodies are limited to 64 MiB.
+
+## Options
+
+| Flag | Environment | Default | |
+|---|---|---|---|
+| `--key <key>` | `ZAP_API_KEY` | | API key (stdio). Not used with `--http`. |
+| `--http` | | off | Serve Streamable HTTP at `/mcp` instead of stdio |
+| `--port <port>` | `ZAP_MCP_PORT` | `3000` | HTTP port |
+| `--host <host>` | `ZAP_MCP_HOST` | `127.0.0.1` | HTTP address |
+| `--toolsets <a,b>` | `ZAP_TOOLSETS` | the defaults below | Toolsets to expose, or `all` |
+| `--read-only` | `ZAP_READ_ONLY=1` | off | Only tools that change nothing |
+| `--sender <address>` | `ZAP_SENDER` | | From for sends that omit it; without one, sends require `from` |
+| `--reply-to <address>` | `ZAP_REPLY_TO` | | Reply-To for sends that omit it |
+| `--allowed-recipient-domains <a,b>` | `ZAP_ALLOWED_RECIPIENT_DOMAINS` | | Refuse sends to any other domain |
+| `--base-url <url>` | `ZAP_BASE_URL` | `https://api.zapsmtp.com/v1` | API base URL |
+| `--list-tools` | | | Print the tools these options expose, and exit |
+| `-h`, `--help` / `-v`, `--version` | | | |
+
+Flags win over the environment.
+
+## Toolsets
+
+The default toolsets give 76 tools; `--read-only` leaves 41 of them. Clients that slow down with many
+tools do best with just the toolsets they need: `--toolsets emails,simulator` is 14 tools.
+
+| Toolset | Default | Tools | |
+|---|---|---|---|
+| `emails` | yes | 12 | `emails_send`, `emails_send_batch`, `emails_list`, `emails_get`, `emails_update`, `emails_cancel`, `emails_get_content`, `emails_spam_check`, `emails_spam_check_sent`, `emails_attachments_list`, `emails_attachments_get`, `emails_share` |
+| `receiving` | yes | 8 | `emails_receiving_list`, `emails_receiving_get`, `emails_receiving_delete`, `emails_receiving_attachments_list`, `emails_receiving_attachments_get`, `emails_receiving_redeliver`, `emails_receiving_report_spam`, `emails_receiving_reply` |
+| `threads` | yes | 3 | `threads_list`, `threads_get`, `threads_update` |
+| `templates` | yes | 12 | `templates_list`, `templates_create`, `templates_get`, `templates_update`, `templates_delete`, `templates_render`, `templates_render_source`, `templates_publish`, `templates_duplicate`, `templates_versions_list`, `templates_versions_get`, `templates_versions_restore` |
+| `variables` | yes | 3 | `variables_list`, `variables_set_global`, `variables_delete_global` |
+| `domains` | yes | 11 | `domains_list`, `domains_create`, `domains_get`, `domains_update`, `domains_verify`, `domains_delete`, `domains_get_dmarc`, `domains_get_reputation`, `domains_check_reputation`, `domains_get_brand`, `domains_update_brand` |
+| `webhooks` | yes | 12 | `webhooks_list`, `webhooks_create`, `webhooks_get`, `webhooks_update`, `webhooks_delete`, `webhooks_test`, `webhooks_list_deliveries`, `webhooks_rotate_secret`, `webhooks_events_replay`, `webhooks_events_list`, `webhooks_events_get`, `verify_webhook_signature` |
+| `suppressions` | yes | 6 | `suppressions_list`, `suppressions_create`, `suppressions_delete`, `suppressions_get`, `suppressions_create_batch`, `suppressions_delete_batch` |
+| `logs` | yes | 2 | `logs_list`, `logs_get` |
+| `stats` | yes | 4 | `stats_get`, `stats_timeseries`, `stats_breakdown`, `stats_metrics` |
+| `usage` | yes | 1 | `usage_get` |
+| `simulator` | yes | 2 | `simulator_get`, `send_test_email` |
+| `inbound` | | 16 | inbound domains, routes and forward destinations |
+| `actions` | | 5 | click actions |
+| `template_modules` | | 5 | reusable template modules |
+| `template_assets` | | 3 | images hosted for templates |
+| `template_timers` | | 1 | countdown timer images |
+| `api_keys` | | 4 | create, update and revoke API keys |
+| `smtp_credentials` | | 3 | SMTP relay credentials |
+| `dedicated_ips` | | 1 | dedicated sending IPs |
+
+`zapsmtp-mcp --list-tools --toolsets all` prints every tool. Tool names follow the
+[Node.js SDK](https://www.npmjs.com/package/zapsmtp): `zap.templates.versions.get` is
+`templates_versions_get`.
+
+## What the tools do
+
+- **Arguments** are the API's parameters by their API names (`reply_to`, `scheduled_at`), path
+  parameters included (`templates_versions_get` takes `id` and `vid`). Unknown or missing arguments are
+  refused before anything is sent.
+- **Results** are the API's JSON. A list returns one page: `{data, has_more, next_cursor}`; pass
+  `next_cursor` back as `cursor` for the next page with the same filters. An operation without a body
+  returns `{"ok": true}`.
+- **Errors** are tool errors (`isError`) with `{"error": {status, code, type, message, request_id}}`,
+  so the model can correct itself; quote the `request_id` to support.
+- **Sends** (`emails_send`, `emails_send_batch`, `emails_receiving_reply`) take an `idempotency_key`; the
+  server makes one when it is omitted, so the SDK's automatic retries never send twice.
+- **`send_test_email`** sends to the simulator address of a scenario (`delivered`, `bounced`, `full`,
+  `blocked`, `delayed`, `complained`, `suppressed`, or any SMTP reply as `bounce+<code>…`) and returns
+  the email id with the event to expect.
+- **`verify_webhook_signature`** checks a webhook request's `Zap-Signature` against its raw body and
+  the endpoint's secret, locally, and returns its events (several for a batch webhook).
+
+Annotations: tools for `GET` requests, renders and spam checks are `readOnlyHint`. Deletes, cancelling a
+scheduled email, rotating a webhook secret, removing suppressions and restoring a template version are
+`destructiveHint`. Sends, test webhooks and replays are `openWorldHint`. Updates, deletes and
+verifications are `idempotentHint`.
+
+## Resources
+
+When the package was built with the docs site, `resources/list` offers
+`https://zapsmtp.com/llms.txt` (an index of the docs) and every guide as Markdown, for example
+`https://zapsmtp.com/docs/sending.md`. They are read from the package; nothing is fetched.
+
+## Safety
+
+- **The key stays out of the conversation.** It is read from the environment or a flag and sent only to
+  the API. Tool results and errors are scrubbed of it, and the server writes nothing about it to its
+  logs. Prefer the environment (or VS Code's `promptString` input) over `--key`, which shows in process
+  lists.
+- **Scope the key.** Give the agent a `zap_test_…` key while you try things, and a key restricted to
+  sending, one domain or one stream (`api_keys_create`) for production use.
+- **Limit what the agent can do**: `--read-only`, `--toolsets`, and
+  `--allowed-recipient-domains acme.com,example.org`, which refuses sends to any other domain (and its
+  subdomains) before any request is made. Under the allowlist, `emails_receiving_reply` must name its
+  recipients in `to` and cannot use `reply_all`, since the original sender's domain is unknown until
+  the API answers. `send_test_email` always sends to the simulator.
+- **Review before approving**: destructive tools are annotated, so clients that ask before running a tool
+  (Claude Code, Claude Desktop, VS Code, Cursor) show which calls change or delete things.
+- **HTTP**: loopback by default with `Host`/`Origin` checks; use HTTPS beyond your machine.
+
+## Embedding
+
+```ts
+import { API, buildTools, createServer, makeClient } from 'zapsmtp-mcp';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+const tools = buildTools(API, { toolsets: ['emails', 'simulator'], sender: 'hello@acme.com' });
+const server = createServer({ client: makeClient({ apiKey: process.env.ZAP_API_KEY! }), tools });
+await server.connect(new StdioServerTransport());
+```
+
+## Development
+
+```bash
+cd sdks/node && npm ci && npm run build   # the SDK this package uses
+cd ../mcp && npm ci
+npm run generate    # src/generated/ by sdks/codegen (emit/mcp.mjs); the build fails when it is stale
+npm test            # every tool against the conformance server, HTTP auth, safety options
+npm run coverage    # 100% of the hand-written code
+npm run build       # the codegen check, dist/, and docs/ from landing/zapsmtp-site/dist when it is built
+../live/run.sh mcp  # against the dev API
+```
+
+`src/generated/` is generated by `sdks/codegen` (`emit/mcp.mjs`; the code calling the SDK comes from
+`codegen/templates/tools-model.ts`, shared with the CLI); `src/catalog.ts` holds the hand-written choices (toolsets,
+annotations, descriptions).

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+// Entry point of the zapsmtp-mcp command.
+import { main } from './main.js';
+main(process.argv.slice(2), process.env, process).then((r) => {
+    if (typeof r === 'number') {
+        process.exitCode = r;
+        return;
+    }
+    const stop = () => { void r.close().then(() => process.exit(0)); };
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+}, (err) => {
+    process.stderr.write(`zapsmtp-mcp: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,0CAA0C;AAC1C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE;IAC3D,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC1B,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IACD,MAAM,IAAI,GAAG,GAAG,EAAE,GAAG,KAAK,CAAC,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACnE,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAC7B,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;AAChC,CAAC,EAAE,CAAC,GAAY,EAAE,EAAE;IAClB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,gBAAgB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC3F,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC"}

package/dist/catalog.d.ts

@@ -0,0 +1,30 @@
+import { type Operation } from './generated/model.js';
+export interface Toolset {
+    name: string;
+    description: string;
+    default: boolean;
+}
+/** Every toolset, in the order they are listed. A resource without one here gets its own (snake_case name). */
+export declare const TOOLSETS: Toolset[];
+export declare const DEFAULT_TOOLSETS: string[];
+/** The SDK method path of an operation, e.g. "emails.receiving.list". */
+export declare const sdkName: (op: Operation) => string;
+/** emails.receiving.attachments.list -> emails_receiving_attachments_list */
+export declare const toolName: (op: Operation) => string;
+/** Received emails get a toolset of their own; every other operation belongs to its top-level resource. */
+export declare const toolsetOf: (op: Operation) => string;
+export interface Annotations {
+    title: string;
+    readOnlyHint: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint: boolean;
+}
+export declare function annotations(op: Operation): Annotations;
+/** Operations whose recipients --allowed-recipient-domains checks, and the parameters that hold them. */
+export declare const RECIPIENT_PARAMS: Record<string, string[]>;
+/** Operations that take the default sender and Reply-To. */
+export declare const SENDS: Set<string>;
+/** The operation's documentation, cut at a sentence end when it is long. */
+export declare function describe(op: Operation): string;
+export declare function trim(s: string, max: number): string;

package/dist/catalog.js

@@ -0,0 +1,80 @@
+// The hand-written layer over the generated operations: tool names, toolsets,
+// annotations and descriptions. Everything here is a judgement call the API
+// model cannot make; the parameters themselves always come from the model.
+import { snake } from './generated/model.js';
+/** Every toolset, in the order they are listed. A resource without one here gets its own (snake_case name). */
+export const TOOLSETS = [
+    { name: 'emails', description: 'Send (one or a batch), list, get, reschedule, cancel, spam-check and share sent emails; their attachments', default: true },
+    { name: 'receiving', description: 'Received (inbound) emails: list, get, reply, report spam, redeliver, attachments, delete', default: true },
+    { name: 'threads', description: 'Conversations of sent and received emails', default: true },
+    { name: 'templates', description: 'Templates: create, update, render, publish, duplicate, versions', default: true },
+    { name: 'variables', description: 'Template variables and global variables', default: true },
+    { name: 'domains', description: 'Sending domains: DNS records, verification, tracking, DMARC reports, reputation, brand (BIMI)', default: true },
+    { name: 'webhooks', description: 'Webhook endpoints, test deliveries, delivery history, event replay, secret rotation, signature verification', default: true },
+    { name: 'suppressions', description: 'The suppression list: add, remove, look up', default: true },
+    { name: 'logs', description: 'API request logs', default: true },
+    { name: 'stats', description: 'Sending statistics, time series, breakdowns and metrics', default: true },
+    { name: 'usage', description: 'This month\'s usage and plan', default: true },
+    { name: 'simulator', description: 'Simulator addresses, and send_test_email to try any delivery outcome safely', default: true },
+    { name: 'inbound', description: 'Inbound domains, routes and forward destinations', default: false },
+    { name: 'actions', description: 'Click actions (named buttons and links)', default: false },
+    { name: 'template_modules', description: 'Reusable template modules', default: false },
+    { name: 'template_assets', description: 'Images hosted for templates', default: false },
+    { name: 'template_timers', description: 'Countdown timer images', default: false },
+    { name: 'api_keys', description: 'API keys: create, update, revoke', default: false },
+    { name: 'smtp_credentials', description: 'SMTP relay credentials', default: false },
+    { name: 'dedicated_ips', description: 'Dedicated sending IPs and their warm-up', default: false },
+];
+export const DEFAULT_TOOLSETS = TOOLSETS.filter((t) => t.default).map((t) => t.name);
+/** The SDK method path of an operation, e.g. "emails.receiving.list". */
+export const sdkName = (op) => [...op.resource, op.method].join('.');
+/** emails.receiving.attachments.list -> emails_receiving_attachments_list */
+export const toolName = (op) => [...op.resource, op.method].map(snake).join('_');
+/** Received emails get a toolset of their own; every other operation belongs to its top-level resource. */
+export const toolsetOf = (op) => op.resource[0] === 'emails' && op.resource[1] === 'receiving' ? 'receiving' : snake(op.resource[0]);
+/** POST operations that change nothing: they compute an answer. */
+const READ_ONLY_POSTS = new Set(['templates.render', 'templates.renderSource', 'emails.spamCheck', 'emails.spamCheckSent']);
+/** Operations that destroy or revoke something besides DELETE requests. */
+const DESTRUCTIVE = new Set(['emails.cancel', 'webhooks.rotateSecret', 'suppressions.deleteBatch', 'templates.versions.restore']);
+/** POST operations that end in the same state when repeated. */
+const IDEMPOTENT_POSTS = new Set([
+    'emails.cancel', 'domains.verify', 'inbound.domains.verify', 'domains.checkReputation', 'templates.publish',
+    'emails.receiving.reportSpam', 'suppressions.createBatch', 'suppressions.deleteBatch', 'templates.versions.restore',
+]);
+/** Operations that send email or call a URL outside ZapSMTP. */
+const OPEN_WORLD = new Set([
+    'emails.send', 'emails.sendBatch', 'emails.receiving.reply', 'inbound.forwardDestinations.create',
+    'inbound.forwardDestinations.resendConfirmation', 'webhooks.test', 'webhooks.events.replay', 'emails.receiving.redeliver',
+]);
+export function annotations(op) {
+    const name = sdkName(op);
+    const readOnly = op.httpMethod === 'GET' || READ_ONLY_POSTS.has(name);
+    const a = { title: op.title, readOnlyHint: readOnly, openWorldHint: OPEN_WORLD.has(name) };
+    if (!readOnly) {
+        a.destructiveHint = op.httpMethod === 'DELETE' || DESTRUCTIVE.has(name);
+        a.idempotentHint = op.httpMethod === 'PUT' || op.httpMethod === 'DELETE' || op.httpMethod === 'PATCH' || IDEMPOTENT_POSTS.has(name);
+    }
+    return a;
+}
+/** Operations whose recipients --allowed-recipient-domains checks, and the parameters that hold them. */
+export const RECIPIENT_PARAMS = {
+    'emails.send': ['to', 'cc', 'bcc'],
+    'emails.sendBatch': ['to', 'cc', 'bcc'],
+    'emails.receiving.reply': ['to', 'cc', 'bcc'],
+    'inbound.forwardDestinations.create': ['email'],
+};
+/** Operations that take the default sender and Reply-To. */
+export const SENDS = new Set(['emails.send', 'emails.sendBatch']);
+const MAX_DESCRIPTION = 900;
+/** The operation's documentation, cut at a sentence end when it is long. */
+export function describe(op) {
+    return trim(op.doc, MAX_DESCRIPTION);
+}
+export function trim(s, max) {
+    if (s.length <= max)
+        return s;
+    const cut = s.slice(0, max);
+    const end = Math.max(cut.lastIndexOf('. '), cut.lastIndexOf('.\n'));
+    return end > max / 2 ? cut.slice(0, end + 1) : cut.slice(0, cut.lastIndexOf(' ')) + ' …';
+}
+//# sourceMappingURL=catalog.js.map

package/dist/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"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"}

package/dist/docs.d.ts

@@ -0,0 +1,13 @@
+export interface DocPage {
+    uri: string;
+    name: string;
+    title: string;
+    description: string;
+    /** the file in the docs directory */
+    file: string;
+}
+/** Where the build puts the docs: <package>/docs. */
+export declare const DOCS_DIR: string;
+/** The bundled pages; none when the package was built without them. */
+export declare function loadDocs(dir?: string): DocPage[];
+export declare function readDoc(dir: string, page: DocPage): string;

package/dist/docs.js

@@ -0,0 +1,22 @@
+// The ZapSMTP docs as MCP resources: llms.txt and the guides in Markdown,
+// bundled into the package at build time (scripts/bundle-docs.mjs). Nothing
+// is fetched at runtime.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Where the build puts the docs: <package>/docs. */
+export const DOCS_DIR = fileURLToPath(new URL('../docs/', import.meta.url));
+/** The bundled pages; none when the package was built without them. */
+export function loadDocs(dir = DOCS_DIR) {
+    try {
+        const pages = JSON.parse(readFileSync(join(dir, 'index.json'), 'utf8'));
+        return Array.isArray(pages) ? pages : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function readDoc(dir, page) {
+    return readFileSync(join(dir, page.file), 'utf8');
+}
+//# sourceMappingURL=docs.js.map

package/dist/docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.js","sourceRoot":"","sources":["../src/docs.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,4EAA4E;AAC5E,yBAAyB;AACzB,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAWzC,qDAAqD;AACrD,MAAM,CAAC,MAAM,QAAQ,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE5E,uEAAuE;AACvE,MAAM,UAAU,QAAQ,CAAC,MAAc,QAAQ;IAC7C,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,EAAE,MAAM,CAAC,CAAc,CAAC;QACrF,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,GAAW,EAAE,IAAa;IAChD,OAAO,YAAY,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;AACpD,CAAC"}

package/dist/generated/api.d.ts

@@ -0,0 +1,2 @@
+import type { Api } from './model.js';
+export declare const API: Api;