@capimail/mcp 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0 - 2026-11-08
+
+First release.
+
+- stdio MCP server built on `@modelcontextprotocol/sdk` and `@capimail/sdk` 0.2.
+- Read tools: `search_docs`, `get_integration_guide`, `get_credits`, `get_email_status`, `check_suppression`, `list_validation_jobs`, `get_validation_job`, `get_validation_results`, `list_domain_monitors`.
+- Write tools: `send_email`, `send_otp`, `verify_otp`, `validate_emails`, `start_validation_job`, `check_domain`, `monitor_domain`, `add_suppression`.
+- Prompt `integrate-capimail`; resource `capimail://docs/full`.
+- Safety defaults:
+  - Live keys are read-only unless `CAPIMAIL_MCP_ACCESS=write`.
+  - `send_email` is capped at 5 recipients per call.
+  - Every send gets an idempotency key.
+  - API errors come back as readable tool results.

package/README.md

@@ -1,3 +1,98 @@
-# Temporary Holding Version
+# @capimail/mcp
 
-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.
+[Model Context Protocol](https://modelcontextprotocol.io) server for **CapiMail**. It lets AI coding agents and assistants (Claude Code, Cursor, VS Code Copilot, Windsurf, Claude Desktop) read the CapiMail docs, inspect your workspace, and, when you allow it, send transactional email, OTPs and run the Email Validation and Domain Health add-ons.
+
+Runs locally over stdio and calls the public CapiMail API with your key. No other data leaves your machine.
+
+## Quick start
+
+Start with a **test key** (`cm_test_…`, from Dashboard > API Keys). Every tool is available and nothing is delivered or charged.
+
+### Claude Code
+
+```bash
+claude mcp add capimail --env CAPIMAIL_API_KEY=cm_test_your_key -- npx -y @capimail/mcp
+```
+
+### Cursor (`.cursor/mcp.json`) and Windsurf (`~/.codeium/windsurf/mcp_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "capimail": {
+      "command": "npx",
+      "args": ["-y", "@capimail/mcp"],
+      "env": { "CAPIMAIL_API_KEY": "cm_test_your_key" }
+    }
+  }
+}
+```
+
+### VS Code (`.vscode/mcp.json`)
+
+The key is prompted once and never written to the file:
+
+```json
+{
+  "inputs": [{ "type": "promptString", "id": "capimail-key", "description": "CapiMail API key", "password": true }],
+  "servers": {
+    "capimail": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@capimail/mcp"],
+      "env": { "CAPIMAIL_API_KEY": "${input:capimail-key}" }
+    }
+  }
+}
+```
+
+### Claude Desktop (`claude_desktop_config.json`)
+
+Same `mcpServers` block as Cursor.
+
+## Tools
+
+| Tool | Access | What it does |
+| --- | --- | --- |
+| `search_docs` | read | Searches the CapiMail reference (endpoints, fields, errors, webhooks, add-ons). |
+| `get_integration_guide` | read | Integration checklist plus a TypeScript, Python or cURL snippet. |
+| `get_credits` | read | Balance, reserved and available credits. |
+| `get_email_status` | read | Status and provider events of a message. |
+| `check_suppression` | read | Whether an address is suppressed. |
+| `list_validation_jobs`, `get_validation_job`, `get_validation_results` | read | Bulk validation jobs and per-address results. |
+| `list_domain_monitors` | read | Monitored domains with their last DNS result. |
+| `send_email` | write | Transactional email, inline or `template_key` (max 5 recipients per call). |
+| `send_otp`, `verify_otp` | write | One-time codes using your OTP settings. |
+| `validate_emails`, `start_validation_job` | write | Email Validation add-on (paid). |
+| `check_domain`, `monitor_domain` | write | Domain Health add-on (paid, own domains free). |
+| `add_suppression` | write | Add an address to the suppression list. |
+
+Also available: the prompt **`integrate-capimail`** (guided setup for your codebase) and the resource **`capimail://docs/full`** (the full Markdown reference).
+
+## Safety defaults
+
+- **Test keys** get read and write tools; sends are simulated and nothing is charged.
+- **Live keys** get **read tools only**. Set `CAPIMAIL_MCP_ACCESS=write` to allow real sends and paid calls, and keep tool-call approval on in your client.
+- No bulk or marketing tools. `send_email` is capped at `CAPIMAIL_MCP_MAX_RECIPIENTS` (default 5). Campaigns stay in the dashboard.
+- All API rules still apply: verified domains, suppression, rate limits, credits.
+- Do not commit config files that contain a key.
+
+## Configuration
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `CAPIMAIL_API_KEY` | required | `cm_test_…` or `cm_live_…` |
+| `CAPIMAIL_MCP_ACCESS` | `write` for test keys, `read` for live keys | `read` or `write` |
+| `CAPIMAIL_MCP_MAX_RECIPIENTS` | `5` | Recipients per `send_email` call (1-50) |
+| `CAPIMAIL_BASE_URL` | `https://capimail.com` | API origin |
+
+## Other sources for agents
+
+- https://capimail.com/docs.md: the full reference as Markdown
+- https://capimail.com/openapi.yaml: OpenAPI 3.1, every `/api/v1` route
+- https://capimail.com/agents.md: a section for your repository's `AGENTS.md` (`curl -s https://capimail.com/agents.md >> AGENTS.md`)
+- [`@capimail/sdk`](https://www.npmjs.com/package/@capimail/sdk): the typed TypeScript client this server uses
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Runtime configuration from environment variables. The server never logs or
+ * returns the API key.
+ *
+ * Access levels:
+ * - "read": status, credits, suppressions (read), validation job reads,
+ *   domain monitor list, docs. Nothing that spends credits or sends email.
+ * - "write": everything, including sending email/OTP and paid add-on calls.
+ *
+ * Default: "write" for test keys (cm_test_, nothing is ever delivered or
+ * charged) and "read" for live keys. Set CAPIMAIL_MCP_ACCESS=write to let an
+ * agent send real email or spend credits with a live key.
+ */
+export type Access = "read" | "write";
+export type McpConfig = {
+    apiKey: string;
+    baseUrl: string;
+    mode: "test" | "live";
+    access: Access;
+    /** Hard cap on recipients per send_email call made by an agent. */
+    maxRecipients: number;
+};
+export declare class ConfigError extends Error {
+}
+export declare function loadConfig(env?: Record<string, string | undefined>): McpConfig;

package/dist/config.js

@@ -0,0 +1,22 @@
+export class ConfigError extends Error {
+}
+export function loadConfig(env = process.env) {
+    const apiKey = env.CAPIMAIL_API_KEY?.trim();
+    if (!apiKey)
+        throw new ConfigError("Set CAPIMAIL_API_KEY to a CapiMail API key (cm_test_… to start safely, or cm_live_…).");
+    if (!/^cm_(test|live)_/.test(apiKey))
+        throw new ConfigError("CAPIMAIL_API_KEY must start with cm_test_ or cm_live_.");
+    const mode = apiKey.startsWith("cm_test_") ? "test" : "live";
+    const requested = env.CAPIMAIL_MCP_ACCESS?.trim().toLowerCase();
+    if (requested && requested !== "read" && requested !== "write")
+        throw new ConfigError("CAPIMAIL_MCP_ACCESS must be read or write.");
+    const access = requested ?? (mode === "test" ? "write" : "read");
+    const maxRecipients = Math.min(50, Math.max(1, Number(env.CAPIMAIL_MCP_MAX_RECIPIENTS ?? 5) || 5));
+    return {
+        apiKey,
+        baseUrl: (env.CAPIMAIL_BASE_URL?.trim() || "https://capimail.com").replace(/\/$/, ""),
+        mode,
+        access,
+        maxRecipients,
+    };
+}

package/dist/docs.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Documentation access for coding agents: the full Markdown reference served
+ * at /llms-full.txt (same source as /docs), split into sections and searched
+ * by keyword. Cached per process for 10 minutes.
+ */
+export type DocSection = {
+    title: string;
+    body: string;
+};
+export declare function fetchDocs(baseUrl: string, fetchImpl?: typeof fetch, now?: number): Promise<string>;
+export declare function resetDocsCache(): void;
+/** Splits on Markdown headings (## and ###), keeping each heading with its body. */
+export declare function splitSections(markdown: string): DocSection[];
+/** Ranks sections by query term hits (title hits weigh more) and returns the best ones. */
+export declare function searchSections(sections: DocSection[], query: string, limit?: number): DocSection[];

package/dist/docs.js

@@ -0,0 +1,51 @@
+const TTL_MS = 10 * 60_000;
+let cache = null;
+export async function fetchDocs(baseUrl, fetchImpl = fetch, now = Date.now()) {
+    if (cache && cache.baseUrl === baseUrl && now - cache.at < TTL_MS)
+        return cache.text;
+    const response = await fetchImpl(`${baseUrl}/llms-full.txt`, { headers: { accept: "text/plain" } });
+    if (!response.ok)
+        throw new Error(`Could not load CapiMail docs (HTTP ${response.status}).`);
+    const text = await response.text();
+    cache = { at: now, baseUrl, text };
+    return text;
+}
+export function resetDocsCache() {
+    cache = null;
+}
+/** Splits on Markdown headings (## and ###), keeping each heading with its body. */
+export function splitSections(markdown) {
+    const sections = [];
+    let current = null;
+    for (const line of markdown.split("\n")) {
+        const heading = /^#{2,3}\s+(.*)$/.exec(line);
+        if (heading) {
+            if (current)
+                sections.push(current);
+            current = { title: heading[1].trim(), body: "" };
+        }
+        else if (current) {
+            current.body += `${line}\n`;
+        }
+    }
+    if (current)
+        sections.push(current);
+    return sections.map((section) => ({ ...section, body: section.body.trim() })).filter((section) => section.body.length > 0);
+}
+/** Ranks sections by query term hits (title hits weigh more) and returns the best ones. */
+export function searchSections(sections, query, limit = 3) {
+    const terms = query.toLowerCase().split(/[^a-z0-9_./-]+/).filter((term) => term.length > 1);
+    if (!terms.length)
+        return sections.slice(0, limit);
+    return sections
+        .map((section, index) => {
+        const title = section.title.toLowerCase();
+        const body = section.body.toLowerCase();
+        const score = terms.reduce((sum, term) => sum + (title.includes(term) ? 5 : 0) + (body.split(term).length - 1), 0);
+        return { section, score, index };
+    })
+        .filter((entry) => entry.score > 0)
+        .sort((a, b) => b.score - a.score || a.index - b.index)
+        .slice(0, limit)
+        .map((entry) => entry.section);
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// CapiMail MCP server (stdio). Configure your AI client to run:
+//   npx -y @capimail/mcp
+// with CAPIMAIL_API_KEY in its environment. See README.md.
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ConfigError, loadConfig } from "./config.js";
+import { createServer } from "./server.js";
+async function main() {
+    let config;
+    try {
+        config = loadConfig();
+    }
+    catch (error) {
+        // stdout belongs to the MCP protocol; diagnostics go to stderr.
+        console.error(`[capimail-mcp] ${error instanceof ConfigError ? error.message : "Invalid configuration."}`);
+        process.exit(1);
+    }
+    const server = createServer(config);
+    await server.connect(new StdioServerTransport());
+    console.error(`[capimail-mcp] ready (${config.mode} key, ${config.access} access, ${config.baseUrl})`);
+}
+main().catch((error) => {
+    console.error("[capimail-mcp] fatal:", error instanceof Error ? error.message : error);
+    process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,15 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { McpConfig } from "./config.js";
+export declare const SERVER_NAME = "capimail";
+export declare const SERVER_VERSION = "0.1.0";
+/** Turns any thrown error into a readable tool result instead of a protocol error. */
+export declare function errorResult(error: unknown): {
+    isError: boolean;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function createServer(config: McpConfig, options?: {
+    fetch?: typeof fetch;
+}): McpServer;

package/dist/server.js

@@ -0,0 +1,65 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CapiMail, CapiMailError } from "@capimail/sdk";
+import { z } from "zod";
+import { fetchDocs } from "./docs.js";
+import { integrationGuide, toolsFor } from "./tools.js";
+export const SERVER_NAME = "capimail";
+export const SERVER_VERSION = "0.1.0";
+/** Turns any thrown error into a readable tool result instead of a protocol error. */
+export function errorResult(error) {
+    if (error instanceof CapiMailError) {
+        const hint = error.retryAfterSeconds ? ` Retry after ${error.retryAfterSeconds}s.` : "";
+        return { isError: true, content: [{ type: "text", text: `CapiMail API error ${error.status} ${error.code}: ${error.message}${hint}` }] };
+    }
+    return { isError: true, content: [{ type: "text", text: error instanceof Error ? error.message : "Unexpected error." }] };
+}
+export function createServer(config, options = {}) {
+    const client = new CapiMail({ apiKey: config.apiKey, baseUrl: config.baseUrl, fetch: options.fetch });
+    const context = { client, config, fetch: options.fetch };
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION }, {
+        instructions: [
+            "CapiMail is a transactional email API for Indonesian businesses (also: Email Validation, OTP and Domain Health add-ons).",
+            "Before writing integration code, call search_docs or get_integration_guide.",
+            `This session uses a ${config.mode} key with ${config.access} access.`,
+            config.mode === "test" ? "Test key: sends are simulated, nothing is delivered and no credits are spent." : "Live key: write tools deliver real email and spend credits; confirm with the user first.",
+        ].join(" "),
+    });
+    for (const tool of toolsFor(config)) {
+        server.registerTool(tool.name, { title: tool.title, description: tool.description, inputSchema: tool.inputSchema, annotations: tool.annotations }, async (args) => {
+            try {
+                const result = await tool.handler(args, context);
+                return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+            }
+            catch (error) {
+                return errorResult(error);
+            }
+        });
+    }
+    server.registerResource("capimail-docs", "capimail://docs/full", { title: "CapiMail API reference (Markdown)", description: "Every endpoint, field, error code, webhook and add-on.", mimeType: "text/markdown" }, async (uri) => ({ contents: [{ uri: uri.href, mimeType: "text/markdown", text: await fetchDocs(config.baseUrl, options.fetch) }] }));
+    server.registerPrompt("integrate-capimail", {
+        title: "Integrate CapiMail into this project",
+        description: "Guides the coding agent through adding transactional email with CapiMail.",
+        argsSchema: { use_case: z.string().optional().describe("e.g. email verification, OTP login, password reset, receipts") },
+    }, ({ use_case }) => {
+        const guide = integrationGuide(config.baseUrl, "typescript");
+        return {
+            messages: [{
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: [
+                            `Add CapiMail transactional email to this project${use_case ? ` for: ${use_case}` : ""}.`,
+                            "Follow this checklist exactly:",
+                            ...guide.checklist.map((step, index) => `${index + 1}. ${step}`),
+                            "",
+                            "Reference snippet:",
+                            guide.snippet,
+                            "",
+                            "Use the search_docs tool for any field, error code or webhook detail you are unsure about. Do not invent endpoints.",
+                        ].join("\n"),
+                    },
+                }],
+        };
+    });
+    return server;
+}

