@porkbunllc/mcp-server 0.1.1 → 0.3.2

package/README.md

@@ -2,20 +2,60 @@
 
 A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes the [Porkbun v3 API](https://porkbun.com/api/json/v3/documentation) as native tools for AI agents — Claude Desktop, Cursor, Cline, and any other MCP-compatible client.
 
-> **Status:** v0.1 — read-only tools only. Write operations (register, DNS edits, SSL provisioning) coming in subsequent releases.
+> **Status:** v0.3.1 — covers everything you can do in the Porkbun web UI. All write operations attach an `Idempotency-Key` automatically, so retries within 24 hours don't double-charge.
 
-## What's included (v0.1)
+## What's included (v0.3.1 — 30 tools)
+
+**Read tools (free, no spend, no state changes)**
 
 | Tool | Description |
 |---|---|
 | `ping` | Verify API connectivity and credentials |
 | `check_domain` | Check availability and pricing for a single domain |
+| `get_pricing` | Get registration/renewal/transfer pricing for all TLDs (no auth needed) |
+| `list_marketplace` | Browse the Porkbun aftermarket — filter by TLD, max price, name substring |
 | `list_domains` | Paginate through domains in the authenticated account |
 | `get_balance` | Get account credit balance |
-| `get_pricing` | Get registration/renewal/transfer pricing for all TLDs |
+| `get_api_settings` | Get monthly spend limit, low-balance alert, auto top-up config, MTD spend |
+| `get_nameservers` | Get current nameservers for a domain |
 | `list_dns_records` | List DNS records for a domain |
+| `list_dnssec_records` | List DNSSEC DS records published at the registry |
+| `list_url_forwards` | List URL forwarding rules for a domain |
+| `list_glue_records` | List glue records (host-to-IP mappings) for a domain |
+| `list_transfers` | List in-progress and recent inbound transfers |
+| `get_transfer_status` | Get status of a specific inbound transfer |
 | `get_ssl_bundle` | Retrieve the free Porkbun-issued SSL bundle for a domain |
 
+**Domain lifecycle writes (spend account credit)**
+
+| Tool | Description |
+|---|---|
+| `register_domain` | Register a new domain — call `check_domain` first to confirm price |
+| `renew_domain` | Renew an existing domain |
+| `transfer_domain` | Initiate an inbound transfer (returns transferId; takes 5-7 days) |
+
+**Domain settings writes (free)**
+
+| Tool | Description |
+|---|---|
+| `update_auto_renew` | Turn auto-renewal on or off |
+| `update_nameservers` | Replace the nameserver list for a domain (full replace, not append) |
+
+**DNS / DNSSEC / URL-forwarding / glue writes (free)**
+
+| Tool | Description |
+|---|---|
+| `create_dns_record` | Create a new DNS record (A, AAAA, CNAME, MX, TXT, etc.) |
+| `update_dns_record` | Update an existing DNS record by its ID |
+| `delete_dns_record` | Delete a DNS record by its ID |
+| `create_dnssec_record` | Submit a DNSSEC DS record to the registry |
+| `delete_dnssec_record` | Remove a DNSSEC DS record by key tag |
+| `create_url_forward` | Create a URL forwarding rule |
+| `delete_url_forward` | Delete a URL forwarding rule by ID |
+| `create_glue_record` | Create a glue record (host-to-IP mapping at the registry) |
+| `update_glue_record` | Replace the IP list for a glue record |
+| `delete_glue_record` | Delete a glue record by host |
+
 ## Install
 
 You'll need [Node.js](https://nodejs.org) 18 or newer.

package/dist/index.js

@@ -5,7 +5,7 @@ import { loadConfig } from "./api.js";
 import { tools } from "./tools.js";
 const server = new McpServer({
     name: "porkbun-mcp",
-    version: "0.1.0",
+    version: "0.3.2",
 });
 // Defer config loading until the first tool call. tools/list works without
 // credentials so MCP clients can still discover what's available.
@@ -19,6 +19,7 @@ for (const tool of tools) {
     server.registerTool(tool.name, {
         description: tool.description,
         inputSchema: tool.inputSchema,
+        ...(tool.annotations ? { annotations: tool.annotations } : {}),
     }, async (args) => {
         try {
             const result = await tool.handler(getConfig(), args);

package/dist/tools.js

@@ -1,9 +1,11 @@
 import { z } from "zod";
 import { call } from "./api.js";
+// ─── Read-only tools ────────────────────────────────────────────────────────
 const ping = {
     name: "ping",
     description: "Verify the Porkbun API connection and credentials. Returns the caller's public IP and whether the API key is valid. Use this as a first sanity check before making other calls.",
     inputSchema: {},
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
     handler: async (config) => {
         return await call(config, "/ping", { method: "POST" });
     },
@@ -17,6 +19,7 @@ const check_domain = {
             .min(3)
             .describe("Fully qualified domain name to check, e.g. `example.com`"),
     },
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
     handler: async (config, args) => {
         const domain = String(args.domain).toLowerCase();
         return await call(config, `/domain/checkDomain/${encodeURIComponent(domain)}`, {
@@ -39,6 +42,7 @@ const list_domains = {
             .optional()
             .describe("If true, include user-defined domain labels in the response."),
     },
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
     handler: async (config, args) => {
         const params = new URLSearchParams();
         if (args.start !== undefined)
@@ -53,6 +57,7 @@ const get_balance = {
     name: "get_balance",
     description: "Get the available account credit balance for the authenticated Porkbun account. Returns the balance in cents (integer) and a human-readable display string (e.g. `$12.34`). Use this to check spend headroom before initiating registrations or renewals.",
     inputSchema: {},
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
     handler: async (config) => {
         return await call(config, "/account/balance", { method: "GET" });
     },
@@ -61,6 +66,7 @@ const get_pricing = {
     name: "get_pricing",
     description: "Get current Porkbun pricing for all supported TLDs. Returns registration, renewal, and transfer prices per TLD in USD. No authentication required. Useful when an agent needs to compare TLD costs before registering. Note: this returns standard pricing only — premium domains have their own per-domain pricing reported by check_domain.",
     inputSchema: {},
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
     handler: async (config) => {
         return await call(config, "/pricing/get", { method: "POST" });
     },
@@ -74,6 +80,7 @@ const list_dns_records = {
             .min(3)
             .describe("Fully qualified domain name registered at Porkbun, e.g. `example.com`"),
     },
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
     handler: async (config, args) => {
         const domain = String(args.domain).toLowerCase();
         return await call(config, `/dns/retrieve/${encodeURIComponent(domain)}`, { method: "GET" });
@@ -88,17 +95,573 @@ const get_ssl_bundle = {
             .min(3)
             .describe("Fully qualified domain name registered at Porkbun, e.g. `example.com`"),
     },
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
     handler: async (config, args) => {
         const domain = String(args.domain).toLowerCase();
         return await call(config, `/ssl/retrieve/${encodeURIComponent(domain)}`, { method: "GET" });
     },
 };
+const get_nameservers = {
+    name: "get_nameservers",
+    description: "Get the current nameservers configured for a domain in the authenticated account. Returns an array of nameserver hostnames. Read-only complement to `update_nameservers`.",
+    inputSchema: {
+        domain: z.string().min(3).describe("Fully qualified domain name, e.g. `example.com`"),
+    },
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    handler: async (config, args) => {
+        const domain = String(args.domain).toLowerCase();
+        return await call(config, `/domain/getNs/${encodeURIComponent(domain)}`, { method: "GET" });
+    },
+};
+const list_url_forwards = {
+    name: "list_url_forwards",
+    description: "List all URL forwarding rules configured for a domain. Each entry includes its `id` (used by `delete_url_forward`), the source subdomain, the destination URL, the redirect type (permanent/temporary), and whether the request path and wildcards are forwarded.",
+    inputSchema: {
+        domain: z.string().min(3).describe("Fully qualified domain name, e.g. `example.com`"),
+    },
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    handler: async (config, args) => {
+        const domain = String(args.domain).toLowerCase();
+        return await call(config, `/domain/getUrlForwarding/${encodeURIComponent(domain)}`, {
+            method: "GET",
+        });
+    },
+};
+const list_dnssec_records = {
+    name: "list_dnssec_records",
+    description: "List the DNSSEC DS records currently submitted to the registry for a domain. Returns key tag, algorithm, digest type, and digest. Use this to verify DNSSEC chain-of-trust setup. Empty array = DNSSEC not configured.",
+    inputSchema: {
+        domain: z.string().min(3).describe("Fully qualified domain name, e.g. `example.com`"),
+    },
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    handler: async (config, args) => {
+        const domain = String(args.domain).toLowerCase();
+        return await call(config, `/dns/getDnssecRecords/${encodeURIComponent(domain)}`, {
+            method: "GET",
+        });
+    },
+};
+const list_transfers = {
+    name: "list_transfers",
+    description: "List all in-progress and recent inbound domain transfers for the authenticated account. Returns each transfer's domain, status (`NEW`, `PENDINGAUTH`, `PENDINGSUBMIT`, `PENDINGTRANSFER`, `DONE`, `CANCELED`, etc.), and create date. Use this to monitor transfers initiated by `transfer_domain`.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    handler: async (config) => {
+        return await call(config, "/domain/listTransfers", { method: "GET" });
+    },
+};
+const get_transfer_status = {
+    name: "get_transfer_status",
+    description: "Get the status of a specific inbound transfer for a domain. Useful for polling after `transfer_domain` to know when the transfer completes (typical window: 5-7 days). Returns the same status values as `list_transfers`, plus a human-readable description.",
+    inputSchema: {
+        domain: z.string().min(3).describe("Domain whose transfer status to check, e.g. `example.com`"),
+    },
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    handler: async (config, args) => {
+        const domain = String(args.domain).toLowerCase();
+        return await call(config, `/domain/getTransfer/${encodeURIComponent(domain)}`, {
+            method: "GET",
+        });
+    },
+};
+const list_marketplace = {
+    name: "list_marketplace",
+    description: "Browse domains for sale on the Porkbun marketplace (aftermarket — domains owned by other users, not new registrations). Returns each listing's domain, TLD, SLD length, price (in USD), and listing date.\n\nFilters (all optional, server-side, mirroring the porkbun.com/marketplace UI):\n- `query`: SLD substring match. Multi-word queries: prefix a word with `-` to exclude it (e.g. `\"ai -test\"` matches SLDs containing 'ai' but not 'test').\n- `tlds`: limit to a list of TLDs (without the leading dot).\n- `sld_length_min`, `sld_length_max`: SLD character length bounds.\n- `sort_name`: `domain` | `tld` | `price` | `sld_length`.\n- `sort_direction`: `asc` | `desc`.\n\nWhen any filter is set, server returns up to 1000 matching listings. With no filters, supports raw pagination via `start` / `limit` (max 5000).",
+    inputSchema: {
+        query: z.string().optional().describe("SLD substring search. Use `-word` to exclude. Example: `'ai -test'`."),
+        tlds: z
+            .array(z.string())
+            .optional()
+            .describe("Limit to these TLDs (no leading dot). Example: `['com', 'io', 'ai']`."),
+        sld_length_min: z.number().int().min(1).optional().describe("Minimum SLD character length."),
+        sld_length_max: z.number().int().min(1).optional().describe("Maximum SLD character length."),
+        sort_name: z
+            .enum(["domain", "tld", "price", "sld_length"])
+            .optional()
+            .describe("Sort field. Default: `sld_length` asc when query is set, else `create_date` desc."),
+        sort_direction: z.enum(["asc", "desc"]).optional().describe("Sort direction."),
+        start: z.number().int().min(0).optional().describe("Pagination offset (no-filter mode only). Default 0."),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(5000)
+            .optional()
+            .describe("Page size (no-filter mode only). Default 1000, max 5000."),
+    },
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    handler: async (config, args) => {
+        const body = {};
+        if (args.query !== undefined)
+            body.query = args.query;
+        if (Array.isArray(args.tlds) && args.tlds.length)
+            body.tlds = args.tlds;
+        if (args.sld_length_min !== undefined)
+            body.sldLengthMin = args.sld_length_min;
+        if (args.sld_length_max !== undefined)
+            body.sldLengthMax = args.sld_length_max;
+        if (args.sort_name !== undefined)
+            body.sortName = args.sort_name;
+        if (args.sort_direction !== undefined)
+            body.sortDirection = args.sort_direction;
+        if (args.start !== undefined)
+            body.start = args.start;
+        if (args.limit !== undefined)
+            body.limit = args.limit;
+        return await call(config, "/marketplace/getAll", { method: "POST", body });
+    },
+};
+const get_api_settings = {
+    name: "get_api_settings",
+    description: "Get the authenticated account's API spend control configuration: monthly spend limit, low-balance alert threshold, auto top-up settings, and current month's API spend total. All amounts are in cents. Useful for an agent to check budget headroom before initiating expensive operations — `register_domain` will be hard-blocked if it would push monthly spend over the configured limit.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    handler: async (config) => {
+        return await call(config, "/account/apiSettings", { method: "GET" });
+    },
+};
+const list_glue_records = {
+    name: "list_glue_records",
+    description: "List glue records for a domain. Glue records associate a host (e.g. `ns1.example.com`) with one or more IP addresses at the registry, used when running your own nameservers on the same domain they serve. Returns the host, IPv4 addresses, and IPv6 addresses for each glue record.",
+    inputSchema: {
+        domain: z.string().min(3).describe("Domain to list glue records for, e.g. `example.com`"),
+    },
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    handler: async (config, args) => {
+        const domain = String(args.domain).toLowerCase();
+        return await call(config, `/domain/getGlue/${encodeURIComponent(domain)}`, { method: "GET" });
+    },
+};
+const create_glue_record = {
+    name: "create_glue_record",
+    description: "Create a glue record for a host on a domain. Used when running your own nameservers on the same domain they serve (e.g. `ns1.example.com` serving `example.com`). The `subdomain` is just the host part (e.g. `ns1`), not the full FQDN. Provide IPs as an array of IPv4 and/or IPv6 addresses. Idempotent.",
+    inputSchema: {
+        domain: z.string().min(3).describe("Parent domain, e.g. `example.com`"),
+        subdomain: z
+            .string()
+            .min(1)
+            .describe("Host portion only (no domain), e.g. `ns1`."),
+        ips: z
+            .array(z.string().min(7))
+            .min(1)
+            .describe("Array of IPv4 and/or IPv6 addresses to associate with the host."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (config, args) => {
+        const domain = String(args.domain).toLowerCase();
+        const subdomain = String(args.subdomain).toLowerCase();
+        return await call(config, `/domain/createGlue/${encodeURIComponent(domain)}/${encodeURIComponent(subdomain)}`, { method: "POST", idempotent: true, body: { ips: args.ips } });
+    },
+};
+const update_glue_record = {
+    name: "update_glue_record",
+    description: "Update the IP addresses associated with an existing glue record. Replaces the full IP list — pass all IPs you want set, not just additions. Idempotent.",
+    inputSchema: {
+        domain: z.string().min(3).describe("Parent domain, e.g. `example.com`"),
+        subdomain: z.string().min(1).describe("Host portion only, e.g. `ns1`."),
+        ips: z
+            .array(z.string().min(7))
+            .min(1)
+            .describe("Full replacement set of IPv4/IPv6 addresses for the host."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (config, args) => {
+        const domain = String(args.domain).toLowerCase();
+        const subdomain = String(args.subdomain).toLowerCase();
+        return await call(config, `/domain/updateGlue/${encodeURIComponent(domain)}/${encodeURIComponent(subdomain)}`, { method: "POST", idempotent: true, body: { ips: args.ips } });
+    },
+};
+const delete_glue_record = {
+    name: "delete_glue_record",
+    description: "Delete a glue record by host on a domain. Idempotent: deleting a non-existent glue record returns success.",
+    inputSchema: {
+        domain: z.string().min(3).describe("Parent domain, e.g. `example.com`"),
+        subdomain: z.string().min(1).describe("Host portion only, e.g. `ns1`."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    handler: async (config, args) => {
+        const domain = String(args.domain).toLowerCase();
+        const subdomain = String(args.subdomain).toLowerCase();
+        return await call(config, `/domain/deleteGlue/${encodeURIComponent(domain)}/${encodeURIComponent(subdomain)}`, { method: "POST", idempotent: true });
+    },
+};
+// ─── Domain lifecycle (write — these spend account credit) ──────────────────
+const DNS_RECORD_TYPES = [
+    "A",
+    "AAAA",
+    "CNAME",
+    "MX",
+    "TXT",
+    "NS",
+    "ALIAS",
+    "SRV",
+    "TLSA",
+    "CAA",
+    "HTTPS",
+    "SVCB",
+];
+const register_domain = {
+    name: "register_domain",
+    description: "**Spends account credit.** Registers a new domain on the authenticated Porkbun account. The `cost` parameter must exactly match the current registration price returned by `check_domain` (in cents) — Porkbun rejects mismatched quotes. Workflow: call `check_domain` first to get availability + price, confirm the spend with the user, then call this. The order is idempotency-safe: retries within 24 hours via the same Idempotency-Key return the original response without re-charging. Premium domains, .uk, and a handful of registry-specific TLDs cannot be registered via API and must be done on the website. The account's email and phone number must be verified, and the account must have at least one prior registration order before this works.",
+    inputSchema: {
+        domain: z
+            .string()
+            .min(3)
+            .describe("Fully qualified domain name to register, e.g. `example.com`"),
+        cost: z
+            .number()
+            .int()
+            .positive()
+            .describe("Registration price in cents. Must match the value returned by `check_domain` for this domain (multiplied by years if duration > 1)."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (config, args) => {
+        const domain = String(args.domain).toLowerCase();
+        return await call(config, `/domain/create/${encodeURIComponent(domain)}`, {
+            method: "POST",
+            idempotent: true,
+            body: {
+                cost: Number(args.cost),
+                agreeToTerms: "yes",
+            },
+        });
+    },
+};
+const renew_domain = {
+    name: "renew_domain",
+    description: "**Spends account credit.** Renews an existing domain in the authenticated account. The `cost` parameter must exactly match the current renewal price returned by `check_domain` (in cents). The domain must be opted in to API access (per-domain or global toggle in account settings). Domains registered within the last 30 days, or already renewed within the last 30 days, cannot be renewed yet — the API returns `RENEWAL_TOO_SOON`. Premium domain renewals are not supported via API. Idempotency-safe: retries within 24 hours don't double-charge.",
+    inputSchema: {
+        domain: z.string().min(3).describe("Domain name to renew, e.g. `example.com`. Must already be in your account."),
+        cost: z
+            .number()
+            .int()
+            .positive()
+            .describe("Renewal price in cents. Must match the value returned by `check_domain`."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (config, args) => {
+        const domain = String(args.domain).toLowerCase();
+        return await call(config, `/domain/renew/${encodeURIComponent(domain)}`, {
+            method: "POST",
+            idempotent: true,
+            body: { cost: Number(args.cost) },
+        });
+    },
+};
+const transfer_domain = {
+    name: "transfer_domain",
+    description: "**Spends account credit.** Initiates a transfer of an external domain into Porkbun. Returns immediately with a `transferId`; the actual registry transfer takes 5-7 days for most TLDs. Use `get_transfer_status` to poll. Requires the auth/EPP code from the losing registrar. The `cost` must match the current transfer price from `check_domain`. .uk domains and a few TLDs do not support inbound API transfers. Idempotency-safe.",
+    inputSchema: {
+        domain: z.string().min(3).describe("Domain to transfer in, e.g. `example.com`"),
+        cost: z
+            .number()
+            .int()
+            .positive()
+            .describe("Transfer price in cents. Must match the value returned by `check_domain`."),
+        auth_code: z
+            .string()
+            .min(1)
+            .describe("Authorization (EPP) code from the losing registrar."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (config, args) => {
+        const domain = String(args.domain).toLowerCase();
+        return await call(config, `/domain/transfer/${encodeURIComponent(domain)}`, {
+            method: "POST",
+            idempotent: true,
+            body: {
+                cost: Number(args.cost),
+                authCode: String(args.auth_code),
+            },
+        });
+    },
+};
+const update_auto_renew = {
+    name: "update_auto_renew",
+    description: "Turn auto-renewal on or off for a domain in the authenticated account. When auto-renew is on, Porkbun automatically charges your account credit at expiration. When off, you must manually renew or the domain expires. Idempotent.",
+    inputSchema: {
+        domain: z.string().min(3).describe("Domain to update, e.g. `example.com`"),
+        status: z
+            .enum(["on", "off"])
+            .describe("`on` enables auto-renew, `off` disables it."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (config, args) => {
+        const domain = String(args.domain).toLowerCase();
+        return await call(config, `/domain/updateAutoRenew/${encodeURIComponent(domain)}`, {
+            method: "POST",
+            idempotent: true,
+            body: { status: args.status },
+        });
+    },
+};
+// ─── DNS writes ─────────────────────────────────────────────────────────────
+const create_dns_record = {
+    name: "create_dns_record",
+    description: "Create a DNS record on a domain in the authenticated account. Returns the new record's `id` so it can be referenced by `update_dns_record` and `delete_dns_record`. For the `name` field: omit or pass empty string for the apex/root, otherwise pass the subdomain prefix only (e.g. `www`, not `www.example.com`). For MX and SRV records, set `prio` (priority). Free, doesn't spend account credit.",
+    inputSchema: {
+        domain: z.string().min(3).describe("Domain to add the record to, e.g. `example.com`"),
+        type: z
+            .enum(DNS_RECORD_TYPES)
+            .describe("Record type. Common: A, AAAA, CNAME, MX, TXT."),
+        content: z
+            .string()
+            .min(1)
+            .describe("Record value (e.g. an IP for A, a hostname for CNAME, the text body for TXT)."),
+        name: z
+            .string()
+            .optional()
+            .describe("Subdomain prefix (no domain). Empty string or omitted = apex. Examples: `www`, `mail`, `api.staging`."),
+        ttl: z
+            .number()
+            .int()
+            .min(60)
+            .optional()
+            .describe("Time-to-live in seconds. Minimum 60. Defaults to 600 if omitted."),
+        prio: z
+            .number()
+            .int()
+            .min(0)
+            .optional()
+            .describe("Priority — required for MX and SRV records, ignored otherwise."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (config, args) => {
+        const domain = String(args.domain).toLowerCase();
+        const body = {
+            type: args.type,
+            content: args.content,
+        };
+        if (args.name !== undefined)
+            body.name = args.name;
+        if (args.ttl !== undefined)
+            body.ttl = String(args.ttl);
+        if (args.prio !== undefined)
+            body.prio = String(args.prio);
+        return await call(config, `/dns/create/${encodeURIComponent(domain)}`, {
+            method: "POST",
+            idempotent: true,
+            body,
+        });
+    },
+};
+const update_dns_record = {
+    name: "update_dns_record",
+    description: "Update an existing DNS record by its numeric `record_id` (obtained from `list_dns_records`). All fields except `record_id` and `domain` are optional — pass only the ones you want to change. Idempotent: applying the same update twice is a no-op.",
+    inputSchema: {
+        domain: z.string().min(3).describe("Domain the record belongs to, e.g. `example.com`"),
+        record_id: z
+            .string()
+            .min(1)
+            .describe("Numeric record ID (as a string). Get this from `list_dns_records`."),
+        type: z.enum(DNS_RECORD_TYPES).optional().describe("New record type (rarely changed)."),
+        content: z.string().min(1).optional().describe("New record value."),
+        name: z.string().optional().describe("New subdomain prefix (empty string = apex)."),
+        ttl: z.number().int().min(60).optional().describe("New TTL in seconds."),
+        prio: z.number().int().min(0).optional().describe("New priority (MX/SRV only)."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (config, args) => {
+        const domain = String(args.domain).toLowerCase();
+        const recordId = String(args.record_id);
+        const body = {};
+        if (args.type !== undefined)
+            body.type = args.type;
+        if (args.content !== undefined)
+            body.content = args.content;
+        if (args.name !== undefined)
+            body.name = args.name;
+        if (args.ttl !== undefined)
+            body.ttl = String(args.ttl);
+        if (args.prio !== undefined)
+            body.prio = String(args.prio);
+        return await call(config, `/dns/edit/${encodeURIComponent(domain)}/${encodeURIComponent(recordId)}`, { method: "POST", idempotent: true, body });
+    },
+};
+const delete_dns_record = {
+    name: "delete_dns_record",
+    description: "Delete a single DNS record by its numeric `record_id` (obtained from `list_dns_records`). Idempotent: deleting an already-deleted record returns success. Free.",
+    inputSchema: {
+        domain: z.string().min(3).describe("Domain the record belongs to, e.g. `example.com`"),
+        record_id: z.string().min(1).describe("Numeric record ID (as a string)."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    handler: async (config, args) => {
+        const domain = String(args.domain).toLowerCase();
+        const recordId = String(args.record_id);
+        return await call(config, `/dns/delete/${encodeURIComponent(domain)}/${encodeURIComponent(recordId)}`, { method: "POST", idempotent: true });
+    },
+};
+// ─── DNSSEC writes ──────────────────────────────────────────────────────────
+const create_dnssec_record = {
+    name: "create_dnssec_record",
+    description: "Submit a DNSSEC DS record to the registry for a domain. Use when you sign DNS yourself (custom nameservers running BIND/Knot/PowerDNS/etc.) and need to publish the chain-of-trust at the parent zone. Required: keyTag, algorithm, digestType, digest. Optional key-data fields for registries that require full DNSKEY (rare).",
+    inputSchema: {
+        domain: z.string().min(3).describe("Domain to add the DS record to."),
+        keyTag: z.string().describe("DNSSEC key tag (16-bit identifier of the key)."),
+        alg: z
+            .string()
+            .describe("Algorithm number, e.g. `13` for ECDSA P-256 SHA-256, `8` for RSA SHA-256."),
+        digestType: z.string().describe("Digest type, e.g. `2` for SHA-256, `4` for SHA-384."),
+        digest: z.string().describe("Hex-encoded DS digest value."),
+        maxSigLife: z.string().optional().describe("Maximum signature lifetime in seconds (registry-specific, optional)."),
+        keyDataFlags: z.string().optional().describe("DNSKEY flags (optional — typically 256 or 257)."),
+        keyDataProtocol: z.string().optional().describe("DNSKEY protocol (optional — almost always 3)."),
+        keyDataAlgo: z.string().optional().describe("DNSKEY algorithm (optional)."),
+        keyDataPubKey: z.string().optional().describe("Base64-encoded public key (optional)."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (config, args) => {
+        const domain = String(args.domain).toLowerCase();
+        const body = {
+            keyTag: args.keyTag,
+            alg: args.alg,
+            digestType: args.digestType,
+            digest: args.digest,
+        };
+        for (const k of ["maxSigLife", "keyDataFlags", "keyDataProtocol", "keyDataAlgo", "keyDataPubKey"]) {
+            if (args[k] !== undefined)
+                body[k] = args[k];
+        }
+        return await call(config, `/dns/createDnssecRecord/${encodeURIComponent(domain)}`, {
+            method: "POST",
+            idempotent: true,
+            body,
+        });
+    },
+};
+const delete_dnssec_record = {
+    name: "delete_dnssec_record",
+    description: "Remove a DNSSEC DS record from the registry for a domain, identified by key tag. Use when retiring a key. Idempotent: deleting a non-existent key tag returns success.",
+    inputSchema: {
+        domain: z.string().min(3).describe("Domain to remove the DS record from."),
+        keyTag: z.string().describe("Key tag of the DS record to remove (from `list_dnssec_records`)."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    handler: async (config, args) => {
+        const domain = String(args.domain).toLowerCase();
+        const keyTag = String(args.keyTag);
+        return await call(config, `/dns/deleteDnssecRecord/${encodeURIComponent(domain)}/${encodeURIComponent(keyTag)}`, { method: "POST", idempotent: true });
+    },
+};
+// ─── URL forwarding writes ──────────────────────────────────────────────────
+const create_url_forward = {
+    name: "create_url_forward",
+    description: "Add a URL forwarding rule for a domain. Forwards a subdomain (or apex if `subdomain` is empty/omitted) to an arbitrary destination URL. Useful for redirects without setting up a web server. Free.",
+    inputSchema: {
+        domain: z.string().min(3).describe("Domain to add the forward to, e.g. `example.com`"),
+        location: z
+            .string()
+            .url()
+            .describe("Destination URL to forward visitors to, e.g. `https://newsite.example.com`"),
+        type: z
+            .enum(["permanent", "temporary"])
+            .describe("`permanent` sends HTTP 301 (browsers cache); `temporary` is the configurable default redirect."),
+        includePath: z
+            .enum(["yes", "no"])
+            .describe("`yes` appends the request URI path to the forward target; `no` always sends to the bare destination."),
+        wildcard: z
+            .enum(["yes", "no"])
+            .describe("`yes` also forwards all sub-subdomains; `no` forwards only the exact subdomain."),
+        subdomain: z
+            .string()
+            .optional()
+            .describe("Subdomain prefix to forward. Empty/omitted = the apex (root domain). Examples: `www`, `shop`."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (config, args) => {
+        const domain = String(args.domain).toLowerCase();
+        const body = {
+            location: args.location,
+            type: args.type,
+            includePath: args.includePath,
+            wildcard: args.wildcard,
+        };
+        if (args.subdomain !== undefined)
+            body.subdomain = args.subdomain;
+        return await call(config, `/domain/addUrlForward/${encodeURIComponent(domain)}`, {
+            method: "POST",
+            idempotent: true,
+            body,
+        });
+    },
+};
+const delete_url_forward = {
+    name: "delete_url_forward",
+    description: "Delete a URL forwarding rule by its `id` (obtained from `list_url_forwards`). Idempotent.",
+    inputSchema: {
+        domain: z.string().min(3).describe("Domain the forward belongs to."),
+        record_id: z
+            .string()
+            .min(1)
+            .describe("Numeric forward record ID from `list_url_forwards`."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    handler: async (config, args) => {
+        const domain = String(args.domain).toLowerCase();
+        const recordId = String(args.record_id);
+        return await call(config, `/domain/deleteUrlForward/${encodeURIComponent(domain)}/${encodeURIComponent(recordId)}`, { method: "POST", idempotent: true });
+    },
+};
+// ─── Nameservers ────────────────────────────────────────────────────────────
+const update_nameservers = {
+    name: "update_nameservers",
+    description: "Replace the nameservers for a domain in the authenticated account. **This is a full replacement, not an append** — the supplied list becomes the complete set of nameservers. Most TLDs require 2-13 entries. Setting custom nameservers disables Porkbun's free DNS hosting for the domain. Idempotent: applying the same NS list twice is a no-op.",
+    inputSchema: {
+        domain: z.string().min(3).describe("Domain to update, e.g. `example.com`"),
+        nameservers: z
+            .array(z.string().min(3))
+            .min(2)
+            .max(13)
+            .describe("Full list of nameservers (e.g. `['ns1.example.com', 'ns2.example.com']`). Minimum 2, maximum 13."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    handler: async (config, args) => {
+        const domain = String(args.domain).toLowerCase();
+        return await call(config, `/domain/updateNs/${encodeURIComponent(domain)}`, {
+            method: "POST",
+            idempotent: true,
+            body: { ns: args.nameservers },
+        });
+    },
+};
 export const tools = [
+    // read — global / account
     ping,
     check_domain,
+    get_pricing,
+    list_marketplace,
     list_domains,
     get_balance,
-    get_pricing,
+    get_api_settings,
+    // read — per-domain
+    get_nameservers,
     list_dns_records,
+    list_dnssec_records,
+    list_url_forwards,
+    list_glue_records,
+    list_transfers,
+    get_transfer_status,
     get_ssl_bundle,
+    // write — domain lifecycle (spend account credit)
+    register_domain,
+    renew_domain,
+    transfer_domain,
+    // write — domain settings
+    update_auto_renew,
+    update_nameservers,
+    // write — DNS
+    create_dns_record,
+    update_dns_record,
+    delete_dns_record,
+    // write — DNSSEC
+    create_dnssec_record,
+    delete_dnssec_record,
+    // write — URL forwarding
+    create_url_forward,
+    delete_url_forward,
+    // write — glue records
+    create_glue_record,
+    update_glue_record,
+    delete_glue_record,
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porkbunllc/mcp-server",
-  "version": "0.1.1",
+  "version": "0.3.2",
   "description": "Porkbun MCP server — exposes the Porkbun v3 API as tools for AI agents (Claude Desktop, Cursor, etc.)",
   "type": "module",
   "bin": {
@@ -15,6 +15,7 @@
     "build": "tsc",
     "start": "node dist/index.js",
     "dev": "tsc --watch",
+    "smoke": "node scripts/smoke.mjs",
     "prepublishOnly": "rm -rf dist && tsc"
   },
   "keywords": [