brewpage-mcp 1.16.4 → 1.16.6

package/README.md

@@ -17,7 +17,7 @@ Choosing a host? See how BrewPage compares with GitHub Pages, Netlify Drop, Tiin
 ## Quick Start
 
 ```bash
-npx -y brewpage-mcp@1.16.4
+npx -y brewpage-mcp@1.16.6
 ```
 
 Requires Node.js 20 or newer. This starts the stdio server for an MCP client.
@@ -50,7 +50,7 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
   "mcpServers": {
     "brewpage": {
       "command": "npx",
-      "args": ["-y", "brewpage-mcp@1.16.4"]
+      "args": ["-y", "brewpage-mcp@1.16.6"]
     }
   }
 }
@@ -61,7 +61,7 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
 Register a project-scoped stdio server:
 
 ```bash
-claude mcp add --transport stdio --scope project brewpage -- npx -y brewpage-mcp@1.16.4
+claude mcp add --transport stdio --scope project brewpage -- npx -y brewpage-mcp@1.16.6
 ```
 
 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).
@@ -75,7 +75,7 @@ Open **Settings > MCP** and add:
   "mcpServers": {
     "brewpage": {
       "command": "npx",
-      "args": ["-y", "brewpage-mcp@1.16.4"]
+      "args": ["-y", "brewpage-mcp@1.16.6"]
     }
   }
 }
@@ -89,7 +89,7 @@ Open the Cline MCP settings panel and add:
 {
   "brewpage": {
     "command": "npx",
-    "args": ["-y", "brewpage-mcp@1.16.4"]
+    "args": ["-y", "brewpage-mcp@1.16.6"]
   }
 }
 ```
@@ -97,7 +97,7 @@ Open the Cline MCP settings panel and add:
 ### Global Install
 
 ```bash
-npm install -g brewpage-mcp@1.16.4
+npm install -g brewpage-mcp@1.16.6
 brewpage-mcp
 ```
 
@@ -176,7 +176,7 @@ publish_html(content="<h1>Report</h1>...", format="HTML", ttlDays=15)
 
 Update an existing HTML or Markdown page in place, preserving its short URL. Requires the original `ownerToken` returned at creation.
 
-Parameters: `namespace` (string), `id` (string), `content` (string, the new body), `ownerToken` (string), `format` (optional HTML/Markdown alias or supported code language such as `json`, `yaml`, or `typescript`; omitted preserves the stored format).
+Parameters: `namespace` (string), `id` (string), `content` (string, the new body), `ownerToken` (string), `format` (optional HTML/Markdown alias or supported code language such as `json`, `yaml`, or `typescript`; omitted preserves the stored format), `tags` (optional; replace the stored tags, `[]` clears, omitted keeps them).
 
 An update never changes the link or delivery mode; an advisory `deliveryModeReason` and `Delivery notice:` line are printed when the server returns them.
 
@@ -250,7 +250,7 @@ publish_site(files=[{"path": "index.html", "content": "..."}, {"path": "style.cs
 
 Replace an owned site's complete file set at the same ID and primary link. Files absent from the new bundle are removed; matching files are overwritten and new files added. Hosting stays unchanged. The `publish_site` limits and status codes apply.
 
-Parameters: `namespace`, `id`, `ownerToken`, exactly one of `entryContent` or a non-empty `files` array of `{path, content}`, optional `entry` (default `index.html`), `ttlDays` (ignored; existing expiry is preserved and a `ttl-ignored` notice is returned), and `tags`.
+Parameters: `namespace`, `id`, `ownerToken`, exactly one of `entryContent` or a non-empty `files` array of `{path, content}`, optional `entry` (default `index.html`), `ttlDays` (ignored; existing expiry is preserved and a `ttl-ignored` notice is returned), and `tags` (optional; replace the stored tags, `[]` clears, omitted keeps them).
 
 ```text
 republish_site(namespace="public", id="aBcDeFgHiJ", ownerToken="tok_...", files=[{"path":"index.html","content":"<h1>Updated site</h1>"}])
@@ -530,6 +530,14 @@ Every publish response includes an **owner token** -- the only credential that a
 
 ## Changelog
 
