brewpage-mcp 1.20.0 → 1.22.0

package/README.md

@@ -38,7 +38,7 @@ Claude Code: `claude mcp add --transport http brewpage --scope user https://brew
 For clients that only start local servers; the same tools as the server URL.
 
 ```bash
-npx -y brewpage-mcp@1.20.0
+npx -y brewpage-mcp@1.22.0
 ```
 
 Requires Node.js 20 or newer. This starts the stdio server for an MCP client.
@@ -63,7 +63,7 @@ Local fallback (stdio, needs Node.js; the same tools): add to `~/Library/Applica
   "mcpServers": {
     "brewpage": {
       "command": "npx",
-      "args": ["-y", "brewpage-mcp@1.20.0"]
+      "args": ["-y", "brewpage-mcp@1.22.0"]
     }
   }
 }
@@ -86,7 +86,7 @@ Custom servers follow your ChatGPT plan and workspace settings.
 The remote command above is the default. Local fallback: register a project-scoped stdio server:
 
 ```bash
-claude mcp add --transport stdio --scope project brewpage -- npx -y brewpage-mcp@1.20.0
+claude mcp add --transport stdio --scope project brewpage -- npx -y brewpage-mcp@1.22.0
 ```
 
 This writes `.mcp.json` in the project root. Use `--scope user` for user-scoped registration. See the [official Claude Code MCP guide](https://code.claude.com/docs/en/mcp).
@@ -110,7 +110,7 @@ Local fallback (stdio, needs Node.js; the same tools): open **Settings > MCP** a
   "mcpServers": {
     "brewpage": {
       "command": "npx",
-      "args": ["-y", "brewpage-mcp@1.20.0"]
+      "args": ["-y", "brewpage-mcp@1.22.0"]
     }
   }
 }
@@ -124,7 +124,7 @@ Open the Cline MCP settings panel and add:
 {
   "brewpage": {
     "command": "npx",
-    "args": ["-y", "brewpage-mcp@1.20.0"]
+    "args": ["-y", "brewpage-mcp@1.22.0"]
   }
 }
 ```
@@ -156,14 +156,14 @@ Thirty-two tools are available. Creation returns an owner token; keep it to modi
 | `bind_token` | Add an owner token to your profile (admin token) |
 | `mint_token` | Mint a profile token, shown once (admin token) |
 | `set_domain` | Connect a domain you own to an HTML page or site; returns the DNS records to create |
-| `list_domains` | List the profile's custom domains with status and DNS records (admin token) |
-| `check_domain` | Check a custom domain's DNS now; status `pending_dns` -> `verifying` -> `active` |
+| `list_domains` | Read one custom domain's status and DNS records without a check, or list the profile's custom domains (admin token) |
+| `check_domain` | Run a DNS check once the records exist; status `pending_dns` -> `verifying` -> `active` |
 | `remove_domain` | Remove a custom domain and free its slot; the BrewPage link keeps working |
 | `get_page_data` | Read what visitors saved on your page: the settings and usage, or one list's entries |
 | `set_page_data` | Write author entries (for example today's menu) without republishing the page |
 | `configure_page_data` | Change who can read a list and its limits; only what you name changes |
 | `delete_page_data` | Delete entries by id, or every entry in a time range |
-| `get_guide` | Read the short Page data guide before writing a page that saves data |
+| `get_guide` | Read a short guide: Page data before writing a page that saves data, or the custom-domain steps |
 | `search_gallery` | Browse public content or list owned resources |
 | `get_stats` | Read platform-wide statistics |
 | `get_limits` | Read the current upload limits (`GET /api/limits`) |
@@ -510,37 +510,48 @@ Parameters: `label` (optional), `scope` (`publish` default | `admin`), `expiresI
 
 ### Custom domains
 
-Show one HTML page (format html, no password) or one site on a domain you own, such as `www.example.com` or `example.com`. Free, 5 per profile. The owner token must be in a free BrewPage profile: sign in at https://account.brewpage.app and add the token there, or with `bind_token`. The BrewPage link keeps working.
+Show one HTML page (format html, no password) or one site on a domain you own, such as `www.example.com` or `example.com`. Free, up to 5 per profile. A profile token works at once; an owner token must first be added to a free BrewPage profile: sign in at https://account.brewpage.app/tokens, press Add existing token and paste it (or `bind_token` with an admin profile token). Any registrar or DNS host works; if you are buying a domain, Cloudflare and Porkbun are the quickest to set up. The BrewPage link keeps working.
 
-How it goes: `set_domain` returns the DNS records, the domain owner creates exactly those records at their DNS provider, then `check_domain` reports the status: `pending_dns` (records not seen yet), `verifying` (DNS found, HTTPS being issued), `active` (live). HTTPS is issued automatically. The records come from the result, never from memory: a subdomain takes a TXT record at `_brewpage.<host>` plus a CNAME to `domains.brewpage.app`; a root domain takes the TXT record plus the A record shown, or the optional ALIAS row.
+How it goes:
 
-`publish_html` and `publish_site` accept an optional `domain` to connect it while publishing. The publication is always created; the result prints a `CUSTOM DOMAIN` block with the records, or says the domain was not set next to the notice that explains why.
+1. `set_domain` returns the DNS records. They come from the result, never from memory: a subdomain takes a TXT record at `_brewpage.<host>` plus a CNAME to `domains.brewpage.app`; a root domain takes the TXT record plus the A record shown, or the optional ALIAS row.
+2. The domain owner creates exactly those records at their DNS provider: MX (mail) records stay, an A, AAAA or CNAME record at the same name is replaced, and at Cloudflare Proxy status is set to DNS only.
+3. After the records exist, `check_domain` once.
+4. `list_domains` with the same `type`, `namespace` and `id` reads the status without a new check until it is `active`. BrewPage checks on its own (the first full check about 15 minutes after adding); the domain is usually live within 30 minutes and HTTPS is issued automatically. Another `check_domain` is needed only after a DNS change.
+
+Statuses: `pending_dns` (records not seen yet), `verifying` (DNS found, HTTPS being issued), `active` (live), `lost` (the records broke after going live; the domain is still served until `graceEndsAt`: restore the records and check again). The `Problem:` line of a result names what blocks progress and its fix; a refusal names its next step. The same steps are in `get_guide(topic="custom-domain")` for the assistant.
+
+`publish_html` and `publish_site` accept an optional `domain` to connect it while publishing. The publication is always created; the result prints a `CUSTOM DOMAIN` block with the records, or says the domain was not set, with the next step, below the notice that explains why.
 
 ### `set_domain`
 
 Connect a domain to an HTML page or site (`PUT /api/publications/{html|site}/{ns}/{id}/domain`). A hostname already in the profile moves to this publication. A page on a BrewPage path address moves to its own subdomain, and its BrewPage link keeps working.
 