package/dist/tools.d.ts

@@ -0,0 +1,42 @@
+import type { CapiMail } from "@capimail/sdk";
+import { z } from "zod";
+import type { Access, McpConfig } from "./config.js";
+/**
+ * Every tool the CapiMail MCP server can expose. Each declares the access it
+ * needs: "read" tools never send email or spend credits; "write" tools do and
+ * are only registered when the configuration allows it (see config.ts).
+ * Handlers return plain JSON; the server turns them into MCP text content.
+ */
+export type ToolContext = {
+    client: CapiMail;
+    config: McpConfig;
+    fetch?: typeof fetch;
+};
+export type ToolDefinition = {
+    name: string;
+    title: string;
+    description: string;
+    access: Access;
+    /** MCP tool annotations, shown to the user by most clients. */
+    annotations: {
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        idempotentHint?: boolean;
+        openWorldHint?: boolean;
+    };
+    inputSchema: z.ZodRawShape;
+    handler: (args: Record<string, unknown>, context: ToolContext) => Promise<unknown>;
+};
+export declare const TOOLS: ToolDefinition[];
+/** Tools available for a configuration: write tools only when access is "write". */
+export declare function toolsFor(config: McpConfig): ToolDefinition[];
+export declare function integrationGuide(baseUrl: string, language: string): {
+    checklist: string[];
+    snippet: string;
+    references: {
+        docs: string;
+        markdown: string;
+        openapi: string;
+        agents_md: string;
+    };
+};

