@amplia-labs/purelymail-mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amplia Labs
+
+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,129 @@
-# Temporary Holding Version
+# purelymail-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.
+MCP server for the [Purelymail API](https://news.purelymail.com/api/index.html).
+It covers all 19 API operations: users, password reset methods, app passwords,
+routing rules, domains and account credit.
+
+## Usage
+
+Requires Node.js 20 or later. There is nothing to install: MCP clients run the
+package through `npx`.
+
+| Variable               | Required | Description                                     |
+| ---------------------- | -------- | ----------------------------------------------- |
+| `PURELYMAIL_API_TOKEN` | yes      | API token from your Purelymail account settings |
+| `PURELYMAIL_READ_ONLY` | no       | `true` or `1` exposes only the 7 read tools     |
+
+### Claude Code
+
+```bash
+claude mcp add purelymail \
+  -e PURELYMAIL_API_TOKEN=your-token \
+  -- npx -y @amplia-labs/purelymail-mcp
+```
+
+### Other MCP clients
+
+```json
+{
+  "mcpServers": {
+    "purelymail": {
+      "command": "npx",
+      "args": ["-y", "@amplia-labs/purelymail-mcp"],
+      "env": { "PURELYMAIL_API_TOKEN": "your-token" }
+    }
+  }
+}
+```
+
+## Tools
+
+| Area           | Read                                 | Write                                  | Destructive                                                    |
+| -------------- | ------------------------------------ | -------------------------------------- | -------------------------------------------------------------- |
+| Users          | `list_users`, `get_user`             | `create_user`                          | `modify_user`, `delete_user`                                   |
+| Password reset | `list_password_reset_methods`        |                                        | `upsert_password_reset_method`, `delete_password_reset_method` |
+| App passwords  |                                      | `create_app_password`                  | `delete_app_password`                                          |
+| Routing        | `list_routing_rules`                 | `create_routing_rule`                  | `delete_routing_rule`                                          |
+| Domains        | `list_domains`, `get_ownership_code` | `add_domain`, `update_domain_settings` | `delete_domain`                                                |
+| Billing        | `check_account_credit`               |                                        |                                                                |
+
+Tools carry the MCP annotations `readOnlyHint` and `destructiveHint`, which
+clients can use to ask for confirmation.
+
+## Security
+
+- The token grants administrative access to the whole account. Use
+  `PURELYMAIL_READ_ONLY=true` when you only need to look things up.
+- `delete_domain` deletes the domain **and all of its users**.
+- Passwords given to `create_user` and `modify_user`, and those returned by
+  `create_app_password`, pass through the model's context and the MCP client's
+  conversation history. Rotate any that are sensitive afterwards.
+
+## API behavior
+
+- Errors come back as **HTTP 200** with
+  `{"type":"error","code":...,"message":...}`, which the spec does not document.
+  The client inspects the response body and reports these as `isError`.
+- `list_password_reset_methods` returns the methods under a key named `users`.
+  That name comes from the API itself.
+- `delete_password_reset_method` requires `target`, even though the spec marks it
+  optional, because the spec does not say what happens without it.
+- Requests are never retried automatically. After a timeout, check the current
+  state before repeating a write.
+
+## Development
+
+```bash
+git clone https://github.com/amplia-labs/purelymail-mcp.git
+cd purelymail-mcp
+npm install
+npm run build
+```
+
+To run a local build from an MCP client, use
+`node /path/to/purelymail-mcp/dist/index.js` as the command.
+
+### Quality checks
+
+```bash
+npm run check
+```
+
+Runs these in order, stopping at the first failure:
+
+| Command                | Tool                                                    | What it checks                                                                             |
+| ---------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `npx tsc --noEmit`     | TypeScript                                              | Types                                                                                      |
+| `npm run lint`         | [oxlint](https://oxc.rs/docs/guide/usage/linter.html)   | `correctness`, `suspicious` and `perf` rules, with type-aware analysis; warnings also fail |
+| `npm run format:check` | [oxfmt](https://oxc.rs/docs/guide/usage/formatter.html) | Formatting                                                                                 |
+| `npm run knip`         | [knip](https://knip.dev)                                | Unused exports, files and dependencies                                                     |
+| `npm run cpd`          | [jscpd](https://github.com/kucherenko/jscpd)            | Duplicated code in `src` and `test`, with zero tolerance                                   |
+| `npm test`             | `node:test`                                             | Build and tests                                                                            |
+
+To fix issues automatically, run `npm run lint:fix` and `npm run format`.
+
+The tests use a fake HTTP server and never call the real API. The development
+tools require Node.js 20.19 or later.
+
+### Releasing
+
+Releases are published to npm by the
+[publish workflow](.github/workflows/publish.yml), using
+[trusted publishing](https://docs.npmjs.com/trusted-publishers). No npm token is
+stored in the repository.
+
+1. Update the version in `package.json` and in both `version` fields of
+   `server.json`. A test fails if they disagree.
+2. Merge the change to `main`.
+3. Tag that commit and push the tag. The tag must match the version:
+
+   ```bash
+   git tag v1.2.3
+   git push origin v1.2.3
+   ```
+
+The workflow runs `npm run check` before uploading anything.
+
+## License
+
+[MIT](LICENSE)

package/dist/client.js

@@ -0,0 +1,69 @@
+const DEFAULT_BASE_URL = "https://purelymail.com";
+const DEFAULT_TIMEOUT_MS = 30_000;
+/** An error reported by the Purelymail API itself, e.g. `invalidToken`. */
+export class PurelymailApiError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "PurelymailApiError";
+        this.code = code;
+    }
+}
+export class PurelymailClient {
+    #token;
+    #baseUrl;
+    #timeoutMs;
+    constructor(options) {
+        this.#token = options.token;
+        this.#baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+        this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    /** POSTs to an API path and returns the unwrapped `result` payload. */
+    async call(path, body) {
+        let response;
+        try {
+            response = await fetch(new URL(path, this.#baseUrl), {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "Purelymail-Api-Token": this.#token,
+                },
+                body: JSON.stringify(body),
+                // Never replay the token (or a write) against another location.
+                redirect: "error",
+                signal: AbortSignal.timeout(this.#timeoutMs),
+            });
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === "TimeoutError") {
+                throw new Error(`Request to ${path} timed out after ${this.#timeoutMs}ms. ` +
+                    "A write may or may not have been applied; check before retrying.", { cause: error });
+            }
+            throw new Error(`Request to ${path} failed: ${String(error)}`, {
+                cause: error,
+            });
+        }
+        const text = await response.text();
+        let payload;
+        try {
+            payload = JSON.parse(text);
+        }
+        catch {
+            throw new Error(`Non-JSON response from ${path} (HTTP ${response.status}): ${text.slice(0, 200)}`);
+        }
+        // The API reports failures as HTTP 200 with `type: "error"` in the body,
+        // so the status code alone says nothing about success.
+        if (isRecord(payload)) {
+            if (payload.type === "error") {
+                throw new PurelymailApiError(typeof payload.code === "string" ? payload.code : "unknown", typeof payload.message === "string" ? payload.message : "Unknown error");
+            }
+            if (response.ok && "result" in payload) {
+                return payload.result;
+            }
+        }
+        throw new Error(`Unexpected response from ${path} (HTTP ${response.status}): ${text.slice(0, 200)}`);
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}

package/dist/index.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { PurelymailClient } from "./client.js";
+import { createServer } from "./server.js";
+const token = process.env.PURELYMAIL_API_TOKEN?.trim();
+if (!token) {
+    console.error("PURELYMAIL_API_TOKEN is not set. Get your API token from your Purelymail account settings.");
+    process.exit(1);
+}
+const readOnly = ["1", "true"].includes(process.env.PURELYMAIL_READ_ONLY?.trim().toLowerCase() ?? "");
+const server = createServer({ client: new PurelymailClient({ token }), readOnly });
+await server.connect(new StdioServerTransport());

package/dist/server.js

@@ -0,0 +1,46 @@
+import { createRequire } from "node:module";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { PurelymailApiError } from "./client.js";
+import { tools } from "./tools.js";
+const packageJson = createRequire(import.meta.url)("../package.json");
+export function createServer({ client, readOnly = false }) {
+    const server = new McpServer({ name: "purelymail", version: packageJson.version });
+    for (const tool of tools) {
+        if (readOnly && tool.kind !== "read")
+            continue;
+        server.registerTool(tool.name, {
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            annotations: annotationsFor(tool),
+        }, (args) => runTool(client, tool, args));
+    }
+    return server;
+}
+function annotationsFor(tool) {
+    return {
+        title: tool.title,
+        readOnlyHint: tool.kind === "read",
+        destructiveHint: tool.kind === "destructive",
+        openWorldHint: true,
+    };
+}
+async function runTool(client, tool, args) {
+    try {
+        const result = await client.call(tool.path, args);
+        return { content: [{ type: "text", text: formatResult(result) }] };
+    }
+    catch (error) {
+        const text = error instanceof PurelymailApiError
+            ? `Purelymail API error (${error.code}): ${error.message}`
+            : error instanceof Error
+                ? error.message
+                : String(error);
+        return { isError: true, content: [{ type: "text", text }] };
+    }
+}
+/** Write operations return `{}`, which reads as nothing having happened. */
+function formatResult(result) {
+    const isEmpty = typeof result === "object" && result !== null && Object.keys(result).length === 0;
+    return JSON.stringify(isEmpty ? { success: true } : result, null, 2);
+}

package/dist/tools.js

@@ -0,0 +1,247 @@
+import { z } from "zod";
+const fullUserName = z.string().min(1).describe('Full username, e.g. "user@domain.com"');
+export const tools = [
+    // Users
+    {
+        name: "list_users",
+        title: "List users",
+        description: "Lists all users under the account (up to 1000).",
+        path: "/api/v0/listUser",
+        kind: "read",
+        inputSchema: {},
+    },
+    {
+        name: "get_user",
+        title: "Get user",
+        description: "Retrieves a user's settings: search indexing, recovery, 2FA requirement, spam filtering and password reset methods.",
+        path: "/api/v0/getUser",
+        kind: "read",
+        inputSchema: { userName: fullUserName },
+    },
+    {
+        name: "create_user",
+        title: "Create user",
+        description: "Creates a new mailbox user on a domain.",
+        path: "/api/v0/createUser",
+        kind: "write",
+        inputSchema: {
+            userName: z.string().min(1).describe('Local part only, e.g. "user" in "user@domain.com"'),
+            domainName: z.string().min(1),
+            password: z.string().min(1),
+            enablePasswordReset: z.boolean().optional().describe("Defaults to true"),
+            recoveryEmail: z.string().optional(),
+            recoveryEmailDescription: z.string().optional(),
+            recoveryPhone: z.string().optional(),
+            recoveryPhoneDescription: z.string().optional(),
+            enableSearchIndexing: z.boolean().optional().describe("Defaults to true"),
+            sendWelcomeEmail: z.boolean().optional().describe("Defaults to true"),
+        },
+    },
+    {
+        name: "modify_user",
+        title: "Modify user",
+        description: "Changes a user's address, password or settings. Only the fields provided are changed.",
+        path: "/api/v0/modifyUser",
+        kind: "destructive",
+        inputSchema: {
+            userName: fullUserName,
+            newUserName: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Full new username, e.g. "user@domain.com"'),
+            newPassword: z.string().min(1).optional(),
+            enableSearchIndexing: z
+                .boolean()
+                .optional()
+                .describe("Indexes may take some time to be created after enabling."),
+            enablePasswordReset: z
+                .boolean()
+                .optional()
+                .describe("Whether this user can have their password reset."),
+            requireTwoFactorAuthentication: z
+                .boolean()
+                .optional()
+                .describe("Whether this user requires 2FA for login."),
+        },
+    },
+    {
+        name: "delete_user",
+        title: "Delete user",
+        description: "Permanently deletes a user.",
+        path: "/api/v0/deleteUser",
+        kind: "destructive",
+        inputSchema: { userName: fullUserName },
+    },
+    // Password reset methods
+    {
+        name: "list_password_reset_methods",
+        title: "List password reset methods",
+        description: "Lists a user's password reset methods. The API returns them under a key named `users`.",
+        path: "/api/v0/listPasswordReset",
+        kind: "read",
+        inputSchema: { userName: fullUserName },
+    },
+    {
+        name: "upsert_password_reset_method",
+        title: "Create or update password reset method",
+        description: "Creates a password reset method, or updates an existing one when existingTarget is given. A reset method can take over the account, so make sure the target belongs to the user.",
+        path: "/api/v0/upsertPasswordReset",
+        kind: "destructive",
+        inputSchema: {
+            userName: fullUserName,
+            existingTarget: z
+                .string()
+                .optional()
+                .describe("Target from list_password_reset_methods. If provided, updates the method matching it instead of creating a new one."),
+            type: z.enum(["email", "phone"]),
+            target: z.string().min(1).describe("Email address or phone number"),
+            description: z.string().optional().describe("Human-readable description"),
+            allowMfaReset: z
+                .boolean()
+                .optional()
+                .describe("Whether this method can reset the user's MFA as well. Defaults to true."),
+        },
+    },
+    {
+        name: "delete_password_reset_method",
+        title: "Delete password reset method",
+        description: "Deletes one of a user's password reset methods.",
+        path: "/api/v0/deletePasswordReset",
+        kind: "destructive",
+        inputSchema: {
+            userName: fullUserName,
+            // Optional in the API spec, which does not say what omitting it does.
+            // Required here so a delete always names what it removes.
+            target: z.string().min(1).describe("Target from list_password_reset_methods"),
+        },
+    },
+    // App passwords
+    {
+        name: "create_app_password",
+        title: "Create app password",
+        description: "Creates an app password for a user and returns it. The result is a credential: show it to the user once and do not store or repeat it.",
+        path: "/api/v0/createAppPassword",
+        kind: "write",
+        inputSchema: {
+            userHandle: fullUserName,
+            name: z.string().optional().describe("Optional friendly description"),
+        },
+    },
+    {
+        name: "delete_app_password",
+        title: "Delete app password",
+        description: "Deletes an app password. Requires the full password value; the API has no way to list them.",
+        path: "/api/v0/deleteAppPassword",
+        kind: "destructive",
+        inputSchema: {
+            userName: fullUserName,
+            appPassword: z.string().min(1).describe("Full app password"),
+        },
+    },
+    // Routing
+    {
+        name: "list_routing_rules",
+        title: "List routing rules",
+        description: "Lists all routing rules active under the account.",
+        path: "/api/v0/listRoutingRules",
+        kind: "read",
+        inputSchema: {},
+    },
+    {
+        name: "create_routing_rule",
+        title: "Create routing rule",
+        description: "Creates a routing rule for a domain. It must not have the same user/prefix as another rule on that domain.",
+        path: "/api/v0/createRoutingRule",
+        kind: "write",
+        inputSchema: {
+            domainName: z.string().min(1),
+            prefix: z.boolean().describe("Whether matchUser is matched as a prefix of the local part"),
+            matchUser: z.string().describe('Local part to match, i.e. "user" in "user@domain.org"'),
+            targetAddresses: z
+                .array(z.string().min(1))
+                .min(1)
+                .describe("Full email addresses this mail will be rerouted to"),
+            catchall: z
+                .boolean()
+                .optional()
+                .describe("Whether this rule will not fire if the address maps to a user. Defaults to false."),
+        },
+    },
+    {
+        name: "delete_routing_rule",
+        title: "Delete routing rule",
+        description: "Deletes a routing rule.",
+        path: "/api/v0/deleteRoutingRule",
+        kind: "destructive",
+        inputSchema: {
+            routingRuleId: z.number().int().describe("Rule id from list_routing_rules"),
+        },
+    },
+    // Domains
+    {
+        name: "list_domains",
+        title: "List domains",
+        description: "Lists domains accessible to the account, with their settings and a DNS summary (MX, SPF, DKIM, DMARC).",
+        path: "/api/v0/listDomains",
+        kind: "read",
+        inputSchema: {
+            includeShared: z
+                .boolean()
+                .optional()
+                .describe("Whether to include Purelymail shared domains. Defaults to false."),
+        },
+    },
+    {
+        name: "get_ownership_code",
+        title: "Get ownership code",
+        description: "Gets the value of the DNS ownership proof record required before add_domain will succeed.",
+        path: "/api/v0/getOwnershipCode",
+        kind: "read",
+        inputSchema: {},
+    },
+    {
+        name: "add_domain",
+        title: "Add domain",
+        description: "Adds a domain, provided it passes DNS checks. See get_ownership_code.",
+        path: "/api/v0/addDomain",
+        kind: "write",
+        inputSchema: { domainName: z.string().min(1) },
+    },
+    {
+        name: "update_domain_settings",
+        title: "Update domain settings",
+        description: "Updates settings of an owned domain, and can trigger a DNS recheck. Only the fields provided are changed.",
+        path: "/api/v0/updateDomainSettings",
+        kind: "write",
+        inputSchema: {
+            name: z.string().min(1).describe("Domain name"),
+            allowAccountReset: z
+                .boolean()
+                .optional()
+                .describe("Whether this domain can be used to reset an account's password"),
+            symbolicSubaddressing: z
+                .boolean()
+                .optional()
+                .describe("Whether symbolic subaddressing is enabled on this domain"),
+            recheckDns: z.boolean().optional().describe("Defaults to false"),
+        },
+    },
+    {
+        name: "delete_domain",
+        title: "Delete domain",
+        description: "Permanently deletes a domain AND all of its dependent settings and users. Confirm with the user first, listing what will be lost.",
+        path: "/api/v0/deleteDomain",
+        kind: "destructive",
+        inputSchema: { name: z.string().min(1).describe("Domain name") },
+    },
+    // Billing
+    {
+        name: "check_account_credit",
+        title: "Check account credit",
+        description: "Returns the current account credit as a decimal string with up to 64 digits of precision.",
+        path: "/api/v0/checkAccountCredit",
+        kind: "read",
+        inputSchema: {},
+    },
+];

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@amplia-labs/purelymail-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "MCP server for the Purelymail API (users, domains, routing, app passwords, billing)",
+  "keywords": [
+    "email",
+    "mcp",
+    "model-context-protocol",
+    "purelymail"
+  ],
+  "homepage": "https://github.com/amplia-labs/purelymail-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/amplia-labs/purelymail-mcp/issues"
+  },
+  "license": "MIT",
+  "author": "Amplia Labs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amplia-labs/purelymail-mcp.git"
+  },
+  "bin": {
+    "purelymail-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "npm run build && node --test",
+    "lint": "oxlint --deny-warnings",
+    "lint:fix": "oxlint --fix",
+    "format": "oxfmt",
+    "format:check": "oxfmt --check",
+    "knip": "knip",
+    "cpd": "jscpd",
+    "check": "tsc --noEmit && npm run lint && npm run format:check && npm run knip && npm run cpd && npm test",
+    "prepublishOnly": "npm run check"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "jscpd": "^5.4.2",
+    "knip": "^6.44.1",
+    "oxfmt": "^0.76.0",
+    "oxlint": "^1.91.0",
+    "oxlint-tsgolint": "^7.0.2006",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "mcpName": "io.github.amplia-labs/purelymail-mcp"
+}