+## 1.16.6 -- 2026-10-31
+
+- `publish_html`, `publish_file` and `publish_site` descriptions lead with `namespace=public` to be found (gallery + Google, Bing & AI search; omitted: private); the `namespace` input names what to publish publicly (docs, guides, demos, portfolios, reports, landing pages) and the generated `priv-*` default; the private result line says how to be found. Shorter texts, no new facts.
+
+## 1.16.5 -- 2026-10-30
+
+- `update_html` takes optional `tags` (sent as `?tags=a,b`); `update_html` and `republish_site` tags replace the stored tags, `[]` clears them, omitted keeps them. A 429 on any write prints the server's `Retry-After` beside the verbatim body (`retryAfterSeconds`).
+
 ## 1.16.4 -- 2026-10-30
 
 - Owner update tools (`update_html`, `republish_site`, `update_json`, `set_kv`) answer a 404 with the server body plus which publish tool makes a new copy; `delete_resource` relays the 404 unchanged.

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.16.4";
+export declare const USER_AGENT = "brewpage-mcp/1.16.6";
 export declare const OWNER_TOKEN_ENV = "BREWPAGE_OWNER_TOKEN";
 export interface ServerOptions {
     /** BrewPage origin for API calls; default https://brewpage.app. */

package/dist/tools.js

@@ -1,7 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/server";
 import { z } from "zod";
 export const DEFAULT_BASE_URL = "https://brewpage.app";
-export const USER_AGENT = "brewpage-mcp/1.16.4";
+export const USER_AGENT = "brewpage-mcp/1.16.6";
 export const OWNER_TOKEN_ENV = "BREWPAGE_OWNER_TOKEN";
 const READ_ONLY = { readOnlyHint: true };
 const DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true };