package/dist/tools.js

@@ -0,0 +1,272 @@
+import { z } from "zod";
+import { fetchDocs, searchSections, splitSections } from "./docs.js";
+const email = z.string().trim().max(320);
+const idempotencyKey = z.string().regex(/^[A-Za-z0-9._:-]{8,128}$/).optional()
+    .describe("Optional retry-safety key (8-128 of A-Z a-z 0-9 . _ : -). Reusing it never sends or charges twice.");
+const READ = { readOnlyHint: true, openWorldHint: true };
+export const TOOLS = [
+    // ---- Docs (no API key use) ------------------------------------------------
+    {
+        name: "search_docs",
+        title: "Search CapiMail docs",
+        description: "Search the CapiMail API documentation (endpoints, fields, errors, webhooks, add-ons, pricing). Use this before writing integration code.",
+        access: "read",
+        annotations: READ,
+        inputSchema: { query: z.string().min(2).max(200).describe("What you need, e.g. 'verify webhook signature' or 'send with template_key'.") },
+        handler: async (args, { config, fetch: fetchImpl }) => {
+            const sections = splitSections(await fetchDocs(config.baseUrl, fetchImpl));
+            const hits = searchSections(sections, String(args.query));
+            return {
+                results: hits.map((section) => ({ title: section.title, content: section.body.slice(0, 4000) })),
+                full_reference: `${config.baseUrl}/llms-full.txt`,
+                openapi: `${config.baseUrl}/openapi.yaml`,
+            };
+        },
+    },
+    {
+        name: "get_integration_guide",
+        title: "Get the integration checklist",
+        description: "Returns the step-by-step checklist and code conventions for adding CapiMail to an application (keys, domain, SDK, idempotency, webhooks, test mode).",
+        access: "read",
+        annotations: READ,
+        inputSchema: { language: z.enum(["typescript", "python", "curl"]).optional().describe("Preferred language for snippets (default typescript).") },
+        handler: async (args, { config }) => integrationGuide(config.baseUrl, args.language ?? "typescript"),
+    },
+    // ---- Account and email status ----------------------------------------------
+    {
+        name: "get_credits",
+        title: "Get credit balance",
+        description: "Returns the workspace's credit balance, reserved and available credits.",
+        access: "read",
+        annotations: READ,
+        inputSchema: {},
+        handler: async (_args, { client }) => client.account.credits(),
+    },
+    {
+        name: "get_email_status",
+        title: "Get email status",
+        description: "Returns the status and provider events of a sent email by message id.",
+        access: "read",
+        annotations: READ,
+        inputSchema: { message_id: z.string().uuid() },
+        handler: async (args, { client }) => client.emails.get(String(args.message_id)),
+    },
+    {
+        name: "check_suppression",
+        title: "Check if an address is suppressed",
+        description: "Returns whether CapiMail will refuse to send to an address (bounced, complained, unsubscribed or manually suppressed).",
+        access: "read",
+        annotations: READ,
+        inputSchema: { email },
+        handler: async (args, { client }) => client.suppressions.get(String(args.email)),
+    },
+    {
+        name: "list_validation_jobs",
+        title: "List validation jobs",
+        description: "Lists recent bulk Email Validation jobs with status and summary.",
+        access: "read",
+        annotations: READ,
+        inputSchema: { limit: z.number().int().min(1).max(100).optional() },
+        handler: async (args, { client }) => client.validation.jobs.list({ limit: args.limit }),
+    },
+    {
+        name: "get_validation_job",
+        title: "Get a validation job",
+        description: "Returns a bulk validation job's status and, once completed, its summary.",
+        access: "read",
+        annotations: READ,
+        inputSchema: { job_id: z.string().uuid() },
+        handler: async (args, { client }) => client.validation.jobs.get(String(args.job_id)),
+    },
+    {
+        name: "get_validation_results",
+        title: "Get validation results",
+        description: "Returns one page (up to 1000) of per-address results of a validation job, optionally filtered by verdict.",
+        access: "read",
+        annotations: READ,
+        inputSchema: {
+            job_id: z.string().uuid(),
+            verdict: z.enum(["valid", "risky", "invalid", "unknown"]).optional(),
+            after: z.number().int().optional().describe("The next_after value of the previous page."),
+            limit: z.number().int().min(1).max(1000).optional(),
+        },
+        handler: async (args, { client }) => client.validation.jobs.results(String(args.job_id), {
+            verdict: args.verdict,
+            after: args.after,
+            limit: args.limit,
+        }),
+    },
+    {
+        name: "list_domain_monitors",
+        title: "List monitored domains",
+        description: "Lists domains under daily DNS monitoring with their last MX/SPF/DKIM/DMARC result.",
+        access: "read",
+        annotations: READ,
+        inputSchema: {},
+        handler: async (_args, { client }) => ({ monitors: await client.domains.monitors.list() }),
+    },
+    // ---- Write: sends email or spends credits ----------------------------------
+    {
+        name: "send_email",
+        title: "Send a transactional email",
+        description: "Sends a transactional email from a verified domain (inline html/text or a stored template_key). With a test key nothing is delivered. Not for marketing or bulk sends.",
+        access: "write",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        inputSchema: {
+            from: z.string().max(423).describe("Verified sender, e.g. 'Acme <hello@acme.co.id>'."),
+            to: z.array(email).min(1).describe("Recipients (capped by CAPIMAIL_MCP_MAX_RECIPIENTS, default 5)."),
+            subject: z.string().max(998).optional(),
+            html: z.string().max(200_000).optional(),
+            text: z.string().max(100_000).optional(),
+            template_key: z.string().optional().describe("Send a stored transactional template instead of subject/html/text."),
+            locale: z.string().optional(),
+            variables: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+            idempotency_key: idempotencyKey,
+        },
+        handler: async (args, { client, config }) => {
+            const to = args.to;
+            if (to.length > config.maxRecipients)
+                throw new Error(`An agent may send to at most ${config.maxRecipients} recipients per call. Use the API or dashboard for larger sends.`);
+            return client.emails.send({
+                from: String(args.from),
+                to,
+                subject: args.subject,
+                html: args.html,
+                text: args.text,
+                idempotencyKey: args.idempotency_key ?? `mcp-${crypto.randomUUID()}`,
+                ...(args.template_key ? { template: { key: String(args.template_key), locale: args.locale, variables: args.variables } } : {}),
+            });
+        },
+    },
+    {
+        name: "validate_emails",
+        title: "Validate email addresses",
+        description: "Checks up to 100 addresses now (syntax, mail server, disposable, role). Costs 2 credits per address with a verdict; needs a live key.",
+        access: "write",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        inputSchema: { emails: z.array(email).min(1).max(100), idempotency_key: idempotencyKey },
+        handler: async (args, { client }) => client.validation.check({ emails: args.emails, idempotencyKey: args.idempotency_key }),
+    },
+    {
+        name: "start_validation_job",
+        title: "Start a bulk validation job",
+        description: "Starts a background validation job for up to 10,000 addresses. Credits are charged up front (unknowns refunded); completion fires the validation.completed webhook.",
+        access: "write",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        inputSchema: {
+            emails: z.array(email).min(1).max(10_000),
+            suppress_invalid: z.boolean().optional(),
+            metadata: z.record(z.string(), z.string()).optional(),
+            idempotency_key: idempotencyKey,
+        },
+        handler: async (args, { client }) => client.validation.jobs.create({
+            emails: args.emails,
+            suppressInvalid: args.suppress_invalid,
+            metadata: args.metadata,
+            idempotencyKey: args.idempotency_key,
+        }),
+    },
+    {
+        name: "send_otp",
+        title: "Send a one-time code",
+        description: "Creates and emails a one-time code using the workspace's OTP settings. Returns the OTP id (and test_code with a test key).",
+        access: "write",
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+        inputSchema: {
+            to: email,
+            purpose: z.string().optional(),
+            domain: z.string().optional(),
+            template_key: z.string().optional(),
+            locale: z.string().optional(),
+        },
+        handler: async (args, { client }) => client.otp.send({
+            to: String(args.to),
+            purpose: args.purpose,
+            domain: args.domain,
+            templateKey: args.template_key,
+            locale: args.locale,
+        }),
+    },
+    {
+        name: "verify_otp",
+        title: "Verify a one-time code",
+        description: "Verifies a code once. Wrong codes count toward the lock limit, so only call it with what the user typed.",
+        access: "write",
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+        inputSchema: { otp_id: z.string().uuid(), code: z.string().min(4).max(20) },
+        handler: async (args, { client }) => client.otp.verify(String(args.otp_id), String(args.code)),
+    },
+    {
+        name: "check_domain",
+        title: "Check a domain's email DNS",
+        description: "Live MX, SPF, DKIM and DMARC check with issue codes. Free for the workspace's verified sending domains, otherwise 5 credits.",
+        access: "write",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        inputSchema: { domain: z.string().max(253), dkim_selectors: z.array(z.string().max(63)).max(5).optional(), idempotency_key: idempotencyKey },
+        handler: async (args, { client }) => client.domains.check({ domain: String(args.domain), dkimSelectors: args.dkim_selectors, idempotencyKey: args.idempotency_key }),
+    },
+    {
+        name: "monitor_domain",
+        title: "Monitor a domain daily",
+        description: "Adds a domain to daily DNS monitoring (3 credits per daily check). domain.health_changed fires when its status changes.",
+        access: "write",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        inputSchema: { domain: z.string().max(253), dkim_selectors: z.array(z.string().max(63)).max(5).optional() },
+        handler: async (args, { client }) => client.domains.monitors.create({ domain: String(args.domain), dkimSelectors: args.dkim_selectors }),
+    },
+    {
+        name: "add_suppression",
+        title: "Suppress an address",
+        description: "Adds an address to the suppression list so CapiMail never sends to it.",
+        access: "write",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        inputSchema: { email, reason: z.enum(["manual", "unsubscribe", "spam_complaint", "bounce", "other"]).optional() },
+        handler: async (args, { client }) => client.suppressions.add(String(args.email), args.reason),
+    },
+];
+/** Tools available for a configuration: write tools only when access is "write". */
+export function toolsFor(config) {
+    return TOOLS.filter((tool) => tool.access === "read" || config.access === "write");
+}
+export function integrationGuide(baseUrl, language) {
+    const snippets = {
+        typescript: `npm install @capimail/sdk
+
+import { CapiMail } from "@capimail/sdk";
+const capimail = new CapiMail({ apiKey: process.env.CAPIMAIL_API_KEY! });
+
+await capimail.emails.send({
+  from: "Acme <hello@your-verified-domain.com>",
+  to: user.email,
+  template: { key: "email-verification", locale: "id", variables: { name: user.name, verify_url: link } },
+  idempotencyKey: \`verify-\${user.id}\`,
+});`,
+        python: `import os, requests
+requests.post("${baseUrl}/api/v1/emails",
+  headers={"Authorization": f"Bearer {os.environ['CAPIMAIL_API_KEY']}"},
+  json={"from": "hello@your-verified-domain.com", "to": ["user@example.com"],
+        "subject": "Welcome", "html": "<p>Hi</p>", "idempotency_key": "welcome-123"}, timeout=10)`,
+        curl: `curl -X POST ${baseUrl}/api/v1/emails \\
+  -H "Authorization: Bearer $CAPIMAIL_API_KEY" -H "Content-Type: application/json" \\
+  -d '{"from":"hello@your-verified-domain.com","to":["user@example.com"],"subject":"Welcome","html":"<p>Hi</p>","idempotency_key":"welcome-123"}'`,
+    };
+    return {
+        checklist: [
+            "Create an API key in the dashboard (API Keys). Start with cm_test_: full simulated lifecycle, nothing delivered, no credits.",
+            "Store it server-side as CAPIMAIL_API_KEY. Never expose it to the browser or commit it.",
+            "Verify a sending domain (Domains) and send only from addresses on it.",
+            "Send with POST /api/v1/emails or the SDK. Always pass an idempotency key derived from your own record id so retries never double-send.",
+            "A 202 means queued, not delivered. Track outcomes with webhooks (Settings > Webhooks) and verify X-CapiMail-Signature, or poll GET /api/v1/emails/{id}.",
+            "Handle errors by code: 402 insufficient_credits, 422 recipient_suppressed, 429 rate_limit_exceeded (respect Retry-After).",
+            "Prefer stored templates (template_key) for verification, OTP, reset and receipt emails; marketing content must use campaigns.",
+            "Switch to a cm_live_ key only after the organization is approved.",
+        ],
+        snippet: snippets[language] ?? snippets.typescript,
+        references: {
+            docs: `${baseUrl}/docs`,
+            markdown: `${baseUrl}/docs.md`,
+            openapi: `${baseUrl}/openapi.yaml`,
+            agents_md: `${baseUrl}/agents.md`,
+        },
+    };
+}

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@capimail/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Model Context Protocol server for CapiMail: lets AI coding agents and assistants read the docs, send transactional email, validate addresses, send/verify OTPs and check domain health.",
+  "author": "CapiMail",
+  "homepage": "https://capimail.com/docs#ai-agents",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "capimail-mcp": "./dist/index.js"
+  },
+  "main": "./dist/server.js",
+  "types": "./dist/server.d.ts",
+  "files": ["dist", "README.md", "CHANGELOG.md"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@capimail/sdk": "^0.2.0",
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "zod": "^4.1.11"
+  },
+  "keywords": ["capimail", "mcp", "model-context-protocol", "email", "transactional", "otp", "ai-agent", "claude", "cursor"],
+  "engines": {
+    "node": ">=18"
+  }
+}