brewpage-mcp 1.9.2 → 1.9.4

package/README.md

@@ -12,7 +12,7 @@ MCP server for [BrewPage](https://brewpage.app) -- publish and manage HTML, KV,
 ## Quick Start
 
 ```bash
-npx -y brewpage-mcp@1.9.2
+npx -y brewpage-mcp@1.9.4
 ```
 
 Requires Node.js 20 or newer. This starts the stdio server for an MCP client.
@@ -28,7 +28,7 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
   "mcpServers": {
     "brewpage": {
       "command": "npx",
-      "args": ["-y", "brewpage-mcp@1.9.2"]
+      "args": ["-y", "brewpage-mcp@1.9.4"]
     }
   }
 }
@@ -39,7 +39,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.9.2
+claude mcp add --transport stdio --scope project brewpage -- npx -y brewpage-mcp@1.9.4
 ```
 
 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).
@@ -53,7 +53,7 @@ Open **Settings > MCP** and add:
   "mcpServers": {
     "brewpage": {
       "command": "npx",
-      "args": ["-y", "brewpage-mcp@1.9.2"]
+      "args": ["-y", "brewpage-mcp@1.9.4"]
     }
   }
 }
@@ -67,7 +67,7 @@ Open the Cline MCP settings panel and add:
 {
   "brewpage": {
     "command": "npx",
-    "args": ["-y", "brewpage-mcp@1.9.2"]
+    "args": ["-y", "brewpage-mcp@1.9.4"]
   }
 }
 ```
@@ -75,7 +75,7 @@ Open the Cline MCP settings panel and add:
 ### Global Install
 
 ```bash
-npm install -g brewpage-mcp@1.9.2
+npm install -g brewpage-mcp@1.9.4
 brewpage-mcp
 ```
 
@@ -102,7 +102,9 @@ Sixteen tools are available. Creation returns an owner token; keep it to modify
 | `search_gallery` | Browse public content or list owned resources |
 | `get_stats` | Read platform-wide statistics |
 
-All five publish tools accept optional `deliveryMode: "path" | "subdomain"`, sent only as `X-Delivery-Mode`; authored JSON and multipart bodies keep their existing format. Visibility and password protection are separate choices. Omitted namespace still generates an unlisted `priv-<random>` namespace; anyone with an unpassworded unlisted link can read it. `public` grants gallery/search eligibility only; password-protected content remains excluded.
+All five publish tools accept optional `deliveryMode: "path" | "subdomain"`, sent only as `X-Delivery-Mode`; authored JSON and multipart bodies keep their existing format. Visibility and password protection are separate choices. Omitted namespace still generates an unlisted `priv-<random>` namespace; anyone with an unpassworded unlisted link can read it. `public` grants gallery/search eligibility only; password-protected content remains excluded and unlisted, protected or otherwise ineligible native responses carry `noindex`; eligible public HTML, sites and files may permit indexing.
+
+The MCP server wraps a subset of the backend-generated public [REST contract](../openapi/openapi.json). Its inputs retain their published behavior: TTL inputs accept 1–30 days (default 15), while backend owner-specific caps and eligible automatic extensions can affect actual expiry. Use returned `expiresAt`. `get_page` reads stored rendered HTML or format-specific code/text from the API; it does not call the owner-only original-source endpoint or a browser viewer. `publish_file` uploads from a source URL and does not expose password or TTL inputs.
 
 For a fresh publication, sites and non-public namespaces require Dedicated subdomain (`subdomain`); explicit `path` is rejected. Other public publications default to Promotion (`path`) and may choose Dedicated subdomain, including password-protected content. Promotion uses a BrewPage path with stricter active-document restrictions. Each NEW site gets one publication-specific host for its complete bundle, preserving relative/root-relative paths; missing assets return 404, with no SPA fallback. Third-party widgets may still need provider configuration.
 
@@ -110,7 +112,7 @@ Responses use the server's primary `link` verbatim, including the root slash, an
 
 When `deliveryMode` is omitted for a `public` HTML or Markdown page, the server may publish it on its own subdomain if the page needs browser features a BrewPage link does not provide. `publish_html` then prints `deliveryModeReason: "auto:<codes>"` and a `Delivery notice:` line with the server's explanation; pass `deliveryMode: "path"` to keep a BrewPage link, or change it later with `update_hosting`. `advisory:<codes>` (from `publish_html` or `update_html`) means the address was not changed but such features were found. Codes are comma-separated, drawn from `storage`, `cookies`, `history`, `downloads`, `top-navigation`, `media-capture`, `pointer-lock`, `embeds`, `fullscreen`. Neither line appears when nothing applies.
 
