@mailpace/mcp 0.0.0-stage → 2.0.0

package/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright © 2025 OhMySMTP Ltd
+
+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,179 @@
-# Temporary Holding Version
+# MailPace MCP (Model Context Protocol) 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.
+MailPace MCP Server exposes the [MailPace](https://mailpace.com) transactional email, domain management, and email status APIs to MCP clients.
+
+## Features
+
+- Send transactional email with the [Send API](https://docs.mailpace.com/reference/send)
+- List, create, update, and verify domains with the [Domains API](https://docs.mailpace.com/reference/domains)
+- Manage domain API tokens
+- Check delivery, bounce, and deferral status with the [Email Status API](https://docs.mailpace.com/reference/email-status)
+- Optional recipient allowlist and idempotent sends
+- Tools expose structured output schemas and MCP behavior annotations
+
+## Requirements
+
+- Node.js 20 or newer
+- A MailPace organization and domain
+- A **domain API token** to send email and check email status for that domain
+- An **organization API token** to manage domains and domain API tokens
+
+## Configuration
+
+Credentials are read from environment variables only. They are never accepted as command-line arguments, which would expose them in process listings.
+
+| Variable | Required | Description |
+| --- | --- | --- |
+| `MAILPACE_API_TOKEN` | For sending and domain-scoped status | Domain API token |
+| `MAILPACE_ORGANIZATION_TOKEN` | For domain management | Organization API token |
+| `MAILPACE_ALLOWED_RECIPIENTS` | No | Comma-separated allowlist of exact addresses or `@domain` rules. When set, `mailpace_send_email` refuses other recipients. |
+| `MAILPACE_API_URL` | No | Override the API base URL. Must be HTTPS except for localhost development. |
+| `MAILPACE_REQUEST_TIMEOUT_MS` | No | Per-request timeout in milliseconds. Default `30000`. |
+| `MAILPACE_MAX_RETRIES` | No | Retries for idempotent requests and 429 responses. Default `2`. |
+
+At least one of `MAILPACE_API_TOKEN` or `MAILPACE_ORGANIZATION_TOKEN` is required. Tools are registered according to the available credentials.
+
+## Tools
+
+| Tool | Credential | Description |
+| --- | --- | --- |
+| `mailpace_send_email` | Domain token | Send an email. Supports attachments, tags, and `Idempotency-Key`. |
+| `mailpace_get_email_status` | Domain or organization token | Get delivery, bounce, or deferral status by domain and email ID. |
+| `mailpace_list_domains` | Organization token | List domains with pagination and sorting. |
+| `mailpace_get_domain` | Organization token | Get a domain by ID. |
+| `mailpace_create_domain` | Organization token | Create a sending domain. |
+| `mailpace_update_domain` | Organization token | Update a domain's name or URL. |
+| `mailpace_verify_domain` | Organization token | Check DKIM and advanced verification DNS records. |
+| `mailpace_list_domain_api_tokens` | Organization token | List a domain's API tokens. |
+| `mailpace_get_domain_api_token` | Organization token | Get one domain API token. |
+| `mailpace_create_domain_api_token` | Organization token | Create a domain API token. Store the returned token securely. |
+| `mailpace_update_domain_api_token` | Organization token | Rename a domain API token. |
+| `mailpace_revoke_domain_api_token` | Organization token | Revoke a domain API token. This cannot be undone. |
+
+### Sending email safely
+
+`mailpace_send_email` is an external side effect. Clients and hosts should confirm recipients before invoking it. For automation, set `MAILPACE_ALLOWED_RECIPIENTS` to reduce the impact of mistakes or prompt injection, for example:
+
+```bash
+MAILPACE_ALLOWED_RECIPIENTS="hello@example.com,@yourcompany.com"
+```
+
+Use an `idempotency_key` when retrying a send to prevent duplicate email delivery.
+
+## Client configuration
+
+After building locally, point your MCP client at the built entry point:
+
+```json
+{
+  "mcpServers": {
+    "mailpace": {
+      "command": "node",
+      "args": ["/absolute/path/to/mailpace-mcp/build/index.js"],
+      "env": {
+        "MAILPACE_API_TOKEN": "your-domain-api-token",
+        "MAILPACE_ORGANIZATION_TOKEN": "your-organization-api-token"
+      }
+    }
+  }
+}
+```
+
+Once published, this can also be run with `npx -y @mailpace/mcp`.
+
+## Build and run
+
+```bash
+npm ci
+npm run build
+npm start
+```
+
+Development uses `tsx` and TypeScript source directly:
+
+```bash
+npm run dev
+```
+
+## Testing
+
+```bash
+npm test
+```
+
+The integration tests start the built server, connect over stdio, and exercise tool registration, request shapes, validation, error mapping, retries, and timeouts against a local mock MailPace API.
+
+## Docker
+
+```bash
+docker build -t mailpace-mcp .
+docker run --rm -i \
+  -e MAILPACE_API_TOKEN=your-domain-api-token \
+  -e MAILPACE_ORGANIZATION_TOKEN=your-organization-api-token \
+  mailpace-mcp
+```
+
+The image runs as the non-root `node` user and installs only production dependencies.
+
+## Publishing
+
+The package is published as `@mailpace/mcp` on npm and registered with the [Official MCP Registry](https://registry.modelcontextprotocol.io) as:
+
+```text
+com.mailpace/mailpace-mcp
+```
+
+`package.json` contains the matching `mcpName` field, and `server.json` contains the registry metadata.
+
+### One-time setup
+
+1. Create an npm automation token with publish access and add it as the `NPM_TOKEN` repository secret.
+2. Generate an Ed25519 key pair for DNS authentication:
+
+   ```bash
+   openssl genpkey -algorithm Ed25519 -out key.pem
+   PUBLIC_KEY="$(openssl pkey -in key.pem -pubout -outform DER | tail -c 32 | base64)"
+   echo "mailpace.com. IN TXT \"v=MCPv1; k=ed25519; p=${PUBLIC_KEY}\""
+   ```
+
+3. Add the printed TXT record to `mailpace.com` DNS.
+4. Add the private key as the `MCP_PRIVATE_KEY` repository secret:
+
+   ```bash
+   openssl pkey -in key.pem -noout -text | grep -A3 "priv:" | tail -n +2 | tr -d ' :\n'
+   ```
+
+   Do not commit `key.pem`; it is gitignored.
+
+### Releasing
+
+Update `package.json` and `server.json` to the new version, commit, then push a matching tag:
+
+```bash
+git tag v2.0.0
+git push origin v2.0.0
+```
+
+The `Release` workflow runs typechecking and tests, verifies the tag matches `package.json`, publishes to npm, waits for the package to appear, and publishes the version metadata to the Official MCP Registry.
+
+## Security
+
+- Tokens are read from the environment only.
+- Use a domain token for sending and an organization token only when domain management is needed.
+- Keep `MAILPACE_ALLOWED_RECIPIENTS` set in unattended deployments.
+- Revoke unused domain API tokens from the MailPace dashboard.
+
+## Contributing
+
+1. Fork the repository.
+2. Create a new branch for your feature or bugfix.
+3. Commit your changes and push the branch to your fork.
+4. Create a pull request with a detailed description of your changes.
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE.md) file for details.
+
+## Contact
+
+For any questions or support, please contact us at support@mailpace.com.

package/build/index.js

@@ -0,0 +1,800 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/server";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import { createRequire } from "node:module";
+import * as z from "zod/v4";
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
+const apiToken = process.env.MAILPACE_API_TOKEN;
+const organizationToken = process.env.MAILPACE_ORGANIZATION_TOKEN;
+if (!apiToken && !organizationToken) {
+    console.error("No API token provided. Set MAILPACE_API_TOKEN (to send email) and/or " +
+        "MAILPACE_ORGANIZATION_TOKEN (to manage domains).");
+    process.exit(1);
+}
+function normalizeApiBaseUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`Invalid MAILPACE_API_URL: ${value}`);
+    }
+    const isLocalhost = url.hostname === "localhost" ||
+        url.hostname === "127.0.0.1" ||
+        url.hostname === "::1" ||
+        url.hostname === "[::1]";
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && isLocalhost)) {
+        throw new Error("MAILPACE_API_URL must use HTTPS, except for localhost development URLs");
+    }
+    return `${url.origin}${url.pathname}`.replace(/\/+$/, "");
+}
+let API_BASE_URL;
+try {
+    API_BASE_URL = normalizeApiBaseUrl(process.env.MAILPACE_API_URL || "https://app.mailpace.com/api/v1");
+}
+catch (error) {
+    console.error(error.message);
+    process.exit(1);
+}
+function readIntegerEnv(name, fallback, minimum) {
+    const raw = process.env[name];
+    if (raw === undefined || raw === "") {
+        return fallback;
+    }
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < minimum) {
+        console.error(`${name} must be an integer greater than or equal to ${minimum}`);
+        process.exit(1);
+    }
+    return value;
+}
+const REQUEST_TIMEOUT_MS = readIntegerEnv("MAILPACE_REQUEST_TIMEOUT_MS", 30_000, 1);
+const MAX_RETRIES = readIntegerEnv("MAILPACE_MAX_RETRIES", 2, 0);
+const server = new McpServer({
+    name: "mailpace",
+    version,
+}, {
+    instructions: "MailPace provides transactional email sending and domain management. " +
+        "MAILPACE_API_TOKEN enables mailpace_send_email and mailpace_get_email_status for one domain. " +
+        "MAILPACE_ORGANIZATION_TOKEN enables domain and domain API token management, plus mailpace_get_email_status for any domain. " +
+        "Sending email is an external side effect; confirm recipients before calling mailpace_send_email.",
+    maxToolInputElements: 10_000,
+});
+const domainSchema = z
+    .object({
+    id: z.number().int(),
+    name: z.string().nullable().optional(),
+    url: z.string(),
+    dkim_selector: z.string().nullable().optional(),
+    dkim_string: z.string().nullable().optional(),
+    dkim_verified: z.boolean(),
+    advanced_verified: z.boolean(),
+    webhook_public_key: z.string().nullable().optional(),
+    created_at: z.string(),
+    modified_at: z.string(),
+})
+    .passthrough();
+const domainListSchema = z.object({
+    domains: z.array(domainSchema),
+});
+const verifyDomainSchema = z
+    .object({
+    dkim_verified: z.boolean(),
+    advance_verified: z.boolean(),
+    errors: z.record(z.string(), z.unknown()).optional(),
+})
+    .passthrough();
+const apiTokenSchema = z
+    .object({
+    id: z.number().int().optional(),
+    domain_id: z.number().int().optional(),
+    name: z.string().nullable().optional(),
+    token: z.string().optional(),
+    created_at: z.string().optional(),
+    modified_at: z.string().optional(),
+})
+    .passthrough();
+const apiTokenListSchema = z.object({
+    api_tokens: z.array(apiTokenSchema),
+});
+const messageSchema = z
+    .object({
+    message: z.string().optional(),
+})
+    .passthrough();
+const emailStatusSchema = z
+    .object({
+    id: z.number().int(),
+    domain_id: z.number().int(),
+    status: z.string(),
+    message_id: z.string().nullable().optional(),
+    from: z.string().optional(),
+    to: z.string().optional(),
+    cc: z.string().nullable().optional(),
+    bcc: z.string().nullable().optional(),
+    subject: z.string().nullable().optional(),
+    replyto: z.string().nullable().optional(),
+    inreplyto: z.string().nullable().optional(),
+    references: z.string().nullable().optional(),
+    list_unsubscribe: z.string().nullable().optional(),
+    tags: z.array(z.string()).optional(),
+    bounce_reason: z.string().nullable().optional(),
+    bounce: z.record(z.string(), z.unknown()).nullable().optional(),
+    deferred: z.record(z.string(), z.unknown()).nullable().optional(),
+    created_at: z.string().optional(),
+    modified_at: z.string().optional(),
+})
+    .passthrough();
+const sendEmailSchema = z.object({
+    id: z.number().int(),
+    status: z.string(),
+});
+const EMAIL_ADDRESS_RE = /^[^\s@<>]+@[^\s@<>]+\.[^\s@<>]+$/;
+const ATTACHMENT_EXTENSIONS = new Set([
+    "jpeg",
+    "jpg",
+    "png",
+    "gif",
+    "txt",
+    "pdf",
+    "docx",
+    "xlsx",
+    "pptx",
+    "csv",
+    "att",
+    "ics",
+    "ical",
+    "html",
+    "zip",
+    "auf",
+    "xml",
+    "dwg",
+]);
+const MAX_RECIPIENTS = 50;
+const MAX_ATTACHMENT_BYTES = 30 * 1024 * 1024;
+const ALLOWED_RECIPIENTS = (process.env.MAILPACE_ALLOWED_RECIPIENTS || "")
+    .split(",")
+    .map((entry) => entry.trim().toLowerCase())
+    .filter(Boolean);
+function bareAddress(value) {
+    const trimmed = value.trim();
+    const angleMatch = trimmed.match(/^.*<([^<>]+)>$/);
+    return (angleMatch ? angleMatch[1] : trimmed).trim();
+}
+function isRecipientAllowed(value) {
+    if (ALLOWED_RECIPIENTS.length === 0) {
+        return true;
+    }
+    const address = bareAddress(value).toLowerCase();
+    return ALLOWED_RECIPIENTS.some((rule) => rule.startsWith("@") ? address.endsWith(rule) : address === rule);
+}
+function splitAddressList(value) {
+    const parts = [];
+    let current = "";
+    let inQuotes = false;
+    let angleDepth = 0;
+    for (const char of value) {
+        if (char === '"') {
+            inQuotes = !inQuotes;
+        }
+        else if (char === "<" && !inQuotes) {
+            angleDepth += 1;
+        }
+        else if (char === ">" && !inQuotes) {
+            angleDepth = Math.max(0, angleDepth - 1);
+        }
+        if (char === "," && !inQuotes && angleDepth === 0) {
+            parts.push(current);
+            current = "";
+        }
+        else {
+            current += char;
+        }
+    }
+    parts.push(current);
+    return parts.map((part) => part.trim()).filter(Boolean);
+}
+function isValidAddress(value) {
+    const trimmed = value.trim();
+    const angleMatch = trimmed.match(/^.*<([^<>]+)>$/);
+    const address = (angleMatch ? angleMatch[1] : trimmed).trim();
+    return EMAIL_ADDRESS_RE.test(address);
+}
+const emailAddressSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .refine(isValidAddress, {
+    message: "Must be an email address or an RFC 822 name & addr-spec, for example 'Name <user@example.com>'",
+});
+const emailListSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .refine((value) => {
+    const addresses = splitAddressList(value);
+    return addresses.length > 0 && addresses.every(isValidAddress);
+}, {
+    message: "Must be a comma-separated list of email addresses or RFC 822 name & addr-spec entries",
+});
+const attachmentSchema = z.object({
+    name: z
+        .string()
+        .min(1)
+        .refine((name) => {
+        const parts = name.split(".");
+        return (parts.length === 2 &&
+            ATTACHMENT_EXTENSIONS.has(parts[1].toLowerCase()));
+    }, {
+        message: "File names must have exactly one full stop and use a supported extension",
+    })
+        .describe("File name including extension, for example invoice.pdf. Must contain exactly one full stop."),
+    content: z.string().min(1).describe("Base64-encoded file contents"),
+    content_type: z
+        .string()
+        .min(1)
+        .describe("MIME type, for example application/pdf"),
+    cid: z
+        .string()
+        .optional()
+        .describe("Optional content ID for inline images"),
+});
+const sendEmailInputSchema = z
+    .object({
+    from: emailAddressSchema.describe("Sender email address or RFC 822 name & addr-spec, for example 'Name <user@example.com>'. The domain must match the API token."),
+    to: emailListSchema.describe("Recipient address or comma-separated list of recipients (maximum 50 total including cc and bcc)"),
+    subject: z.string().optional().describe("Email subject"),
+    htmlbody: z
+        .string()
+        .optional()
+        .describe("HTML body. Required if textbody is not provided."),
+    textbody: z
+        .string()
+        .optional()
+        .describe("Plain-text body. Required if htmlbody is not provided."),
+    cc: emailListSchema
+        .optional()
+        .describe("Optional comma-separated CC recipients"),
+    bcc: emailListSchema
+        .optional()
+        .describe("Optional comma-separated BCC recipients"),
+    replyto: emailAddressSchema
+        .optional()
+        .describe("Optional Reply-To address"),
+    inreplyto: z
+        .string()
+        .optional()
+        .describe("Optional In-Reply-To message ID"),
+    references: z
+        .string()
+        .optional()
+        .describe("Optional space-separated References message IDs"),
+    list_unsubscribe: z
+        .string()
+        .optional()
+        .describe("Optional List-Unsubscribe header value"),
+    attachments: z
+        .array(attachmentSchema)
+        .optional()
+        .describe("Optional attachments. Total email size must not exceed 30 MB."),
+    tags: z
+        .union([z.string(), z.array(z.string())])
+        .optional()
+        .describe("Optional tag or list of tags for filtering and analytics"),
+    idempotency_key: z
+        .string()
+        .min(1)
+        .max(255)
+        .optional()
+        .describe("Optional unique key (for example a UUIDv4) that prevents sending the same email twice when retrying"),
+})
+    .superRefine((value, ctx) => {
+    if (!value.textbody && !value.htmlbody) {
+        ctx.addIssue({
+            code: "custom",
+            message: "Either textbody or htmlbody must be provided",
+            path: ["textbody"],
+        });
+    }
+    const recipients = [value.to, value.cc, value.bcc]
+        .filter((address) => Boolean(address))
+        .flatMap(splitAddressList);
+    if (recipients.length > MAX_RECIPIENTS) {
+        ctx.addIssue({
+            code: "custom",
+            message: `A maximum of ${MAX_RECIPIENTS} recipients is allowed`,
+            path: ["to"],
+        });
+    }
+    const attachmentBytes = (value.attachments ?? []).reduce((total, attachment) => total + Math.ceil((attachment.content.length * 3) / 4), 0);
+    if (attachmentBytes > MAX_ATTACHMENT_BYTES) {
+        ctx.addIssue({
+            code: "custom",
+            message: "Attachments must not exceed 30 MB in total",
+            path: ["attachments"],
+        });
+    }
+});
+const MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
+const MAX_ERROR_DETAIL_LENGTH = 1000;
+function jsonResult(data) {
+    const isObject = data !== null && typeof data === "object" && !Array.isArray(data);
+    return {
+        content: [{ type: "text", text: JSON.stringify(data) }],
+        ...(isObject
+            ? { structuredContent: data }
+            : {}),
+    };
+}
+function errorResult(message) {
+    return {
+        content: [{ type: "text", text: message }],
+        isError: true,
+    };
+}
+function truncate(text, maxLength = MAX_ERROR_DETAIL_LENGTH) {
+    if (text.length <= maxLength) {
+        return text;
+    }
+    return `${text.slice(0, maxLength)}…`;
+}
+function describeRequestFailure(error, options) {
+    if (options.signal?.aborted) {
+        return "MailPace API request cancelled";
+    }
+    if (error?.name === "TimeoutError" || error?.name === "AbortError") {
+        return `MailPace API request timed out after ${REQUEST_TIMEOUT_MS}ms`;
+    }
+    return null;
+}
+function formatApiError(status, statusText, detail, tokenHeader) {
+    const safeDetail = truncate(detail.trim() || "Unknown error");
+    const tokenName = tokenHeader === "MailPace-Organization-Token"
+        ? "organization API token"
+        : "domain server token";
+    switch (status) {
+        case 401:
+            return `MailPace authentication failed (401). Check that the ${tokenName} is valid and has not been revoked. ${safeDetail}`;
+        case 403:
+            return `MailPace denied the request (403). The ${tokenName} may not have access to this resource. ${safeDetail}`;
+        case 404:
+            return `MailPace resource not found (404). Check the domain, email, or token ID. ${safeDetail}`;
+        case 422:
+            return `MailPace rejected the request (422): ${safeDetail}`;
+        case 429:
+            return `MailPace rate limit exceeded (429). Retry later. ${safeDetail}`;
+        default:
+            return `MailPace API request failed (${status} ${statusText}): ${safeDetail}`;
+    }
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new Error("MailPace API request cancelled"));
+            return;
+        }
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener("abort", () => {
+            clearTimeout(timer);
+            reject(new Error("MailPace API request cancelled"));
+        }, { once: true });
+    });
+}
+function retryDelayMs(attempt, response) {
+    const retryAfter = response?.headers.get("retry-after");
+    if (retryAfter) {
+        const seconds = Number(retryAfter);
+        if (Number.isFinite(seconds)) {
+            return Math.max(0, seconds * 1000);
+        }
+        const date = Date.parse(retryAfter);
+        if (!Number.isNaN(date)) {
+            return Math.max(0, date - Date.now());
+        }
+    }
+    return Math.min(1000 * 2 ** attempt, 10_000);
+}
+async function apiRequest(path, options) {
+    const url = `${API_BASE_URL}${path}`;
+    const method = options.method || "GET";
+    const body = options.body === undefined ? undefined : JSON.stringify(options.body);
+    const isIdempotent = ["GET", "HEAD", "PATCH", "DELETE"].includes(method) ||
+        Boolean(options.headers?.["Idempotency-Key"]);
+    for (let attempt = 0;; attempt += 1) {
+        const timeoutSignal = AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+        const signal = options.signal
+            ? AbortSignal.any([options.signal, timeoutSignal])
+            : timeoutSignal;
+        let response;
+        try {
+            response = await fetch(url, {
+                method,
+                headers: {
+                    Accept: "application/json",
+                    "Content-Type": "application/json",
+                    [options.tokenHeader]: options.token,
+                    ...options.headers,
+                },
+                body,
+                signal,
+            });
+        }
+        catch (error) {
+            const failure = describeRequestFailure(error, options);
+            if (failure) {
+                throw new Error(failure);
+            }
+            const cause = error?.cause?.message ? `: ${error.cause.message}` : "";
+            const message = `${error?.message || "Network request failed"}${cause}`;
+            if (isIdempotent && attempt < MAX_RETRIES) {
+                await sleep(retryDelayMs(attempt), options.signal);
+                continue;
+            }
+            throw new Error(`MailPace API request failed: ${message}`);
+        }
+        const contentLength = Number(response.headers.get("content-length"));
+        if (Number.isFinite(contentLength) &&
+            contentLength > MAX_RESPONSE_BYTES) {
+            throw new Error(`MailPace API response exceeded the ${MAX_RESPONSE_BYTES} byte limit`);
+        }
+        let responseText;
+        try {
+            responseText = await response.text();
+        }
+        catch (error) {
+            const failure = describeRequestFailure(error, options);
+            if (failure) {
+                throw new Error(failure);
+            }
+            throw new Error(`MailPace API response could not be read: ${error?.message || error}`);
+        }
+        if (responseText.length > MAX_RESPONSE_BYTES) {
+            throw new Error(`MailPace API response exceeded the ${MAX_RESPONSE_BYTES} byte limit`);
+        }
+        let data = null;
+        if (responseText) {
+            try {
+                data = JSON.parse(responseText);
+            }
+            catch {
+                data = responseText;
+            }
+        }
+        if (response.ok) {
+            return data;
+        }
+        if ((response.status === 429 || response.status >= 500) &&
+            attempt < MAX_RETRIES &&
+            (isIdempotent || response.status === 429)) {
+            await sleep(retryDelayMs(attempt, response), options.signal);
+            continue;
+        }
+        let detail = responseText;
+        if (data && typeof data === "object") {
+            const errorData = data;
+            detail = String(errorData.error || errorData.message || JSON.stringify(data));
+        }
+        throw new Error(formatApiError(response.status, response.statusText, detail, options.tokenHeader));
+    }
+}
+function organizationRequest(path, options = {}) {
+    return apiRequest(path, {
+        ...options,
+        token: organizationToken,
+        tokenHeader: "MailPace-Organization-Token",
+    });
+}
+function serverRequest(path, options = {}) {
+    return apiRequest(path, {
+        ...options,
+        token: apiToken,
+        tokenHeader: "MailPace-Server-Token",
+    });
+}
+async function runApiTool(operation, label = "MailPace API") {
+    try {
+        return jsonResult(await operation());
+    }
+    catch (error) {
+        console.error(`${label} error: ${error.message}`);
+        return errorResult(error.message || String(error));
+    }
+}
+function runOrganizationTool(operation) {
+    return runApiTool(operation, "MailPace Domains API");
+}
+// Define the email tool
+if (apiToken) {
+    server.registerTool("mailpace_send_email", {
+        title: "Send Email",
+        description: "Send a transactional email through MailPace. Requires a domain API token.",
+        inputSchema: sendEmailInputSchema,
+        outputSchema: sendEmailSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async ({ idempotency_key, ...email }, ctx) => {
+        try {
+            const disallowedRecipient = [email.to, email.cc, email.bcc]
+                .filter((address) => Boolean(address))
+                .flatMap(splitAddressList)
+                .find((address) => !isRecipientAllowed(address));
+            if (disallowedRecipient) {
+                return errorResult(`Recipient ${bareAddress(disallowedRecipient)} is not permitted by MAILPACE_ALLOWED_RECIPIENTS`);
+            }
+            const result = (await serverRequest("/send", {
+                method: "POST",
+                body: email,
+                headers: idempotency_key
+                    ? { "Idempotency-Key": idempotency_key }
+                    : undefined,
+                signal: ctx.mcpReq.signal,
+            }));
+            return jsonResult({ id: result.id, status: result.status });
+        }
+        catch (error) {
+            console.error(`Error sending email: ${error.message}`);
+            return errorResult(error.message || String(error));
+        }
+    });
+}
+// Email status can be read with either an organization token or the
+// domain's server token.
+if (apiToken || organizationToken) {
+    server.registerTool("mailpace_get_email_status", {
+        title: "Get Email Status",
+        description: "Get the delivery status of an email, including bounce or deferral details.",
+        inputSchema: z.object({
+            domain_id: z
+                .number()
+                .int()
+                .describe("ID of the domain the email was sent from"),
+            id: z
+                .number()
+                .int()
+                .describe("Email ID returned by mailpace_send_email"),
+        }),
+        outputSchema: emailStatusSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ domain_id, id }, ctx) => runApiTool(() => organizationToken
+        ? organizationRequest(`/domains/${domain_id}/emails/${id}`, {
+            signal: ctx.mcpReq.signal,
+        })
+        : serverRequest(`/domains/${domain_id}/emails/${id}`, {
+            signal: ctx.mcpReq.signal,
+        }), "MailPace Email Status API"));
+}
+// Domains API tools. These require an Organization API token.
+if (organizationToken) {
+    server.registerTool("mailpace_list_domains", {
+        title: "List Domains",
+        description: "List the domains belonging to your MailPace organization.",
+        inputSchema: z.object({
+            limit: z.number().int().min(1).max(200).optional(),
+            offset: z.number().int().min(0).optional(),
+            sort: z.enum(["created_at", "id", "name"]).optional(),
+            direction: z.enum(["asc", "desc"]).optional(),
+        }),
+        outputSchema: domainListSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ limit, offset, sort, direction }, ctx) => {
+        const params = new URLSearchParams();
+        if (limit !== undefined)
+            params.set("limit", String(limit));
+        if (offset !== undefined)
+            params.set("offset", String(offset));
+        if (sort !== undefined)
+            params.set("sort", sort);
+        if (direction !== undefined)
+            params.set("direction", direction);
+        const query = params.toString();
+        return runOrganizationTool(async () => ({
+            domains: await organizationRequest(`/domains${query ? `?${query}` : ""}`, { signal: ctx.mcpReq.signal }),
+        }));
+    });
+    server.registerTool("mailpace_get_domain", {
+        title: "Get Domain",
+        description: "Get a single MailPace domain by ID.",
+        inputSchema: z.object({
+            id: z.number().int().describe("The domain ID"),
+        }),
+        outputSchema: domainSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ id }, ctx) => runOrganizationTool(() => organizationRequest(`/domains/${id}`, { signal: ctx.mcpReq.signal })));
+    server.registerTool("mailpace_create_domain", {
+        title: "Create Domain",
+        description: "Create a new sending domain in your MailPace organization.",
+        inputSchema: z.object({
+            url: z
+                .string()
+                .describe("Lower-case domain with TLD, for example example.com"),
+            name: z.string().optional().describe("Friendly name for your reference"),
+        }),
+        outputSchema: domainSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async ({ url, name }, ctx) => runOrganizationTool(() => organizationRequest("/domains", {
+        method: "POST",
+        body: { domain: { url, ...(name !== undefined ? { name } : {}) } },
+        signal: ctx.mcpReq.signal,
+    })));
+    server.registerTool("mailpace_update_domain", {
+        title: "Update Domain",
+        description: "Update the name or URL of a MailPace domain. Changing the URL may require DNS verification again.",
+        inputSchema: z.object({
+            id: z.number().int().describe("The domain ID"),
+            name: z.string().optional().describe("Friendly name for your reference"),
+            url: z
+                .string()
+                .optional()
+                .describe("Lower-case domain with TLD, for example example.com"),
+        }),
+        outputSchema: domainSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ id, name, url }, ctx) => {
+        if (name === undefined && url === undefined) {
+            return errorResult("Provide at least one of name or url to update");
+        }
+        return runOrganizationTool(() => organizationRequest(`/domains/${id}`, {
+            method: "PATCH",
+            body: {
+                domain: {
+                    ...(name !== undefined ? { name } : {}),
+                    ...(url !== undefined ? { url } : {}),
+                },
+            },
+            signal: ctx.mcpReq.signal,
+        }));
+    });
+    server.registerTool("mailpace_verify_domain", {
+        title: "Verify Domain",
+        description: "Check the DKIM and advanced verification DNS records for a MailPace domain.",
+        inputSchema: z.object({
+            id: z.number().int().describe("The domain ID"),
+        }),
+        outputSchema: verifyDomainSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ id }, ctx) => runOrganizationTool(() => organizationRequest(`/domains/${id}/verify`, {
+        method: "POST",
+        signal: ctx.mcpReq.signal,
+    })));
+    server.registerTool("mailpace_list_domain_api_tokens", {
+        title: "List Domain API Tokens",
+        description: "List the API tokens for a MailPace domain.",
+        inputSchema: z.object({
+            domain_id: z.number().int().describe("The domain ID"),
+        }),
+        outputSchema: apiTokenListSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ domain_id }, ctx) => runOrganizationTool(async () => ({
+        api_tokens: await organizationRequest(`/domains/${domain_id}/api_tokens`, { signal: ctx.mcpReq.signal }),
+    })));
+    server.registerTool("mailpace_get_domain_api_token", {
+        title: "Get Domain API Token",
+        description: "Get a single API token for a MailPace domain.",
+        inputSchema: z.object({
+            domain_id: z.number().int().describe("The domain ID"),
+            id: z.number().int().describe("The API token ID"),
+        }),
+        outputSchema: apiTokenSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ domain_id, id }, ctx) => runOrganizationTool(() => organizationRequest(`/domains/${domain_id}/api_tokens/${id}`, {
+        signal: ctx.mcpReq.signal,
+    })));
+    server.registerTool("mailpace_create_domain_api_token", {
+        title: "Create Domain API Token",
+        description: "Create a new API token for a MailPace domain. Store the returned token securely; it may not be shown again.",
+        inputSchema: z.object({
+            domain_id: z.number().int().describe("The domain ID"),
+            name: z.string().optional().describe("Friendly token label"),
+        }),
+        outputSchema: apiTokenSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async ({ domain_id, name }, ctx) => runOrganizationTool(() => organizationRequest(`/domains/${domain_id}/api_tokens`, {
+        method: "POST",
+        body: { api_token: { ...(name !== undefined ? { name } : {}) } },
+        signal: ctx.mcpReq.signal,
+    })));
+    server.registerTool("mailpace_update_domain_api_token", {
+        title: "Update Domain API Token",
+        description: "Update the name of an API token for a MailPace domain.",
+        inputSchema: z.object({
+            domain_id: z.number().int().describe("The domain ID"),
+            id: z.number().int().describe("The API token ID"),
+            name: z.string().optional().describe("Friendly token label"),
+        }),
+        outputSchema: apiTokenSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ domain_id, id, name }, ctx) => {
+        if (name === undefined) {
+            return errorResult("Provide a name to update the API token");
+        }
+        return runOrganizationTool(() => organizationRequest(`/domains/${domain_id}/api_tokens/${id}`, {
+            method: "PATCH",
+            body: { api_token: { name } },
+            signal: ctx.mcpReq.signal,
+        }));
+    });
+    server.registerTool("mailpace_revoke_domain_api_token", {
+        title: "Revoke Domain API Token",
+        description: "Revoke an API token for a MailPace domain. This cannot be undone.",
+        inputSchema: z.object({
+            domain_id: z.number().int().describe("The domain ID"),
+            id: z.number().int().describe("The API token ID"),
+        }),
+        outputSchema: messageSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ domain_id, id }, ctx) => runOrganizationTool(() => organizationRequest(`/domains/${domain_id}/api_tokens/${id}`, {
+        method: "DELETE",
+        signal: ctx.mcpReq.signal,
+    })));
+}
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`MailPace MCP Server running on stdio (email sending: ${apiToken ? "enabled" : "disabled"}, domain management: ${organizationToken ? "enabled" : "disabled"}${ALLOWED_RECIPIENTS.length > 0
+        ? `, recipient allowlist: ${ALLOWED_RECIPIENTS.length} rule(s)`
+        : ""})`);
+}
+main().catch((error) => {
+    console.error("Fatal error in main():", error);
+    process.exit(1);
+});

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@mailpace/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.0",
+  "mcpName": "com.mailpace/mailpace-mcp",
+  "description": "MCP server for the MailPace Send API, Domains API, and Email Status API",
+  "main": "build/index.js",
+  "type": "module",
+  "bin": {
+    "mailpace-mcp": "build/index.js"
+  },
+  "files": [
+    "build",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf build",
+    "dev": "tsx index.ts",
+    "start": "node build/index.js",
+    "pretest": "npm run build",
+    "test": "node --test",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run clean && npm run build && npm test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mailpace/mailpace-mcp.git"
+  },
+  "homepage": "https://github.com/mailpace/mailpace-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/mailpace/mailpace-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mailpace",
+    "email",
+    "transactional-email"
+  ],
+  "author": "MailPace",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.4.0",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.27",
+    "tsx": "^4.20.6",
+    "typescript": "^5.8.2"
+  }
+}