-Parameters: `type` (`html` | `site`), `namespace`, `id`, `hostname` (e.g. `www.example.com` or `example.com`), `ownerToken` (optional; the publication's owner token added to a profile, or a profile token).
+Parameters: `type` (`html` | `site`), `namespace`, `id`, `hostname` (a bare hostname such as `www.example.com` or `example.com`, no scheme or path), `ownerToken` (optional; a profile token, or the publication's owner token added to a profile).
 
 ```
 set_domain(type="html", namespace="public", id="aBcDeFgHiJ", hostname="www.example.com")
 ```
 
-Output: `Custom domain connected.`, then `Domain:`, `Status:`, `Problem:` (what is still missing), `Serving:`, `Shows:`, the `records[]` rows verbatim as JSON (`type`, `name`, `host`, `value`, `state`) and the next step. `host` is the name DNS panels ask for.
+Output: `Custom domain added. It is not live until the DNS records below exist.`, then `Domain:`, `Status:`, `Problem:` (what is still missing, with the fix), `Serving:`, `Shows:`, the `records[]` rows verbatim as JSON (`type`, `name`, `host`, `value`, `state`) and the next step. `host` is the name DNS panels ask for.
 
 ---
 
 ### `list_domains`
 
-List the custom domains of a profile (`GET /api/domains`): how many are used and allowed, and for each one its status, DNS records and the publication it shows.
+Read custom domains without running a DNS check. With `type`, `namespace` and `id` (`GET /api/publications/{html|site}/{ns}/{id}/domain`; a profile token or an owner token added to the profile) or with `hostname` (`GET /api/domains/{hostname}`; admin profile token): the status, problem, DNS records and next step of that one custom domain. Without an address (`GET /api/domains`; admin profile token): every custom domain of the profile, plus how many are used and allowed.
+
+Parameters: optional `type` + `namespace` + `id`, or `hostname`; `ownerToken` (optional, default `BREWPAGE_OWNER_TOKEN`, local server only).
 
-Parameters: `ownerToken` (admin token of the profile; optional, default `BREWPAGE_OWNER_TOKEN`, local server only).
+```
+list_domains(type="html", namespace="public", id="aBcDeFgHiJ")
+```
 
 ---
 
 ### `check_domain`
 
-Check DNS now and return the updated status and records. By publication: `type`, `namespace`, `id` with an owner token in the profile (`POST /api/publications/{html|site}/{ns}/{id}/domain/check`). By hostname: `hostname` with an admin token of the profile (`POST /api/domains/{hostname}/check`). Checks are spaced: a repeat too soon answers 429 and the result prints `Retry-After`.
+Run a DNS check now and return the updated status and records. One check after the records exist is enough: BrewPage keeps checking on its own, and `list_domains` reads the status without a check. By publication: `type`, `namespace`, `id` with a profile token or an owner token added to the profile (`POST /api/publications/{html|site}/{ns}/{id}/domain/check`). By hostname: `hostname` with an admin profile token (`POST /api/domains/{hostname}/check`). A repeat within seconds answers 429 and the result prints `Retry-After`.
 
 Parameters: either `type` + `namespace` + `id`, or `hostname`; `ownerToken` (optional).
 
@@ -584,9 +595,9 @@ The four page-data tools below take `namespace` + `id` + `ownerToken`, or `manag
 
 ### `get_guide`
 
-Read a short reference text. Topic `page-data`: how a page saves what visitors enter, with the script calls and the `state` settings. Meant to be read before writing such a page. No API call.
+Read a short reference text. Topic `page-data`: how a page saves what visitors enter, with the script calls and the `state` settings. Meant to be read before writing such a page. Topic `custom-domain`: the steps that put a page or site on a domain you own, with the statuses and the fix for each problem. No API call.
 
-Parameters: `topic` (`page-data`).
+Parameters: `topic` (`page-data` | `custom-domain`).
 
 ---
 
@@ -693,7 +704,8 @@ get_limits()
 | "List my published pages" / "What did I publish?" | `search_gallery` | Set `mine=true` + `ownerToken` |
 | "Browse the public BrewPage gallery" | `search_gallery` | Optional `q`, `sort=date\|views` |
 | "Put this page on my own domain" | `set_domain` | Owner token in a free profile; returns the DNS records to create |
-| "I added the DNS records, is my domain live?" | `check_domain` | Status `pending_dns` -> `verifying` -> `active` |
+| "I added the DNS records" | `check_domain` | Once; status `pending_dns` -> `verifying` -> `active` |
+| "Is my domain live yet?" | `list_domains` | With `type`, `namespace`, `id`: reads the status without a new check |
 | "Which domains do I have?" | `list_domains` | Admin token of the profile |
 | "Disconnect my domain" | `remove_domain` | The BrewPage link keeps working |
 | "Make a page with a guestbook / form / poll that saves answers" | `get_guide`, then `publish_html` | Publish with `state`; give the user the page link and the management link |
@@ -731,12 +743,14 @@ Every publish response includes an **owner token** -- the only credential that a
 - Memory: run with `--max-old-space-size=192` and a 512 MiB container limit.
 - Never reads `BREWPAGE_OWNER_TOKEN`; refuses to start when it is set. Pass `ownerToken` per call.
 - One JSON log line per request on stdout (method, tool, status, outcome, ms); no arguments, tokens or IPs. `SIGTERM` drains for up to 30 s.
+- `GET /metrics` (Prometheus text) only for peers in `BREWPAGE_METRICS_CIDRS`, else 404: `brewpage_mcp_requests_total{method,client}`, `brewpage_mcp_tool_calls_total{tool,client,outcome}` and the gauge `brewpage_mcp_clients_today{client}` (distinct caller addresses with a tool call since 00:00 UTC, kept only as hashes with a random salt drawn each day; resets on restart). `client` is `claude` (an address in `BREWPAGE_SHARED_EGRESS_CIDRS` or a `Claude...` User-Agent), `chatgpt` (an address in a published egress list or an `openai-mcp`/`ChatGPT` User-Agent), else `other`; `outcome` is `ok`, `tool_error`, `error` or `client_closed`. No IPs, arguments or content in any label.
 
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `BREWPAGE_TRUSTED_PROXY_CIDRS` | required | Comma list of reverse-proxy CIDRs or IPs |
 | `BREWPAGE_SHARED_EGRESS_CIDRS` | empty | Comma list of platform egress CIDRs (one IP, many users): global limits only, no per-IP caps |
 | `BREWPAGE_SHARED_EGRESS_LIST_URLS` | empty | Comma list of `https` URLs of published egress lists (`{"prefixes":[{"ipv4Prefix"}]}`, at least 100 prefixes, at most 1 MiB, no redirects); fetched at startup and daily, last good list kept |
+| `BREWPAGE_METRICS_CIDRS` | empty | Comma list of CIDRs or IPs allowed to read `GET /metrics`; empty = `/metrics` answers 404 |
 | `BREWPAGE_BACKEND_URL` | `http://brewpage-backend-mcp:8080` | API base URL (internal address) |
 | `BREWPAGE_PUBLIC_ORIGIN` | `https://brewpage.app` | Origin for returned links and forwarded proto/host |
 | `BREWPAGE_MCP_PORT` | `8787` | Listen port |
@@ -755,6 +769,14 @@ Every publish response includes an **owner token** -- the only credential that a
 
 ## Changelog
 
+## 1.22.0 -- 2026-11-12
+
+- Custom domains: the texts now lead to a connected domain. A refusal names its next step (an owner token in no profile: sign in at https://account.brewpage.app/tokens, press Add existing token, paste it, repeat); results give the DNS records step (mail records stay, a same-name A, AAAA or CNAME is replaced, Cloudflare Proxy status DNS only), one `check_domain`, then status reads until `active`; the `Problem:` line names the fix; status `lost` is described. `list_domains` takes an optional `type` + `namespace` + `id` or `hostname` and reads that one custom domain without a DNS check; without them it lists the profile as before. `get_guide` adds the topic `custom-domain`. Thirty-two tools. Contract 2.28.0. `User-Agent: brewpage-mcp/1.22.0`.
+
+## 1.21.0 -- 2026-11-12
+
+- Remote mode only: optional `GET /metrics` with usage counts for the operator (calls per tool, Claude, ChatGPT or other clients, distinct clients per day), served only to the addresses in `BREWPAGE_METRICS_CIDRS`. No addresses, arguments or content are kept or shown. Tools, inputs and stdio are unchanged: thirty-two tools, contract 2.27.0. `User-Agent: brewpage-mcp/1.21.0`.
+
 ## 1.20.0 -- 2026-11-12
 
 - Two new tools. `make_private` turns a public publication into a private one: new private link, the public link stops working, views and stats stay; one-way. `set_badge` hides or shows the BrewPage badge on a publication of your profile, up to 5 hidden. `set_visibility` reads as list or unlist; inputs unchanged. The server instructions and the tools that send page code say that page code must not hide or alter the badge. Thirty-two tools. Contract 2.27.0. `User-Agent: brewpage-mcp/1.20.0`.

package/dist/guides/custom-domain.d.ts

@@ -0,0 +1,4 @@
+/** Custom-domain statuses: the "Statuses (`status`):" table under "## Custom Domains" of llms-full.txt. */
+export declare const DOMAIN_STATUSES: Record<string, string>;
+/** Custom-domain problems and fixes: the "Problems (`problem`) and the fix:" table of the same section; rows with a <placeholder> key left out. */
+export declare const DOMAIN_PROBLEMS: Record<string, string>;

package/dist/guides/custom-domain.js

@@ -0,0 +1,26 @@
+// Generated by scripts/sync-guide.mjs from brewpage-app frontend/src (llms-full.txt); do not hand-edit.
+/** Custom-domain statuses: the "Statuses (`status`):" table under "## Custom Domains" of llms-full.txt. */
+export const DOMAIN_STATUSES = {
+    "pending_dns": "DNS records not seen yet: create them; `problem` names the missing one",
+    "verifying": "DNS records found, HTTPS being issued: wait",
+    "active": "live at `url` (`serving: true`)",
+    "lost": "DNS records broke after going live; still served until `graceEndsAt`: restore them, then check",
+};
+/** Custom-domain problems and fixes: the "Problems (`problem`) and the fix:" table of the same section; rows with a <placeholder> key left out. */
+export const DOMAIN_PROBLEMS = {
+    "DOMAIN_NOT_REGISTERED": "the domain does not exist yet: register it with a domain registrar, then create the records",
+    "TXT_MISSING": "create the TXT record of `records[]`",
+    "TXT_WRONG": "a `bp-verify=` TXT record has another value: replace it with the one in `records[]`",
+    "ROUTING_MISSING": "create the CNAME record (apex: the A or ALIAS record)",
+    "ROUTING_WRONG": "the name points elsewhere: replace its A or CNAME record (Cloudflare: DNS only)",
+    "FOREIGN_AAAA": "delete the AAAA record listed in `records[]`",
+    "CAA_BLOCKS": "add the CAA record listed in `records[]`",
+    "DOMAIN_TAKEN": "this domain is already connected: use another hostname or write to info@brewpage.app",
+    "QUEUE_FULL": "DNS records are right, verification waits its turn: nothing to do",
+    "CERT_PENDING": "HTTPS certificate on its way: nothing to do",
+    "CERT_FAILED": "the certificate could not be issued: check the DNS records, then check again",
+    "DNS_LOST": "DNS records stayed broken past `graceEndsAt`, so the domain was disconnected: restore them, then check again",
+    "CHECK_PAUSED": "automatic checks paused after a long failure: fix DNS, then check again (resumes them)",
+    "RESOLVER_UNAVAILABLE": "DNS did not answer: retried automatically",
+    "PUBLICATION_GONE": "the publication is gone: connect the custom domain to another one",
+};

package/dist/http.js

@@ -8,6 +8,7 @@ import { pathToFileURL } from "node:url";
 import { createMcpHandler, InMemoryTransport, isLegacyRequest, LATEST_PROTOCOL_VERSION } from "@modelcontextprotocol/server";
 import { NodeStreamableHTTPServerTransport, toWebRequest } from "@modelcontextprotocol/node";
 import { createServer, OWNER_TOKEN_ENV, USER_AGENT } from "./tools.js";
+import { classifyClient, UsageMetrics } from "./metrics.js";
 const MIB = 1024 * 1024;
 /** Fits the largest site (25 MiB backend request: 20 MiB of inline text plus JSON escaping).
  * Two 32 MiB sites + 8x1 MiB + 32 light per round peaked at 373 MiB (heap 192): run with mem_limit 512m. */
@@ -143,6 +144,8 @@ function loadConfig() {
         /** Platform egress (one IP, many users): global pools only, no per-client caps or download budget. */
         sharedEgress: parseCidrs("BREWPAGE_SHARED_EGRESS_CIDRS", false),
         sharedEgressLists: parseListUrls("BREWPAGE_SHARED_EGRESS_LIST_URLS"),
+        /** Peers allowed to read GET /metrics (the Prometheus network); empty = /metrics answers 404. */
+        metricsPeers: parseCidrs("BREWPAGE_METRICS_CIDRS", false),
         host: process.env.BREWPAGE_MCP_HOST || "0.0.0.0",
         port,
     };
@@ -457,7 +460,10 @@ async function main() {
     const heavy = new Pool(MAX_HEAVY_IN_FLIGHT, MAX_HEAVY_PER_CLIENT);
     let draining = false;
     const listed = new Map();
-    let sharedEgress = blockList(config.sharedEgress);
+    const staticEgress = blockList(config.sharedEgress);
+    let listedEgress = blockList([]);
+    const metricsPeers = config.metricsPeers.length > 0 ? blockList(config.metricsPeers) : undefined;
+    const metrics = new UsageMetrics([...toolNames]);
     /** Never throws: a failed fetch or parse keeps the last good set and logs a warning. */
     async function loadEgressList(url) {
         try {
@@ -469,7 +475,7 @@ async function main() {
             }
             const ranges = parseEgressList(await readCapped(res, SHARED_LIST_MAX_BYTES));
             listed.set(url, ranges);
-            sharedEgress = blockList([...config.sharedEgress, ...[...listed.values()].flat()]);
+            listedEgress = blockList([...listed.values()].flat());
             log({ event: "shared_egress_list", url, ranges: ranges.length });
         }
         catch (error) {
@@ -479,7 +485,7 @@ async function main() {
     const refreshEgressLists = () => config.sharedEgressLists.forEach((url) => void loadEgressList(url));
     refreshEgressLists();
     setInterval(refreshEgressLists, SHARED_LIST_REFRESH_MS).unref();
-    async function handleMcp(req, res, entry) {
+    async function handleMcp(req, res, entry, usage) {
         if (req.headers.origin !== undefined)
             return rpcError(res, 403, SERVER_ERROR, "Origin not allowed.");
         const peer = peerAddress(req);
@@ -502,7 +508,9 @@ async function main() {
             rpcError(res, 503, SERVER_ERROR, "Busy, retry shortly.", { "Retry-After": "1" });
         };
         const known = Number.isFinite(declared);
-        const shared = sharedEgress.check(client, isIP(client) === 6 ? "ipv6" : "ipv4");
+        const family = isIP(client) === 6 ? "ipv6" : "ipv4";
+        const egress = staticEgress.check(client, family) ? "static" : listedEgress.check(client, family) ? "listed" : undefined;
+        const shared = egress !== undefined;
         const capKey = shared ? undefined : client;
         // Registered first: a client that leaves at any point, even while queued, aborts the call.
         const abort = new AbortController();
@@ -562,6 +570,8 @@ async function main() {
             const toolName = rpc.method === "tools/call" ? rpc.params?.name : undefined;
             entry.method = typeof rpc.method === "string" ? rpc.method.slice(0, MAX_LOGGED_METHOD) : null;
             entry.tool = rpc.method === "tools/call" ? (typeof toolName === "string" && toolNames.has(toolName) ? toolName : "unknown") : null;
+            usage.client = classifyClient(egress, (req.headers["user-agent"] ?? "").slice(0, MAX_LOGGED_METHOD));
+            usage.address = client;
             // Stateless: no server-push streams, as the 2025 GET stream (405); a refused auto-open never fails a connect.
             if (rpc.method === "subscriptions/listen") {
                 const id = message.id;
@@ -634,18 +644,24 @@ async function main() {
             slot?.give(capKey);
         }
     }
-    function handle(req, res, entry) {
+    function handle(req, res, entry, usage) {
         const path = (req.url ?? "/").split("?")[0];
         if (path === "/healthz") {
             res.writeHead(draining ? 503 : 200, { "Content-Type": "application/json" });
             res.end(JSON.stringify({ status: draining ? "draining" : "ok", version: VERSION }));
             return Promise.resolve();
         }
+        const peer = peerAddress(req);
+        if (path === "/metrics" && req.method === "GET" && isIP(peer) !== 0 && metricsPeers?.check(peer, isIP(peer) === 6 ? "ipv6" : "ipv4")) {
+            res.writeHead(200, { "Content-Type": "text/plain; version=0.0.4; charset=utf-8" });
+            res.end(metrics.render());
+            return Promise.resolve();
+        }
         if (path !== "/mcp") {
             rpcError(res, 404, SERVER_ERROR, "Not found.");
             return Promise.resolve();
         }
-        return handleMcp(req, res, entry).catch((error) => {
+        return handleMcp(req, res, entry, usage).catch((error) => {
             entry.outcome = "exception";
             log({ event: "request_failed", message: error instanceof Error ? error.message : String(error) });
             if (!res.headersSent)
@@ -657,11 +673,12 @@ async function main() {
     const httpServer = createHttpServer((req, res) => {
         const started = performance.now();
         const entry = { http: req.method ?? "", method: null, tool: null, status: 0, outcome: null, ms: 0 };
-        const logged = !(req.url ?? "").startsWith("/healthz");
+        const usage = {};
+        const logged = !(req.url ?? "").startsWith("/healthz") && !(req.url ?? "").startsWith("/metrics");
         const closedEarly = new Promise((resolve) => res.once("close", () => resolve(!res.writableFinished)));
         let done;
         try {
-            done = handle(req, res, entry);
+            done = handle(req, res, entry, usage);
         }
         catch (error) {
             entry.outcome = "exception";
@@ -681,6 +698,11 @@ async function main() {
                 entry.outcome ??= res.statusCode < 400 ? "ok" : `http_${res.statusCode}`;
             entry.ms = Math.round(performance.now() - started);
             log(entry);
+            if (usage.client === undefined || typeof entry.method !== "string")
+                return;
+            metrics.request(entry.method, usage.client);
+            if (typeof entry.tool === "string")
+                metrics.toolCall(entry.tool, usage.client, String(entry.outcome), usage.address);
         });
     });
     // Whole request incl. queue wait: 30 s queue + 2 s grace + 32 MiB at the body floor (~131 s) + margin.

package/dist/metrics.d.ts

@@ -0,0 +1,24 @@
+/** Client class: Claude (Anthropic egress or Claude UA), ChatGPT (OpenAI egress or UA), else other. */
+export type ClientClass = "claude" | "chatgpt" | "other";
+/** Egress source of the caller's IP: static shared CIDRs = Anthropic, published lists = OpenAI (deploy contract). */
+export type Egress = "static" | "listed" | undefined;
+export declare function classifyClient(egress: Egress, userAgent: string): ClientClass;
+/** Bounded outcome label from the request log outcome. */
+export declare function outcomeClass(outcome: string | number | null | undefined): string;
+/** In-memory MCP usage counters in Prometheus text format; labels are closed sets, never IPs or arguments. */
+export declare class UsageMetrics {
+    private readonly tools;
+    private readonly now;
+    private readonly requests;
+    private readonly toolCalls;
+    private day;
+    private salt;
+    private readonly daily;
+    constructor(tools: readonly string[], now?: () => Date);
+    request(method: string, client: ClientClass): void;
+    /** One tools/call; `address` only feeds the daily distinct set as a keyed hash. */
+    toolCall(tool: string, client: ClientClass, outcome: string, address: string): void;
+    render(): string;
+    /** New UTC day: forget every hash and draw a new random salt, so days cannot be linked. */
+    private roll;
+}

package/dist/metrics.js

@@ -0,0 +1,84 @@
+import { createHmac, randomBytes } from "node:crypto";
+const CLIENTS = ["claude", "chatgpt", "other"];
+const METHODS = ["initialize", "notifications/initialized", "tools/list", "tools/call", "ping", "server/discover", "other"];
+const OUTCOMES = ["ok", "tool_error", "error", "client_closed"];
+/** Distinct-client memory bound (~100 bytes each); past it the day's gauge stops growing. */
+const MAX_DAILY_CLIENTS = 100_000;
+export function classifyClient(egress, userAgent) {
+    if (egress === "static" || /^claude/i.test(userAgent))
+        return "claude";
+    if (egress === "listed" || /^openai-mcp|chatgpt/i.test(userAgent))
+        return "chatgpt";
+    return "other";
+}
+/** Bounded outcome label from the request log outcome. */
+export function outcomeClass(outcome) {
+    return outcome === "ok" || outcome === "tool_error" || outcome === "client_closed" ? outcome : "error";
+}
+/** In-memory MCP usage counters in Prometheus text format; labels are closed sets, never IPs or arguments. */
+export class UsageMetrics {
+    tools;
+    now;
+    requests = new Map();
+    toolCalls = new Map();
+    day = "";
+    salt = Buffer.alloc(0);
+    daily = new Map();
+    constructor(tools, now = () => new Date()) {
+        this.tools = tools;
+        this.now = now;
+        // Every series born at 0, so increase() sees the first call after a restart.
+        for (const client of CLIENTS) {
+            for (const method of METHODS)
+                this.requests.set(`${method}\t${client}`, 0);
+            for (const tool of [...tools, "unknown"])
+                for (const outcome of OUTCOMES)
+                    this.toolCalls.set(`${tool}\t${client}\t${outcome}`, 0);
+        }
+    }
+    request(method, client) {
+        const key = `${METHODS.includes(method) ? method : "other"}\t${client}`;
+        this.requests.set(key, (this.requests.get(key) ?? 0) + 1);
+    }
+    /** One tools/call; `address` only feeds the daily distinct set as a keyed hash. */
+    toolCall(tool, client, outcome, address) {
+        const key = `${this.tools.includes(tool) ? tool : "unknown"}\t${client}\t${outcomeClass(outcome)}`;
+        this.toolCalls.set(key, (this.toolCalls.get(key) ?? 0) + 1);
+        this.roll();
+        const seen = this.daily.get(client);
+        if ([...this.daily.values()].reduce((sum, set) => sum + set.size, 0) >= MAX_DAILY_CLIENTS)
+            return;
+        seen.add(createHmac("sha256", this.salt).update(address).digest("base64").slice(0, 22));
+    }
+    render() {
+        this.roll();
+        const lines = [
+            "# HELP brewpage_mcp_requests_total Remote MCP JSON-RPC requests by method and client class.",
+            "# TYPE brewpage_mcp_requests_total counter",
+            ...[...this.requests].map(([key, value]) => {
+                const [method, client] = key.split("\t");
+                return `brewpage_mcp_requests_total{method="${method}",client="${client}"} ${value}`;
+            }),
+            "# HELP brewpage_mcp_tool_calls_total Remote MCP tools/call by tool, client class and outcome.",
+            "# TYPE brewpage_mcp_tool_calls_total counter",
+            ...[...this.toolCalls].map(([key, value]) => {
+                const [tool, client, outcome] = key.split("\t");
+                return `brewpage_mcp_tool_calls_total{tool="${tool}",client="${client}",outcome="${outcome}"} ${value}`;
+            }),
+            "# HELP brewpage_mcp_clients_today Distinct client addresses with a tools/call since 00:00 UTC (since start if later).",
+            "# TYPE brewpage_mcp_clients_today gauge",
+            ...CLIENTS.map((client) => `brewpage_mcp_clients_today{client="${client}"} ${this.daily.get(client).size}`),
+        ];
+        return `${lines.join("\n")}\n`;
+    }
+    /** New UTC day: forget every hash and draw a new random salt, so days cannot be linked. */
+    roll() {
+        const day = this.now().toISOString().slice(0, 10);
+        if (day === this.day)
+            return;
+        this.day = day;
+        this.salt = randomBytes(32);
+        for (const client of CLIENTS)
+            this.daily.set(client, new Set());
+    }
+}

package/dist/tools.d.ts

@@ -1,6 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/server";
 export declare const DEFAULT_BASE_URL = "https://brewpage.app";
-export declare const USER_AGENT = "brewpage-mcp/1.20.0";
+export declare const USER_AGENT = "brewpage-mcp/1.22.0";
 export declare const OWNER_TOKEN_ENV = "BREWPAGE_OWNER_TOKEN";
 /** Server instructions of the handshake: one paragraph per line; the first stands alone within 512 chars. */
 export declare const SERVER_INSTRUCTIONS: string;

package/dist/tools.js

@@ -1,8 +1,9 @@
 import { McpServer } from "@modelcontextprotocol/server";
 import { z } from "zod";
+import { DOMAIN_PROBLEMS, DOMAIN_STATUSES } from "./guides/custom-domain.js";
 import { PAGE_DATA_CALLS, PAGE_DATA_GUIDE } from "./guides/page-data.js";
 export const DEFAULT_BASE_URL = "https://brewpage.app";
-export const USER_AGENT = "brewpage-mcp/1.20.0";
+export const USER_AGENT = "brewpage-mcp/1.22.0";
 export const OWNER_TOKEN_ENV = "BREWPAGE_OWNER_TOKEN";
 /** Server instructions of the handshake: one paragraph per line; the first stands alone within 512 chars. */
 export const SERVER_INSTRUCTIONS = [
@@ -10,6 +11,7 @@ export const SERVER_INSTRUCTIONS = [
     "After publishing, give the user the page link and the management link from the result. Say that the management link is private: whoever has it can edit or delete the page, and its Data tab shows what visitors saved.",
     "KV and JSON tools hold your own data. Page data holds what a page's visitors save: get_page_data reads it, set_page_data writes author entries, configure_page_data changes who can read a list, delete_page_data moderates. In a later chat these four take the management link as manageUrl.",
     "HTML pages and sites show a small BrewPage badge; page code must not hide or alter it. A profile can turn it off on up to 5 pages (set_badge).",
+    "A custom domain, only when the user asks for their own domain: set_domain, the user creates the returned DNS records at their DNS provider, check_domain once, then list_domains reads the status until it is active. Steps and fixes: get_guide topic custom-domain.",
 ].join("\n");
 const READ_ONLY = { readOnlyHint: true };
 const DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true };
@@ -198,32 +200,67 @@ function configuredListLine(name, named, before, after) {
     return after.mode === "shared" ? `${name} - ${listRuleText(after)} (was private)`
         : `${name} - ${listRuleText(after)} (was shared; it cannot become shared again while it holds visitors' entries)`;
 }
-const DOMAIN_PROFILE_TEXT = "Works when the owner token is in a free BrewPage profile (sign-in at https://account.brewpage.app); free, 5 domains per profile.";
-const DOMAIN_ADDRESS_TEXT = "Addressed by publication (type, namespace, id; an owner token in the profile) or by hostname (an admin token of the profile).";
-const DOMAIN_OWNER_TOKEN = `Owner token in a BrewPage profile: the publication's own token added to the profile, or a profile token. Default: ${ENV_DEFAULT}.`;
-const DOMAIN_EITHER_TOKEN = `By publication: an owner token in the profile. By hostname: an admin token of the profile. Default: ${ENV_DEFAULT}.`;
-const DOMAIN_ADDRESS_ERROR = "Provide either `hostname` (admin token of the profile) or `type`, `namespace` and `id` (an owner token in the profile).";
-const DOMAIN_ARGUMENT = "Optional domain the user owns (www.example.com or example.com) to connect to the new publication. " +
-    "Works when the owner token is in a free BrewPage profile, without a password. The publication is always created; " +
-    "the result lists the DNS records for the domain owner to create, or says why the domain was not set.";
-/** Plain words for `DomainItem.problem`; other codes print bare. */
-const DOMAIN_PROBLEMS = {
-    TXT_MISSING: "the TXT record is not visible yet",
-    TXT_WRONG: "the TXT record has another value",
-    ROUTING_MISSING: "the CNAME or A record is not visible yet",
-    ROUTING_WRONG: "the CNAME or A record points elsewhere",
-    FOREIGN_AAAA: "an AAAA record points elsewhere: delete it",
-    CAA_BLOCKS: "a CAA record stops the HTTPS certificate: add the CAA record listed",
-    DOMAIN_TAKEN: "this hostname is not available",
-    QUEUE_FULL: "DNS is right; the next step is queued and retried automatically",
-    CERT_PENDING: "the HTTPS certificate is on its way",
-    CERT_FAILED: "the HTTPS certificate was not issued: check DNS, then check again",
-    DNS_LOST: "the records stayed broken: restore them, then check again",
-    CHECK_PAUSED: "automatic checks are paused; a check resumes them",
-    RESOLVER_UNAVAILABLE: "DNS did not answer; retried automatically",
-    PUBLICATION_GONE: "the publication is gone: set the domain on another one",
+const DOMAIN_TOKENS_PAGE = "https://account.brewpage.app/tokens";
+const DOMAIN_PROFILE_TEXT = `Free with a BrewPage profile, up to 5 custom domains: a profile token works at once, an owner token after it is added to a profile (sign-in at ${DOMAIN_TOKENS_PAGE}, "Add existing token").`;
+const DOMAIN_PROVIDER_TEXT = "Any registrar or DNS host works; if the user is buying a domain, Cloudflare and Porkbun are the quickest to set up.";
+const DOMAIN_ADDRESS_TEXT = "Addressed by publication (type, namespace, id; a profile token or an owner token added to the profile) or by hostname (an admin profile token).";
+const DOMAIN_OWNER_TOKEN = `A profile token, or the publication's owner token added to a BrewPage profile. Default: ${ENV_DEFAULT}.`;
+const DOMAIN_EITHER_TOKEN = `By publication: a profile token or an owner token added to the profile. By hostname: an admin profile token. Default: ${ENV_DEFAULT}.`;
+const DOMAIN_LIST_TOKEN = `Whole list or by hostname: an admin profile token. By publication: a profile token or an owner token added to the profile. Default: ${ENV_DEFAULT}.`;
+const DOMAIN_ADDRESS_ERROR = "Provide either `hostname` (an admin profile token) or `type`, `namespace` and `id` (a profile token or an owner token added to the profile).";
+const DOMAIN_HOSTNAME = "Custom domain as a bare hostname, e.g. www.example.com; instead of type, namespace and id";
+const DOMAIN_ARGUMENT = "Optional custom domain for the new publication: a bare hostname the user owns (www.example.com or example.com, no scheme or path). " +
+    "Needs a profile token or an owner token added to a free BrewPage profile, and no password. The publication is always created; " +
+    "the result lists the DNS records for the domain owner to create, or says why the custom domain was not set.";
+/** Status sentence of the check_domain description; names every key of DOMAIN_STATUSES. */
+const DOMAIN_STATUS_TEXT = "Status: pending_dns (DNS records not seen yet), verifying (DNS records found, HTTPS being issued), active (live), " +
+    "lost (DNS records broke after going live; still served until `graceEndsAt`; restored records and one more check bring it back). `problem` names the fix.";
+/** Next step per `reason` of 409 NOT_ELIGIBLE and per `NOT_ELIGIBLE_<reason>` problem. */
+const DOMAIN_REASONS = {
+    OWNERSHIP: `add its owner token to the profile (bind_token with an admin profile token, or "Add existing token" at ${DOMAIN_TOKENS_PAGE})`,
+    OLD: "it is an old publication: publish it again and connect the custom domain to the new one",
+    RETIRED: "its address was retired: connect the custom domain to a live publication",
+    TYPE: "only HTML pages and sites can",
+    FORMAT: "the page is not format html: publish it as format html",
+    PASSWORD: "remove the password (management link, or POST /api/{html|sites}/{ns}/{id}/password {\"password\":null})",
+    EXPIRED: "it has expired: connect the custom domain to another publication",
+    MODE: "it left its own subdomain: change its hosting back to subdomain (update_hosting deliveryMode=subdomain)",
 };
-const DOMAIN_NEXT_CREATE = "Next: ask the user to add exactly these records at their DNS provider and change nothing else (keep MX/email records); `host` is the name DNS panels ask for. Then call check_domain. BrewPage also checks on its own and issues HTTPS automatically.";
+const DOMAIN_READ_STATUS = "read the status with list_domains (same type, namespace and id, or hostname)";
+const DOMAIN_NEXT_CREATE = "Next: give the user exactly these DNS records to create at their DNS provider (`host` is the name DNS panels ask for). " +
+    "MX/mail records stay; an A, AAAA or CNAME record at the same name is replaced. When the user says the records exist, call check_domain once, then " +
+    DOMAIN_READ_STATUS + " until it is active: BrewPage checks on its own (first full check about 15 minutes after adding), " +
+    "usually live within 30 minutes, HTTPS is automatic. Call check_domain again only after a DNS change.";
+const DOMAIN_NEXT_VERIFYING = "Next: DNS records are found and HTTPS is being issued. To follow it, " + DOMAIN_READ_STATUS +
+    " until it is active; call check_domain again only if the Problem line says so or DNS changed.";
+const DOMAIN_NEXT_LOST = "Next: DNS records broke after going live. Ask the user to restore exactly these DNS records at their DNS provider, then call check_domain once.";
+const DOMAIN_SUSPENDED_TEXT = "BrewPage suspended this custom domain: the user writes to info@brewpage.app; repeating a call does not help.";
+/** Custom-domain guide: the flow in tool words, then the status and problem tables generated from llms-full.txt. */
+const CUSTOM_DOMAIN_GUIDE = [
+    "BrewPage custom domain: a hostname the user owns (example.com, docs.example.com) shows one HTML page of format html or one site, without a password. Only when the user asks for their own domain.",
+    `Who: ${DOMAIN_PROFILE_TEXT}`,
+    "  403 DOMAIN_NEEDS_ACCOUNT = the owner token is in no profile: give the user the owner token (it is theirs) to add there, then repeat the call. With an admin profile token bind_token adds it instead.",
+    `Domain: ${DOMAIN_PROVIDER_TEXT}`,
+    "Steps:",
+    "1) set_domain (type, namespace, id, hostname), or `domain` on publish_html / publish_site. The hostname is bare: www.example.com or example.com, no scheme or path.",
+    "2) Give the user exactly the DNS records of the result to create at their DNS provider (`host` is the name DNS panels ask for); never values from memory.",
+    "   MX/mail records stay; an A, AAAA or CNAME record at the same name is replaced. At Cloudflare set Proxy status to DNS only.",
+    "3) When the user says the records exist: check_domain once.",
+    "4) Read the status with list_domains (type, namespace, id) until it is active. BrewPage checks on its own (first full check about 15 minutes after adding);",
+    "   usually live within 30 minutes, HTTPS is issued automatically. check_domain again only after a DNS change; on 429 wait Retry-After and read instead.",
+    "Statuses (`Status:` line of a result):",
+    ...Object.entries(DOMAIN_STATUSES).map(([status, text]) => `  ${status} - ${text}`),
+    "Problems (`Problem:` line) and the fix:",
+    ...Object.entries(DOMAIN_PROBLEMS).map(([problem, fix]) => `  ${problem} - ${fix}`),
+    "  NOT_ELIGIBLE_<reason> - the publication cannot take a custom domain now; the line names the fix",
+    "A refusal names its next step. The BrewPage link keeps working throughout. set_domain with the same hostname on another publication of the profile moves it; remove_domain removes it.",
+].join("\n") + "\n";
+/** `Problem:` value: the code plus its fix (generated table, or the reason of a `NOT_ELIGIBLE_<reason>` code); other codes print bare. */
+function domainProblemText(problem) {
+    const reason = problem.startsWith("NOT_ELIGIBLE_") ? DOMAIN_REASONS[problem.slice("NOT_ELIGIBLE_".length)] : undefined;
+    const fix = reason ? `the publication cannot take a custom domain now: ${reason}` : DOMAIN_PROBLEMS[problem];
+    return fix ? `${problem} (${fix})` : problem;
+}
 /** One custom domain (`DomainItem`): status, `records[]` verbatim and the next step. */
 function domainLines(item) {
     const { hostname, displayHostname, problem, url } = item;
@@ -233,7 +270,7 @@ function domainLines(item) {
         `Status: ${item.status}`,
     ];
     if (typeof problem === "string" && problem)
-        lines.push(`Problem: ${problem}${DOMAIN_PROBLEMS[problem] ? ` (${DOMAIN_PROBLEMS[problem]})` : ""}`);
+        lines.push(`Problem: ${domainProblemText(problem)}`);
     lines.push(`Serving: ${item.serving === true}`);
     if (item.suspended === true)
         lines.push(`suspended: true`);
@@ -247,7 +284,7 @@ function domainLines(item) {
         lines.push(`The publication moved to its own BrewPage subdomain (a custom domain needs it); its BrewPage link keeps working.`);
     if (typeof item.detached === "string" && item.detached)
         lines.push(`Earlier domain ${item.detached} stays in the profile, not attached.`);
-    for (const [field, label] of [["checkedAt", "Checked"], ["nextCheckAt", "Next automatic check"], ["graceEndsAt", "Shown until"]]) {
+    for (const [field, label] of [["checkedAt", "Checked"], ["nextCheckAt", "Next automatic check"], ["graceEndsAt", "Served until (graceEndsAt)"]]) {
         if (typeof item[field] === "string")
             lines.push(`${label}: ${item[field]}`);
     }
@@ -259,44 +296,83 @@ function domainLines(item) {
     if (item.provider === "cloudflare")
         lines.push(`Cloudflare: Proxy status "DNS only" on the CNAME or A record.`);
     if (item.suspended === true)
-        return lines;
+        return [...lines, DOMAIN_SUSPENDED_TEXT];
+    if (problem === "DOMAIN_NOT_REGISTERED")
+        lines.push(DOMAIN_PROVIDER_TEXT);
+    // The DNS provider is unknown until a check names it, so the Cloudflare rule travels with the step.
     if (item.status === "pending_dns")
-        lines.push(DOMAIN_NEXT_CREATE);
+        lines.push(DOMAIN_NEXT_CREATE + (typeof item.provider === "string" && item.provider ? "" : " At Cloudflare set Proxy status to DNS only."));
     if (item.status === "verifying")
-        lines.push(`Next: DNS is found and HTTPS is being issued. Call check_domain again shortly.`);
+        lines.push(DOMAIN_NEXT_VERIFYING);
     if (item.status === "active")
-        lines.push(`Live: the domain shows the publication over HTTPS. The BrewPage link keeps working.`);
+        lines.push(`Live: the custom domain shows the publication over HTTPS. The BrewPage link keeps working.`);
     if (item.status === "lost")
-        lines.push(`Next: DNS changed after going live. Ask the user to restore exactly these records at their DNS provider, then call check_domain.`);
+        lines.push(DOMAIN_NEXT_LOST);
     return lines;
 }
-/** Create with `domain`: the returned `customDomain`, else a line saying it was not set (the reason is a `domain-*` notice). */
-function publishDomainLines(data, requested) {
+/** 403 `DOMAIN_NEEDS_ACCOUNT` and its create notice: the profile step in the user's hands, then `then`. */
+function domainNeedsProfile(fromEnv, then) {
+    return `The owner token is in no BrewPage profile. Give the user the owner token (it is theirs${fromEnv ? `; it is the ${OWNER_TOKEN_ENV} value in this server's settings` : ""}) ` +
+        `and ask them to sign in at ${DOMAIN_TOKENS_PAGE} (free), press "Add existing token" and paste it; then ${then}. With an admin profile token bind_token adds it instead.`;
+}
+const DOMAIN_LIMIT_NEXT = "remove_domain frees one; a hostname already in the profile moves here with set_domain.";
+/** 409 `DOMAIN_PROFILE_AMBIGUOUS` and its create notice; `then` = the call to make with the profile token. */
+function domainAmbiguous(then) {
+    return `The token is in several profiles: ${then} with a profile token of the profile that should hold the custom domain (minted at ${DOMAIN_TOKENS_PAGE}).`;
+}
+/** Next step per `domain-*` notice of a create; other codes point at the notice text. */
+function publishDomainNext(code, fromEnv) {
+    if (code === "domain-needs-account")
+        return ` ${domainNeedsProfile(fromEnv, "call set_domain for this publication")}`;
+    if (code === "domain-limit-reached")
+        return ` Next: ${DOMAIN_LIMIT_NEXT}`;
+    if (code === "domain-profile-ambiguous")
+        return ` ${domainAmbiguous("call set_domain")}`;
+    if (code === "domain-not-eligible" || code === "domain-invalid")
+        return " The domain notice above says what to fix; then set_domain connects it.";
+    if (code === "domain-account-restricted")
+        return " The domain notice above says why.";
+    return " The domain notice above says why. set_domain connects it later.";
+}
+/** Create with `domain`: the returned `customDomain`, else a line saying it was not set plus the next step of its `domain-*` notice. */
+function publishDomainLines(data, requested, fromEnv = false) {
     const item = data.customDomain;
     if (item && typeof item === "object")
         return [``, `CUSTOM DOMAIN`, ...domainLines(item)];
     if (!requested)
         return [];
-    const reason = notices(data).some((n) => n.code.startsWith("domain-")) ? " The domain notice above says why." : "";
-    return [``, `CUSTOM DOMAIN: ${requested} was not set; the publication is live at its BrewPage link.${reason} set_domain connects it later.`];
+    const notice = notices(data).find((n) => n.code.startsWith("domain-"));
+    return [``, `CUSTOM DOMAIN: ${requested} was not set; the publication is live at its BrewPage link.` +
+            (notice ? publishDomainNext(notice.code, fromEnv) : " set_domain connects it later.")];
 }
-/** Next step after a custom-domain refusal; other codes keep the server answer alone. */
-function domainHints(data, byHostname) {
-    const { code, limit, used } = (data ?? {});
-    if (code === "DOMAIN_NEEDS_ACCOUNT") {
-        return ["Custom domains need a free BrewPage account: sign in at https://account.brewpage.app and add this token to your profile (bind_token), then retry."];
+/** Next step after a custom-domain refusal; `address` = how the call named the domain. Other codes keep the server answer alone. */
+function domainHints(data, address, fromEnv = false) {
+    const { code, limit, used, reason } = (data ?? {});
+    switch (code) {
+        case "DOMAIN_NEEDS_ACCOUNT": return [domainNeedsProfile(fromEnv, "repeat this call")];
+        case "DOMAIN_LIMIT": return typeof limit === "number" && limit > 0
+            ? [`The profile uses ${typeof used === "number" ? used : limit} of ${limit} custom domains: ${DOMAIN_LIMIT_NEXT}`] : [];
+        case "ADMIN_TOKEN_REQUIRED": return ["This call needs an admin profile token." + (address === "publication" ? ""
+                : " With a publish-scope profile token or an owner token added to the profile, pass type, namespace and id" + (address === "hostname" ? " instead of hostname." : "."))];
+        case "DOMAIN_CHECK_TOO_SOON": return [`Checked a moment ago: do not call check_domain again now. BrewPage keeps checking on its own; after Retry-After ${DOMAIN_READ_STATUS}.`];
+        case "DOMAIN_NOT_FOUND": return ["No custom domain there: list_domains shows the profile's custom domains; set_domain connects one."];
+        case "INVALID_HOSTNAME": return ["Pass one bare hostname such as www.example.com or example.com (no scheme, path or port); the message says what to fix."];
+        case "DOMAIN_NOT_ALLOWED": return ["brewpage.app addresses and some domains cannot be used: ask the user for a domain they own."];
+        case "NOT_ELIGIBLE": return typeof reason === "string" && DOMAIN_REASONS[reason] ? [`This publication cannot take a custom domain: ${DOMAIN_REASONS[reason]}.`] : [];
+        case "DOMAIN_PROFILE_AMBIGUOUS": return [domainAmbiguous("repeat")];
+        case "OWNER_TOKEN_REVOKED":
+        case "OWNER_TOKEN_EXPIRED":
+            return [`The token ${code === "OWNER_TOKEN_REVOKED" ? "was revoked" : "expired"}: repeat with another profile token or the publication's owner token.`];
+        case "ACCOUNT_RESTRICTED":
+        case "ACCOUNT_BLOCKED":
+            return [`This profile cannot add custom domains${code === "ACCOUNT_RESTRICTED" ? " now" : ""}: tell the user; repeating the call does not help.`];
+        case "DOMAIN_SUSPENDED": return [DOMAIN_SUSPENDED_TEXT];
+        case "PUBLICATION_UNAVAILABLE": return ["The publication is missing or expired (outside public a wrong token answers the same): check type, namespace, id and the token."];
+        case "FEATURE_DISABLED":
+        case "DOMAIN_INTAKE_PAUSED":
+        case "HOSTING_CREATION_PAUSED": return ["Temporary: tell the user and try again later."];
+        default: return [];
     }
-    if (code === "DOMAIN_LIMIT" && typeof limit === "number" && limit > 0) {
-        return [`The profile uses ${typeof used === "number" ? used : limit} of ${limit} custom domains: remove_domain frees one; a hostname already in the profile moves here with set_domain.`];
-    }
-    if (code === "ADMIN_TOKEN_REQUIRED") {
-        return ["Custom domains need an admin token from a free BrewPage profile." + (byHostname ? " With an owner token of the publication, pass type, namespace and id instead of hostname." : "")];
-    }
-    if (code === "DOMAIN_CHECK_TOO_SOON")
-        return ["Checked a moment ago: wait, then call check_domain again."];
-    if (code === "DOMAIN_NOT_FOUND")
-        return ["No custom domain there: list_domains shows the profile's domains; set_domain connects one."];
-    return [];
 }
 /** `/api/<segments>` with each segment encoded; empty, `.` and `..` refused (URL parsing would resolve them away). */
 export function apiPath(...segments) {
@@ -518,7 +594,7 @@ export function createServer(options = {}) {
     const apiFetch = options.fetch ?? fetch;
     const server = new McpServer({
         name: "brewpage-mcp",
-        version: "1.20.0",
+        version: "1.22.0",
     }, { instructions: SERVER_INSTRUCTIONS });
     /** Caller argument first, then the configured default; `fromEnv` marks the configured one. */
     function ownerTokenFor(argument) {
@@ -584,7 +660,7 @@ export function createServer(options = {}) {
             lines.push(`Expires: ${data.expiresAt}`);
         lines.push(...hostingResponseLines(data));
         lines.push(...pageDataPublishLines(data, sentState));
-        lines.push(...publishDomainLines(data, requestedDomain));
+        lines.push(...publishDomainLines(data, requestedDomain, sentOwnerToken !== undefined && sentOwnerToken === defaultOwnerToken));
         lines.push(...ownerTokenLines(data, "update or delete this resource later", sentOwnerToken));
         lines.push(...ownerLinkLines(data));
         const ns = (data.namespace ?? effectiveNamespace) || "";
@@ -599,7 +675,7 @@ export function createServer(options = {}) {
             "Format order: `format`, then a known filename extension, else the server detects it. Returns its primary share link and owner token. Optional password, TTL, filename, top toolbar (showTopBar). " +
             "A `public` page without deliveryMode may get its own subdomain if it needs browser features a BrewPage link lacks; " +
             "the result then has deliveryModeReason and a delivery notice. Markdown raw HTML is allowlisted: scripts, styles, event handlers, forms, embeds removed. " +
-            "Optional `domain` connects a domain the user owns to an HTML-format page. " +
+            "Optional `domain` connects a custom domain the user owns to an HTML-format page. " +
             MANAGE_URL_TEXT + " " + SECRETS + " " + BADGE_TEXT + " " + PUBLISH_STATE_TEXT,
         inputSchema: {
             content: z.string().describe("HTML, Markdown, code or JSON to publish"),
@@ -863,7 +939,7 @@ export function createServer(options = {}) {
         ...toolMeta("Publish site", ADDITIVE),
         description: "Publish an HTML site to BrewPage. " + PUBLIC_HINT + "Single-page: `entryContent`. Multi-page: `files` (`{path, content}` array). Optional `entry` overrides `index.html`. Returns its primary share link and owner token. " +
             "Static only: HTML, CSS, JS (incl. built React/Vue bundles) run in the browser; server code (PHP etc.) never runs. " + SITE_LIMITS_TEXT +
-            " Optional `domain` connects a domain the user owns. " + MANAGE_URL_TEXT + " " + SECRETS + " " + BADGE_TEXT + " " + PUBLISH_STATE_TEXT,
+            " Optional `domain` connects a custom domain the user owns. " + MANAGE_URL_TEXT + " " + SECRETS + " " + BADGE_TEXT + " " + PUBLISH_STATE_TEXT,
         inputSchema: {
             deliveryMode: DELIVERY_MODE_SCHEMA,
             entryContent: z
@@ -969,7 +1045,7 @@ export function createServer(options = {}) {
             lines.push(`Expires: ${site.expiresAt}`);
         lines.push(...hostingResponseLines(site));
         lines.push(...pageDataPublishLines(site, sentState?.value));
-        lines.push(...publishDomainLines(site, domain || undefined));
+        lines.push(...publishDomainLines(site, domain || undefined, owner !== undefined && owner === defaultOwnerToken));
         lines.push(...ownerTokenLines(site, "view info or delete this site", owner));
         lines.push(...ownerLinkLines(site));
         const ns = (site.namespace || effectiveNamespace) || "";
@@ -1636,15 +1712,18 @@ export function createServer(options = {}) {
     }
     server.registerTool("set_domain", {
         ...toolMeta("Connect custom domain", ADDITIVE),
-        description: "Connect a domain the user owns (www.example.com or example.com) to one HTML page or site. " + DOMAIN_PROFILE_TEXT +
-            " Returns the DNS records for the domain owner to create at their DNS provider: TXT for ownership plus CNAME, or A/ALIAS for a root domain. " +
-            "A DNS check after that moves the status pending_dns -> verifying -> active; HTTPS is issued automatically. " +
-            "HTML pages of format html and sites, without a password. A hostname already in the profile moves to this publication. The BrewPage link keeps working.",
+        description: "Connect a custom domain (a hostname the user owns) to one HTML page of format html or one site, without a password. " + DOMAIN_PROFILE_TEXT +
+            " Returns the DNS records for the domain owner to create at their DNS provider exactly as returned: MX/mail records stay, " +
+            "an A, AAAA or CNAME record at the same name is replaced, at Cloudflare Proxy status is DNS only. " +
+            "One DNS check after the records exist is enough: BrewPage keeps checking on its own (first full check about 15 minutes after adding); " +
+            "usually live within 30 minutes, HTTPS is automatic. Status: pending_dns -> verifying -> active (lost when the DNS records break later); `problem` names the fix. " +
+            "A hostname already in the profile moves to this publication; the BrewPage link keeps working. " + DOMAIN_PROVIDER_TEXT +
+            " Steps and fixes: guide topic `custom-domain`.",
         inputSchema: {
             type: z.enum(["html", "site"]).describe("Publication type"),
             namespace: z.string().describe("Publication namespace"),
             id: z.string().describe("Publication ID"),
-            hostname: z.string().describe("Domain or subdomain the user owns, e.g. www.example.com or example.com"),
+            hostname: z.string().describe("Bare hostname the user owns: www.example.com or example.com, no scheme or path"),
             ownerToken: z.string().optional().describe(DOMAIN_OWNER_TOKEN),
         },
     }, async ({ type, namespace, id, hostname, ownerToken }) => {
@@ -1654,23 +1733,40 @@ export function createServer(options = {}) {
         const path = apiPath("publications", type, namespace, id, "domain");
         const { ok, status, data, headers: answerHeaders } = await apiRequest("PUT", path, { hostname }, { "X-Owner-Token": auth.token });
         if (!ok)
-            return ownerFailure("set domain", status, data, auth.fromEnv, answerHeaders, domainHints(data, false));
-        const lead = status === 201 ? "Custom domain connected." : "Custom domain set: it was already in the profile (moved here or unchanged).";
+            return ownerFailure("set domain", status, data, auth.fromEnv, answerHeaders, domainHints(data, "publication", auth.fromEnv));
+        const lead = status === 201 ? "Custom domain added. It is not live until the DNS records below exist."
+            : "Custom domain set: it was already in the profile (moved here or unchanged).";
         return textResult([lead, ``, ...domainLines(data)].join("\n"));
     });
     server.registerTool("list_domains", {
         ...toolMeta("List custom domains", READ_ONLY),
-        description: "List the custom domains of a BrewPage profile: status, DNS records and the publication each one shows, plus how many the profile holds and may hold. Needs an admin token of the profile.",
+        description: "Read custom domains without running a DNS check: status, `problem`, DNS records and the publication shown. " +
+            "No address: every custom domain of the profile plus how many it holds and may hold. With type, namespace and id, or with hostname: that one custom domain.",
         inputSchema: {
-            ownerToken: z.string().optional().describe(`Admin token of the profile. Default: ${ENV_DEFAULT}.`),
+            type: z.enum(["html", "site"]).optional().describe("Publication type; with namespace and id, instead of hostname"),
+            namespace: z.string().optional().describe("Publication namespace"),
+            id: z.string().optional().describe("Publication ID"),
+            hostname: z.string().optional().describe(DOMAIN_HOSTNAME),
+            ownerToken: z.string().optional().describe(DOMAIN_LIST_TOKEN),
         },
-    }, async ({ ownerToken }) => {
+    }, async ({ type, namespace, id, hostname, ownerToken }) => {
         const auth = ownerTokenFor(ownerToken);
         if (!auth.token)
             return textResult(NO_OWNER_TOKEN, true);
+        // An empty string reads as an omitted argument: the list stays reachable for a client that fills every field.
+        const [kind, ns, row, host] = [type, namespace, id, hostname].map((part) => part || undefined);
+        if ([kind, ns, row, host].some((part) => part !== undefined)) {
+            const path = domainPath(kind, ns, row, host);
+            if (path === null)
+                return textResult(DOMAIN_ADDRESS_ERROR, true);
+            const { ok, status, data, headers: answerHeaders } = await apiRequest("GET", path, undefined, { "X-Owner-Token": auth.token });
+            if (!ok)
+                return ownerFailure("read domain", status, data, auth.fromEnv, answerHeaders, domainHints(data, host !== undefined ? "hostname" : "publication", auth.fromEnv));
+            return textResult(domainLines(data).join("\n"));
+        }
         const { ok, status, data, headers: answerHeaders } = await apiRequest("GET", "/api/domains", undefined, { "X-Owner-Token": auth.token });
         if (!ok)
-            return ownerFailure("list domains", status, data, auth.fromEnv, answerHeaders, domainHints(data, false));
+            return ownerFailure("list domains", status, data, auth.fromEnv, answerHeaders, domainHints(data, "list", auth.fromEnv));
         const list = data;
         const items = Array.isArray(list.items) ? list.items : [];
         const lines = [`Custom domains: ${list.used} of ${list.limit} used`];
@@ -1682,14 +1778,15 @@ export function createServer(options = {}) {
     });
     server.registerTool("check_domain", {
         ...toolMeta("Check custom domain DNS", ADDITIVE),
-        description: "Check the DNS of a custom domain now and return its status and records. Status: pending_dns (records not seen yet), " +
-            "verifying (DNS found, HTTPS being issued), active (live). " + DOMAIN_ADDRESS_TEXT +
-            " Checks are spaced: a repeat too soon answers 429 with Retry-After.",
+        description: "Run a DNS check of a custom domain now and return its status, `problem` and DNS records. " +
+            "One check after the DNS records exist is enough: BrewPage keeps checking on its own (`nextCheckAt`) and reading the status needs no check; " +
+            "another check fits only after a DNS change. " + DOMAIN_STATUS_TEXT + " " + DOMAIN_ADDRESS_TEXT +
+            " A repeat within seconds answers 429 with Retry-After.",
         inputSchema: {
             type: z.enum(["html", "site"]).optional().describe("Publication type; with namespace and id, instead of hostname"),
             namespace: z.string().optional().describe("Publication namespace"),
             id: z.string().optional().describe("Publication ID"),
-            hostname: z.string().optional().describe("Custom domain, e.g. www.example.com; instead of type, namespace and id"),
+            hostname: z.string().optional().describe(DOMAIN_HOSTNAME),
             ownerToken: z.string().optional().describe(DOMAIN_EITHER_TOKEN),
         },
     }, async ({ type, namespace, id, hostname, ownerToken }) => {
@@ -1701,18 +1798,18 @@ export function createServer(options = {}) {
             return textResult(DOMAIN_ADDRESS_ERROR, true);
         const { ok, status, data, headers: answerHeaders } = await apiRequest("POST", path, undefined, { "X-Owner-Token": auth.token });
         if (!ok)
-            return ownerFailure("check domain", status, data, auth.fromEnv, answerHeaders, domainHints(data, hostname !== undefined));
+            return ownerFailure("check domain", status, data, auth.fromEnv, answerHeaders, domainHints(data, hostname !== undefined ? "hostname" : "publication", auth.fromEnv));
         return textResult([`DNS checked.`, ``, ...domainLines(data)].join("\n"));
     });
     server.registerTool("remove_domain", {
         ...toolMeta("Remove custom domain", DESTRUCTIVE),
         description: "Remove a custom domain from the profile: it stops showing the publication and its slot is free at once. The BrewPage link keeps working. " +
-            DOMAIN_ADDRESS_TEXT + " DNS records at the provider stay until the domain owner deletes them.",
+            DOMAIN_ADDRESS_TEXT + " DNS records at the DNS provider stay until the domain owner deletes them.",
         inputSchema: {
             type: z.enum(["html", "site"]).optional().describe("Publication type; with namespace and id, instead of hostname"),
             namespace: z.string().optional().describe("Publication namespace"),
             id: z.string().optional().describe("Publication ID"),
-            hostname: z.string().optional().describe("Custom domain, e.g. www.example.com; instead of type, namespace and id"),
+            hostname: z.string().optional().describe(DOMAIN_HOSTNAME),
             ownerToken: z.string().optional().describe(DOMAIN_EITHER_TOKEN),
         },
     }, async ({ type, namespace, id, hostname, ownerToken }) => {
@@ -1724,7 +1821,7 @@ export function createServer(options = {}) {
             return textResult(DOMAIN_ADDRESS_ERROR, true);
         const { ok, status, data, headers: answerHeaders } = await apiRequest("DELETE", path, undefined, { "X-Owner-Token": auth.token });
         if (!ok)
-            return ownerFailure("remove domain", status, data, auth.fromEnv, answerHeaders, domainHints(data, hostname !== undefined));
+            return ownerFailure("remove domain", status, data, auth.fromEnv, answerHeaders, domainHints(data, hostname !== undefined ? "hostname" : "publication", auth.fromEnv));
         const what = hostname !== undefined ? `Custom domain removed: ${hostname}` : `No custom domain on ${type} ${namespace}/${id} now`;
         return textResult(`${what} · slot free · BrewPage link unchanged\nIts DNS records can be deleted at the DNS provider.`);
     });
@@ -1933,10 +2030,11 @@ export function createServer(options = {}) {
         ...toolMeta("Read BrewPage guide", READ_ONLY),
         description: "Short reference texts for building on BrewPage. Topic `page-data`: how a published page saves what visitors enter " +
             "(forms, guestbook, votes, leaderboard, game progress) with the script `https://brewpage.app/js/state.js` and the `state` config; " +
-            "meant to be read before writing such a page.",
+            "meant to be read before writing such a page. Topic `custom-domain`: the steps that put a page or site on a domain the user owns " +
+            "(profile, DNS records, one check, statuses, problems and fixes).",
         inputSchema: {
-            topic: z.enum(["page-data"]).describe("Guide topic"),
+            topic: z.enum(["page-data", "custom-domain"]).describe("Guide topic"),
         },
-    }, async () => textResult(PAGE_DATA_GUIDE + PAGE_DATA_GUIDE_TAIL));
+    }, async ({ topic }) => textResult(topic === "custom-domain" ? CUSTOM_DOMAIN_GUIDE : PAGE_DATA_GUIDE + PAGE_DATA_GUIDE_TAIL));
     return server;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brewpage-mcp",
-  "version": "1.20.0",
+  "version": "1.22.0",
   "mcpName": "io.github.kochetkov-ma/brewpage-mcp",
   "description": "MCP server for BrewPage — publish and manage HTML, sites, KV, JSON and files from AI assistants",
   "type": "module",