-An existing deduplication winner keeps its actual URL, cohort and mode, even when another mode was requested. OLD publications display **Existing link**, with null mode metadata; their legacy links and behavior remain unchanged. Ordinary content updates and site republishing preserve hosting. An eligible NEW public non-site may change mode separately with `update_hosting`.
+When creation returns an existing publication, it keeps its actual URL, cohort and mode, even when another mode was requested. OLD publications display **Existing link**, with null mode metadata; their legacy links and behavior remain unchanged. Ordinary content updates and site republishing preserve hosting. An eligible NEW public non-site may change mode separately with `update_hosting`.
 
 ### Hosting
 
@@ -220,7 +222,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.
 
-Parameters: `namespace`, `id`, `ownerToken`, exactly one of `entryContent` or a non-empty `files` array of `{path, content}`, optional `entry` (default `index.html`), `ttlDays` (1--30, default 15), 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` (compatibility input 1--30; existing expiry is preserved), and `tags`.
 
 ```text
 republish_site(namespace="public", id="aBcDeFgHiJ", ownerToken="tok_...", files=[{"path":"index.html","content":"<h1>Updated site</h1>"}])
@@ -350,7 +352,7 @@ search_gallery(mine=true, ownerToken="tok_...", sort="date")
 
 ### `delete_resource`
 
-Delete a BrewPage resource (HTML page, KV store, JSON collection, or file) using the owner token received at creation.
+Delete a BrewPage resource (HTML page, KV store, JSON document, or file) using the owner token received at creation.
 
 Parameters: `type` (`html` | `kv` | `json` | `file`), `namespace` (string), `id` (string), `ownerToken` (string).
 
@@ -431,6 +433,16 @@ Every publish response includes an **owner token** -- the only credential that a
 
 ## Changelog
 
+## 1.9.4 -- 2026-10-20
+
+- Tool descriptions and responses describe a create that returns an existing publication in plain terms; its link and delivery mode are kept as returned.
+- Keep sixteen tools, all input defaults and HTTP behavior unchanged. Independently versioned from backend API contract 1.113.0.
+
+## 1.9.3 -- 2026-10-11
+
+- Correct tool/discovery descriptions for unlisted access, conditional native indexing, exact share links, current limits, owner/extension TTL exceptions, retained site-republish expiry and API content representations.
+- Keep sixteen tools, all input defaults and HTTP behavior unchanged. This metadata package patch is independently versioned from backend API contract 1.107.2.
+
 ## 1.9.2 -- 2026-10-06
 
 - Dependencies are declared as exact versions, so an installed server uses the same SDK and `zod` versions it is built and tested with. No functional change.

package/dist/index.js