@@ -54,9 +54,9 @@ function maskToken(token) {
 function textResult(text, isError = false) {
     return isError ? { content: [{ type: "text", text }], isError: true } : { content: [{ type: "text", text }] };
 }
-/** ` Retry-After: <value>.` for a busy 503 that sends the header, else empty. */
+/** ` Retry-After: <value>.` for a 429 or busy 503 that sends the header, else empty. */
 function retryAfterText(status, headers) {
-    const after = status === 503 ? headers?.get("retry-after") : null;
+    const after = status === 429 || status === 503 ? headers?.get("retry-after") : null;
     return after ? ` Retry-After: ${after}.` : "";
 }
 /** Create tool for each content update: a 404 update means the row is gone, so the agent publishes anew. */
@@ -99,17 +99,19 @@ function resolveNamespace(namespace) {
     return namespace && namespace.length > 0 ? namespace : defaultPrivateNamespace();
 }
 const UNLISTED_NOTICE = "Private: not listed. Anyone with the link can open it.";
-const LISTABLE_HINT = " Use namespace public to list it in the gallery and sitemap.";
+const LISTABLE_HINT = " To be found, send namespace=public: gallery + Google, Bing & AI search.";
 const PROTECTED_UNLISTED_NOTICE = "Password: link + password. Not listed.";
-const PUBLIC_NAMESPACE_LEAD = "namespace=public: listed in the public gallery and the sitemap, so Google, Bing and AI search can find and index it " +
-    "and people can discover it. Suits anything meant to be found or shared: docs, guides, demos, portfolios, reports, landing pages. ";
+const PUBLIC_NAMESPACE_LEAD = "Send namespace=public for anything meant to be found or shared (docs, guides, demos, portfolios, reports, landing pages): " +
+    "listed in the public gallery and sitemap, so Google, Bing and AI search index it and people discover it. ";
 const PUBLIC_NAMESPACE_TAIL = " Anyone can find and read a public page, so it is unsuitable for secrets, tokens or personal data. " +
-    "Omit (default): private. Unlisted and not indexed; anyone who has the link can still open it. ";
+    "Omit (default): private, a generated priv-* namespace; unlisted, not indexed; the link still opens it. ";
+/** Tool-description lead for listable publish tools. */
+const PUBLIC_HINT = "Send namespace=public to be found: gallery + Google, Bing & AI search. Omitted: private. ";
 const NAMESPACE_FORMAT = "Lowercase only: 1-32 of a-z, 0-9, hyphen.";
 /** `namespace` for publish_html and publish_file. */
 const NAMESPACE_DESCRIPTION = PUBLIC_NAMESPACE_LEAD +
-    "Public pages are served right on the brewpage.app domain, which gives them the strongest reach in search; " +
-    "a page whose code needs its own origin (cookies, storage) gets its own subdomain automatically." +
+    "Public pages are served on the brewpage.app domain itself, for the strongest search reach; " +
+    "code that needs its own origin (cookies, storage) gets its own subdomain automatically." +
     PUBLIC_NAMESPACE_TAIL + NAMESPACE_FORMAT;
 const SITE_NAMESPACE_DESCRIPTION = PUBLIC_NAMESPACE_LEAD + "A site always gets its own subdomain." +
     PUBLIC_NAMESPACE_TAIL + NAMESPACE_FORMAT;
@@ -123,9 +125,9 @@ const DELIVERY_MODE_SCHEMA = z.enum(["path", "subdomain"]).optional().describe("
     "Everything else in any namespace (Markdown, code/text, files, JSON, KV, public HTML) defaults to path (Promotion); public HTML may automatically choose subdomain for browser features. " +
     "When creation returns an existing publication, it keeps its actual mode and URL.");
 /** Site upload rules shared by publish_site and republish_site; current values come from get_limits. */
-const SITE_LIMITS_TEXT = "Default limits (current values: GET /api/limits): a request is at most 25 MiB; a site at most 200 files, 5 MiB per file and 20 MiB in total; " +
-    "each path at most 380 characters. System files (.DS_Store, __MACOSX/ and similar) are skipped and never count; files with an unsupported extension " +
-    "or a too-long path are skipped and listed in notices. Entry: `entry`, else root index.html, else the shallowest HTML file. " +
+const SITE_LIMITS_TEXT = "Default limits (current: GET /api/limits): request 25 MiB; site 200 files, 5 MiB per file, 20 MiB total; " +
+    "path 380 characters. System files (.DS_Store, __MACOSX/ and similar) are skipped and never count; files with an unsupported extension " +
+    "or too-long path are skipped and listed in notices. Entry: `entry`, else root index.html, else the shallowest HTML file. " +
     "Errors: 400 = a site limit exceeded (the message names it), invalid path, no HTML file, or a PDF/Office file unreadable " +
     "or password-protected; 413 = request over 25 MiB, too many files and form fields, or a file name/path too long; " +
     "422 = no servable file left; 503 = busy, retry after Retry-After seconds.";
@@ -216,7 +218,7 @@ export function createServer(options = {}) {
     const apiFetch = options.fetch ?? fetch;
     const server = new McpServer({
         name: "brewpage-mcp",
-        version: "1.16.4",
+        version: "1.16.6",
     });
     /** Caller argument first, then the configured default; `fromEnv` marks the configured one. */
     function ownerTokenFor(argument) {
@@ -291,9 +293,10 @@ export function createServer(options = {}) {
     }
     server.registerTool("publish_html", {
         ...toolMeta("Publish HTML, Markdown, code or JSON page", ADDITIVE),
-        description: "Publish HTML, Markdown, code or JSON content to BrewPage (max 5 MiB); format omitted -> the server detects it. Returns its primary share link and owner token. Supports password protection, custom TTL, optional filename, and an opt-in top toolbar (showTopBar). " +
-            "When deliveryMode is omitted for a `public` page, the server may publish it on its own subdomain if the page needs browser features a BrewPage link does not provide; " +
-            "the result then includes deliveryModeReason and a delivery notice. Markdown raw HTML is allowlisted: scripts, styles, event handlers, forms and embeds are removed. " +
+        description: "Publish HTML, Markdown, code or JSON to BrewPage (max 5 MiB). " + PUBLIC_HINT +
+            "Format omitted -> 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. " +
             MANAGE_URL_TEXT + " " + SECRETS,
         inputSchema: {
             content: z.string().describe("HTML, Markdown, code or JSON to publish"),
@@ -362,7 +365,7 @@ export function createServer(options = {}) {
     });
     server.registerTool("publish_file", {
         ...toolMeta("Publish file from URL", ADDITIVE),
-        description: "Upload a file to BrewPage via URL. Max 5 MiB, video 20 MiB. Returns its primary share link and owner token. Does not expose password or TTL inputs. " +
+        description: "Upload a file from a URL. " + PUBLIC_HINT + "Max 5 MiB, video 20 MiB; no password or TTL. Returns its primary share link and owner token. " +
             MANAGE_URL_TEXT + " " + SECRETS,
         inputSchema: {
             url: z.string().url().describe("URL of the file to upload"),
@@ -427,9 +430,9 @@ export function createServer(options = {}) {
         if (!auth.token)
             return textResult(NO_OWNER_TOKEN, true);
         const path = apiPath(TYPE_SEGMENTS[type], namespace, id, "hosting");
-        const { ok, status, data } = await apiRequest("PATCH", path, { deliveryMode, expectedVersion }, { "X-Owner-Token": auth.token });
+        const { ok, status, data, headers: answerHeaders } = await apiRequest("PATCH", path, { deliveryMode, expectedVersion }, { "X-Owner-Token": auth.token });
         if (!ok)
-            return ownerFailure("update hosting", status, data, auth.fromEnv);
+            return ownerFailure("update hosting", status, data, auth.fromEnv, answerHeaders);
         return {
             content: [{ type: "text", text: formatUpdateResponse(data) }],
         };
@@ -450,9 +453,9 @@ export function createServer(options = {}) {
         if (!auth.token)
             return textResult(NO_OWNER_TOKEN, true);
         const path = apiPath(TYPE_SEGMENTS[type], namespace, id);
-        const { ok, status, data } = await apiRequest("DELETE", path, undefined, { "X-Owner-Token": auth.token });
+        const { ok, status, data, headers: answerHeaders } = await apiRequest("DELETE", path, undefined, { "X-Owner-Token": auth.token });
         if (!ok)
-            return ownerFailure("delete", status, data, auth.fromEnv);
+            return ownerFailure("delete", status, data, auth.fromEnv, answerHeaders);
         return {
             content: [
                 {
@@ -545,8 +548,8 @@ export function createServer(options = {}) {
     });
     server.registerTool("publish_site", {
         ...toolMeta("Publish site", ADDITIVE),
-        description: "Publish an HTML site to BrewPage. Single-page: `entryContent`. Multi-page: `files` (array of `{path, content}`). Optional `entry` overrides default `index.html`. Returns its primary share link and owner token. " +
-            "Static sites: HTML, CSS and JS (incl. built React/Vue/TypeScript bundles) run in the browser; PHP and other server code never run. " + SITE_LIMITS_TEXT +
+        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 +
             " " + MANAGE_URL_TEXT + " " + SECRETS,
         inputSchema: {
             deliveryMode: DELIVERY_MODE_SCHEMA,
@@ -677,7 +680,7 @@ export function createServer(options = {}) {
             tags: z
                 .array(z.string())
                 .optional()
-                .describe("Optional tags (replaces the site's existing tags)"),
+                .describe("Optional tags; replace the site's stored tags. Omit to keep them."),
         },
     }, async ({ namespace, id, ownerToken, entryContent, files, entry, ttlDays, tags }) => {
         const hasEntry = typeof entryContent === "string";
@@ -711,7 +714,7 @@ export function createServer(options = {}) {
             return textResult(NO_OWNER_TOKEN, true);
         const headers = { "X-Owner-Token": auth.token };
         const url = baseUrl + withQuery(apiPath("sites", namespace, id), [["entry", entry || undefined],
-            ["ttl", ttlDays || undefined], ["tags", tags && tags.length ? tags.join(",") : undefined]]);
+            ["ttl", ttlDays || undefined], ["tags", tags?.join(",")]]);
         const res = await bpFetch(url, { method: "PUT", headers, body: formData });
         const data = await res.json().catch(() => null);
         if (!res.ok)
@@ -758,20 +761,24 @@ export function createServer(options = {}) {
                 .string()
                 .optional()
                 .describe("Content format. Accepts (case-insensitive on html/markdown): 'html', 'markdown'/'md', or a code language — yaml, json, xml, csv, tsv, log, toml, ini, sql, sh, bat, env, javascript, typescript, tsx, jsx, css, properties, docker, txt. Omit to preserve the stored format."),
+            tags: z
+                .array(z.string())
+                .optional()
+                .describe("Optional tags; replace the page's stored tags ([] clears). Omit to keep them."),
         },
-    }, async ({ namespace, id, content, ownerToken, format }) => {
+    }, async ({ namespace, id, content, ownerToken, format, tags }) => {
         const body = { content };
         if (format)
             body.format = format;
         const auth = ownerTokenFor(ownerToken);
         if (!auth.token)
             return textResult(NO_OWNER_TOKEN, true);
-        const path = apiPath("html", namespace, id);
-        const { ok, status, data } = await apiRequest("PUT", path, body, {
+        const path = withQuery(apiPath("html", namespace, id), [["tags", tags?.join(",")]]);
+        const { ok, status, data, headers: answerHeaders } = await apiRequest("PUT", path, body, {
             "X-Owner-Token": auth.token,
         });
         if (!ok)
-            return ownerFailure("update HTML", status, data, auth.fromEnv);
+            return ownerFailure("update HTML", status, data, auth.fromEnv, answerHeaders);
         return {
             content: [
                 {
@@ -828,7 +835,7 @@ export function createServer(options = {}) {
                 content: [
                     {
                         type: "text",
-                        text: `Failed to publish JSON (${res.status}): ${JSON.stringify(data)}`,
+                        text: `Failed to publish JSON (${res.status}): ${JSON.stringify(data)}${retryAfterText(res.status, res.headers)}`,
                     },
                 ],
                 isError: true,
@@ -907,7 +914,7 @@ export function createServer(options = {}) {
         });
         const data = await res.json().catch(() => null);
         if (!res.ok)
-            return ownerFailure("update JSON", res.status, data, auth.fromEnv);
+            return ownerFailure("update JSON", res.status, data, auth.fromEnv, res.headers);
         return {
             content: [
                 {
@@ -952,13 +959,13 @@ export function createServer(options = {}) {
             headers["X-Owner-Token"] = owner;
         if (deliveryMode)
             headers["X-Delivery-Mode"] = deliveryMode;
-        const { ok, status, data } = await apiRequest("POST", path, body, headers);
+        const { ok, status, data, headers: answerHeaders } = await apiRequest("POST", path, body, headers);
         if (!ok) {
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Failed to publish KV (${status}): ${JSON.stringify(data)}`,
+                        text: `Failed to publish KV (${status}): ${JSON.stringify(data)}${retryAfterText(status, answerHeaders)}`,
                     },
                 ],
                 isError: true,
@@ -989,11 +996,11 @@ export function createServer(options = {}) {
         if (!auth.token)
             return textResult(NO_OWNER_TOKEN, true);
         const path = apiPath("kv", namespace, id, key);
-        const { ok, status, data } = await apiRequest("PUT", path, body, {
+        const { ok, status, data, headers: answerHeaders } = await apiRequest("PUT", path, body, {
             "X-Owner-Token": auth.token,
         });
         if (!ok)
-            return ownerFailure("set KV", status, data, auth.fromEnv);
+            return ownerFailure("set KV", status, data, auth.fromEnv, answerHeaders);
         return {
             content: [
                 {
@@ -1150,9 +1157,9 @@ export function createServer(options = {}) {
         if (!auth.token)
             return textResult(NO_OWNER_TOKEN, true);
         const path = apiPath(TYPE_SEGMENTS[type], namespace, id, "visibility");
-        const { ok, status, data } = await apiRequest("POST", path, { listed }, { "X-Owner-Token": auth.token });
+        const { ok, status, data, headers: answerHeaders } = await apiRequest("POST", path, { listed }, { "X-Owner-Token": auth.token });
         if (!ok)
-            return ownerFailure("set visibility", status, data, auth.fromEnv);
+            return ownerFailure("set visibility", status, data, auth.fromEnv, answerHeaders);
         const result = data;
         return textResult([...credentialAlertLines(result), `LISTED: ${result.listed} · link unchanged`, ...noticeLines(result)].join("\n"));
     });
@@ -1167,9 +1174,9 @@ export function createServer(options = {}) {
         const auth = ownerTokenFor(ownerToken);
         if (!auth.token)
             return textResult(NO_OWNER_TOKEN, true);
-        const { ok, status, data } = await apiRequest("POST", "/api/owner-token/bind", { token }, { "X-Owner-Token": auth.token });
+        const { ok, status, data, headers: answerHeaders } = await apiRequest("POST", "/api/owner-token/bind", { token }, { "X-Owner-Token": auth.token });
         if (!ok)
-            return textResult(`Failed to bind token (${status}): ${JSON.stringify(data)}`, true);
+            return textResult(`Failed to bind token (${status}): ${JSON.stringify(data)}${retryAfterText(status, answerHeaders)}`, true);
         const result = data;
         return textResult(`BOUND ${maskToken(token)} · ${result.active}/${result.max} active`);
     });
@@ -1186,9 +1193,9 @@ export function createServer(options = {}) {
         const auth = ownerTokenFor(ownerToken);
         if (!auth.token)
             return textResult(NO_OWNER_TOKEN, true);
-        const { ok, status, data } = await apiRequest("POST", "/api/owner-token/mint", { label, scope, expiresIn }, { "X-Owner-Token": auth.token });
+        const { ok, status, data, headers: answerHeaders } = await apiRequest("POST", "/api/owner-token/mint", { label, scope, expiresIn }, { "X-Owner-Token": auth.token });
         if (!ok)
-            return textResult(`Failed to mint token (${status}): ${JSON.stringify(data)}`, true);
+            return textResult(`Failed to mint token (${status}): ${JSON.stringify(data)}${retryAfterText(status, answerHeaders)}`, true);
         const result = data;
         return textResult([
             `MINTED · ${result.scope} · expires ${result.expiresAt ?? "never"}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brewpage-mcp",
-  "version": "1.16.4",
+  "version": "1.16.6",
   "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",