@porkbunllc/mcp-server 0.2.0 → 0.3.2

package/README.md

@@ -2,38 +2,59 @@
 
 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.2 — full domain lifecycle (register, renew, transfer) plus DNS and nameserver writes. All write operations attach an `Idempotency-Key` automatically, so retries within 24 hours don't double-charge.
+> **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.2)
+## What's included (v0.3.1 — 30 tools)
 
-**Read 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 |
 
-**Write tools (spend account credit — register/renew/transfer)**
+**Domain lifecycle writes (spend account credit)**
 
 | Tool | Description |
 |---|---|
-| `register_domain` | Register a new domain — workflow: `check_domain` first to confirm price |
+| `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) |
 
-**DNS and nameserver writes (free)**
+**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 |
-| `update_nameservers` | Replace the nameserver list for a domain (full replace, not append) |
+| `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
 

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.2.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.

package/dist/tools.js

@@ -101,6 +101,190 @@ const get_ssl_bundle = {
         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",
@@ -192,6 +376,25 @@ const transfer_domain = {
         });
     },
 };
+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",
@@ -289,6 +492,117 @@ const delete_dns_record = {
         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",
@@ -312,22 +626,42 @@ const update_nameservers = {
     },
 };
 export const tools = [
-    // read
+    // 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
+    // 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 — nameservers
-    update_nameservers,
+    // 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.2.0",
+  "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": {