@@ -5,13 +5,13 @@ import { z } from "zod";
 const BASE_URL = process.env.BREWPAGE_URL || "https://brewpage.app";
 const server = new McpServer({
     name: "brewpage-mcp",
-    version: "1.9.2",
+    version: "1.9.4",
 });
 const PUBLIC_NAMESPACE = "public";
 /**
  * Generate a short, unlisted private namespace slug used when the caller omits
  * `namespace`. Sending an explicit non-public ns prevents the backend from
- * applying its `public` default, which would gallery-list + index the content.
+ * applying its `public` default and making the content discovery-eligible.
  * Format: `priv-<6 lowercase-alphanumeric chars>`.
  */
 function defaultPrivateNamespace() {
@@ -32,13 +32,14 @@ function resolveNamespace(namespace) {
 const UNLISTED_NOTICE = "Unlisted link — anyone who has it can open it, but it's not in the gallery or search. " +
     "Use namespace `public` for gallery/search eligibility; password-protected content stays excluded.";
 const PROTECTED_UNLISTED_NOTICE = "Password-protected unlisted link — readers need the password; excluded from gallery and search.";
-const NAMESPACE_DESCRIPTION = "Optional. Omit to keep the content PRIVATE/unlisted (reachable only by its link — " +
-    "not listed in the gallery and not indexed by search engines). Pass a custom namespace " +
-    "to group private content, or pass `public` ONLY when the user explicitly wants gallery/search " +
-    "eligibility. Password-protected content stays excluded from gallery/search.";
+const NAMESPACE_DESCRIPTION = "Optional. Omit to generate an unlisted namespace: anyone with its unpassworded link can read it, " +
+    "but it is excluded from gallery/search. Pass a custom namespace to group unlisted content, " +
+    "or pass `public` ONLY when the user explicitly wants gallery/search eligibility. " +
+    "Password-protected content stays excluded; unlisted, protected or otherwise ineligible native responses carry noindex; eligible public HTML, sites and files may permit indexing.";
 const DELIVERY_MODE_SCHEMA = z.enum(["path", "subdomain"]).optional().describe("Optional delivery choice for a fresh publication, independent of password/namespace. " +
-    "Public non-sites default to path (Promotion); fresh sites and non-public content require subdomain. " +
-    "An existing dedup winner keeps its actual mode and URL.");
+    "Public non-sites normally default to path (Promotion); public HTML may automatically choose subdomain for browser features. " +
+    "Fresh sites and non-public content require subdomain. " +
+    "When creation returns an existing publication, it keeps its actual mode and URL.");
 function hostingResponseLines(data) {
     const fields = ["routingCohort", "deliveryMode", "requestedDeliveryMode", "effectiveDeliveryMode",
         "deliveryModeMatched", "modeLocked", "hostingVersion", "access", "managementLink"];
@@ -46,7 +47,7 @@ function hostingResponseLines(data) {
     if (data.routingCohort === "old")
         lines.push("Hosting: Existing link");
     if (data.deliveryModeMatched === false)
-        lines.push("Requested hosting differs from the existing winner; its URL and mode were preserved.");
+        lines.push("Requested hosting differs from the existing publication; its URL and mode were preserved.");
     lines.push(...deliveryReasonLines(data));
     return lines;
 }
@@ -108,7 +109,7 @@ function formatUpdateResponse(data) {
     lines.push(...hostingResponseLines(data));
     return lines.join("\n");
 }
-server.tool("publish_html", "Publish HTML or Markdown content to BrewPage. Returns a public URL and owner token. Supports password protection, custom TTL, optional filename, and an opt-in top toolbar (showTopBar). " +
+server.tool("publish_html", "Publish HTML or Markdown content to BrewPage (repository default limit 5 MiB). 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. Always share the returned URL.", {
     content: z.string().describe("HTML or Markdown content to publish"),
@@ -131,7 +132,7 @@ server.tool("publish_html", "Publish HTML or Markdown content to BrewPage. Retur
         .min(1)
         .max(30)
         .optional()
-        .describe("Time to live in days (1-30, default: 15)"),
+        .describe("Requested TTL in days (1-30, default 15). Backend owner caps and eligible automatic extensions can affect expiry; use returned expiresAt."),
     filename: z
         .string()
         .max(200)
@@ -177,7 +178,7 @@ server.tool("publish_html", "Publish HTML or Markdown content to BrewPage. Retur
         ],
     };
 });
-server.tool("publish_file", "Upload a file to BrewPage via URL. Returns a public URL and owner token.", {
+server.tool("publish_file", "Upload a file to BrewPage via URL. Repository defaults: 5 MiB for files/audio, 20 MiB for video. Returns its primary share link and owner token. Does not expose password or TTL inputs.", {
     url: z.string().url().describe("URL of the file to upload"),
     deliveryMode: DELIVERY_MODE_SCHEMA,
     namespace: z
@@ -286,7 +287,7 @@ server.tool("delete_resource", "Delete a BrewPage resource (HTML page, KV store,
         ],
     };
 });
-server.tool("get_page", "Fetch a published BrewPage HTML page content by namespace and ID.", {
+server.tool("get_page", "Fetch stored rendered HTML or format-specific code/text by namespace and ID. This reads API content, not the owner-only original-source endpoint or browser viewer. Protected reads use the password header.", {
     namespace: z.string().describe("Page namespace"),
     id: z.string().describe("Page ID"),
     password: z
@@ -359,7 +360,7 @@ server.tool("get_stats", "Get BrewPage platform-wide usage statistics including
         ],
     };
 });
-server.tool("publish_site", "Publish an HTML site to BrewPage. Single-page: pass `entryContent`. Multi-page: pass `files` (array of `{path, content}`). Optional `entry` overrides default `index.html`.", {
+server.tool("publish_site", "Publish an HTML site to BrewPage. Single-page: pass `entryContent`. Multi-page: pass `files` (array of `{path, content}`). Optional `entry` overrides default `index.html`. Repository defaults: 20 MiB total, 100 files, 5 MiB per file. Use its returned primary link and retain the owner token.", {
     deliveryMode: DELIVERY_MODE_SCHEMA,
     entryContent: z
         .string()
@@ -386,7 +387,7 @@ server.tool("publish_site", "Publish an HTML site to BrewPage. Single-page: pass
         .min(1)
         .max(30)
         .optional()
-        .describe("Time to live in days (1-30, default: 15)"),
+        .describe("Requested TTL in days (1-30, default 15). Backend owner caps and eligible automatic extensions can affect expiry; use returned expiresAt."),
     ownerToken: z
         .string()
         .optional()
@@ -475,7 +476,7 @@ server.tool("publish_site", "Publish an HTML site to BrewPage. Single-page: pass
         content: [{ type: "text", text: lines.join("\n") }],
     };
 });
-server.tool("republish_site", "Republish (full-replace) an existing multi-file BrewPage site in place at the SAME URL/ID. Requires owner token. The uploaded bundle becomes the complete new file set — files absent from it are removed, new files added, matching files overwritten. Single-page: pass `entryContent`. Multi-page: pass `files` (array of `{path, content}`). Optional `entry` overrides the default `index.html`.", {
+server.tool("republish_site", "Republish (full-replace) an existing multi-file BrewPage site in place at the SAME URL/ID. Requires owner token. The uploaded bundle becomes the complete new file set — files absent from it are removed, new files added, matching files overwritten. Single-page: pass `entryContent`. Multi-page: pass `files` (array of `{path, content}`). Optional `entry` overrides the default `index.html`. Site bundles use repository defaults of 20 MiB total, 100 files, 5 MiB per file; republishing preserves existing expiry.", {
     namespace: z.string().describe("Site namespace"),
     id: z.string().describe("Site ID"),
     ownerToken: z
@@ -498,7 +499,7 @@ server.tool("republish_site", "Republish (full-replace) an existing multi-file B
         .min(1)
         .max(30)
         .optional()
-        .describe("Time to live in days (1-30, default: 15)"),
+        .describe("Compatibility input (1-30); site republishing preserves existing expiry. Use returned expiresAt."),
     tags: z
         .array(z.string())
         .optional()
@@ -620,7 +621,7 @@ server.tool("update_html", "Update an existing BrewPage HTML/Markdown page. Requ
         ],
     };
 });
-server.tool("publish_json", "Publish a JSON document to BrewPage. Accepts a JSON object, array, or a JSON-encoded string. Returns a public URL and owner token.", {
+server.tool("publish_json", "Publish a JSON document to BrewPage (repository default limit 1 MiB). Accepts a JSON object, array, or a JSON-encoded string containing any valid JSON, including scalars/null. Returns its primary share link and owner token.", {
     deliveryMode: DELIVERY_MODE_SCHEMA,
     json: z
         .union([z.string(), z.record(z.unknown()), z.array(z.unknown())])
@@ -639,7 +640,7 @@ server.tool("publish_json", "Publish a JSON document to BrewPage. Accepts a JSON
         .min(1)
         .max(30)
         .optional()
-        .describe("Time to live in days (1-30, default: 15)"),
+        .describe("Requested TTL in days (1-30, default 15). Backend owner caps and eligible automatic extensions can affect expiry; use returned expiresAt."),
     tags: z
         .array(z.string())
         .optional()
@@ -767,7 +768,7 @@ server.tool("update_json", "Update an existing BrewPage JSON document. Requires
         ],
     };
 });
-server.tool("publish_kv", "Publish a key/value entry to BrewPage. Creates a KV store; the entry is addressed by (namespace, id, key). Returns a public URL and owner token.", {
+server.tool("publish_kv", "Publish a key/value entry to BrewPage. Creates a KV store; the entry is addressed by (namespace, id, key). Repository defaults: 1 MiB per value, 1,000 keys per store. Returns its primary share link and owner token.", {
     deliveryMode: DELIVERY_MODE_SCHEMA,
     key: z.string().describe("KV key (first part of the (namespace, id, key) addressing tuple)"),
     value: z.string().describe("KV value"),
@@ -785,7 +786,7 @@ server.tool("publish_kv", "Publish a key/value entry to BrewPage. Creates a KV s
         .min(1)
         .max(30)
         .optional()
-        .describe("Time to live in days (1-30, default: 15)"),
+        .describe("Requested TTL in days (1-30, default 15). Backend owner caps and eligible automatic extensions can affect expiry; use returned expiresAt."),
     tags: z
         .array(z.string())
         .optional()

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "brewpage-mcp",
-  "version": "1.9.2",
+  "version": "1.9.4",
   "mcpName": "io.github.kochetkov-ma/brewpage-mcp",
-  "description": "MCP server for BrewPage — publish and manage HTML, KV, JSON, and file content from AI assistants",
+  "description": "MCP server for BrewPage — publish and manage HTML, sites, KV, JSON and files from AI assistants",
   "type": "module",
   "bin": {
     "brewpage-mcp": "./dist/index.js"