brewpage-mcp 1.7.0 → 1.9.0

package/README.md

@@ -7,14 +7,16 @@ MCP server for [BrewPage](https://brewpage.app) -- publish and manage HTML, KV,
 
 ## What is BrewPage
 
-[BrewPage](https://brewpage.app) is a free instant hosting platform designed for AI agents and developers. One `POST` request publishes HTML, Markdown, a multi-file site, a JSON document, or a binary file and returns a stable HTTPS short URL -- no accounts, no API keys, no infrastructure setup. Every resource carries an **owner token** returned at creation time: use it to update content in place (keeping the same URL), delete the resource, or authenticate list operations across sessions. `brewpage-mcp` exposes this API as fourteen typed MCP tools so any compatible agent -- Claude, Codex, Gemini, Cursor, Cline -- can publish, update, fetch, and manage BrewPage HTML, JSON, KV, and file content without leaving the conversation.
+[BrewPage](https://brewpage.app) is a free instant hosting platform designed for AI agents and developers. One `POST` request publishes HTML, Markdown, a multi-file site, a JSON document, or a binary file and returns its primary HTTPS link -- no accounts, no API keys, no infrastructure setup. Every resource carries an **owner token** returned at creation time: use it to update content in place, delete the resource, or authenticate list operations across sessions. `brewpage-mcp` exposes this API as sixteen typed MCP tools so any compatible agent -- Claude, Codex, Gemini, Cursor, Cline -- can publish, update, fetch, and manage BrewPage HTML, JSON, KV, and file content without leaving the conversation.
 
 ## Quick Start
 
 ```bash
-npx brewpage-mcp
+npx -y brewpage-mcp@1.9.0
 ```
 
+Requires Node.js 20 or newer. This starts the stdio server for an MCP client.
+
 ## Installation
 
 ### Claude Desktop
@@ -26,7 +28,7 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
   "mcpServers": {
     "brewpage": {
       "command": "npx",
-      "args": ["-y", "brewpage-mcp"]
+      "args": ["-y", "brewpage-mcp@1.9.0"]
     }
   }
 }
@@ -34,19 +36,14 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
 
 ### Claude Code
 
-Add to `~/.claude/settings.json`:
+Register a project-scoped stdio server:
 
-```json
-{
-  "mcpServers": {
-    "brewpage": {
-      "command": "npx",
-      "args": ["-y", "brewpage-mcp"]
-    }
-  }
-}
+```bash
+claude mcp add --transport stdio --scope project brewpage -- npx -y brewpage-mcp@1.9.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).
+
 ### Cursor
 
 Open **Settings > MCP** and add:
@@ -56,7 +53,7 @@ Open **Settings > MCP** and add:
   "mcpServers": {
     "brewpage": {
       "command": "npx",
-      "args": ["-y", "brewpage-mcp"]
+      "args": ["-y", "brewpage-mcp@1.9.0"]
     }
   }
 }
@@ -70,7 +67,7 @@ Open the Cline MCP settings panel and add:
 {
   "brewpage": {
     "command": "npx",
-    "args": ["-y", "brewpage-mcp"]
+    "args": ["-y", "brewpage-mcp@1.9.0"]
   }
 }
 ```
@@ -78,13 +75,54 @@ Open the Cline MCP settings panel and add:
 ### Global Install
 
 ```bash
-npm install -g brewpage-mcp
+npm install -g brewpage-mcp@1.9.0
 brewpage-mcp
 ```
 
 ## Tools
 
-Fourteen tools are available, grouped by resource: **HTML**, **JSON**, **KV**, **Files**, **Sites**, and **Discovery**. All write operations return an owner token; keep it to modify or delete the resource later. Any update (`PUT`) operation requires the original `ownerToken` -- it is the backend's authorization gate. `password` is optional on reads/creates; if set, it is sent as the `X-Password` header.
+Sixteen tools are available. Creation returns an owner token; keep it to modify or delete the resource later. Updates (`PUT`/`PATCH`) require the original `ownerToken`. Supported password inputs use `X-Password`.
+
+| Tool | Purpose |
+|------|---------|
+| `publish_html` | Publish HTML or Markdown |
+| `update_html` | Replace page content; omitted format preserves stored format |
+| `get_page` | Fetch raw page content |
+| `publish_file` | Fetch a source URL and upload the file |
+| `publish_site` | Publish a single page or complete multi-file site bundle |
+| `republish_site` | Replace the complete site bundle at the same ID/link |
+| `publish_json` | Publish a JSON object, array, or JSON-encoded string |
+| `get_json` | Read a JSON document |
+| `update_json` | Replace a JSON document |
+| `publish_kv` | Create a KV store with an initial entry |
+| `set_kv` | Set or replace a key in an owned KV store |
+| `get_kv` | Read a KV value |
+| `update_hosting` | Change eligible delivery mode with owner token and hosting version |
+| `delete_resource` | Delete HTML, JSON, KV, or file content |
+| `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.
+
+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.
+
+Responses use the server's primary `link` verbatim, including the root slash, and expose `routingCohort`, actual/requested/effective modes, `deliveryModeMatched`, `modeLocked`, `hostingVersion`, access and the trusted-apex `managementLink` when present. Never reconstruct a host from namespace or ID. NEW password links are clean URLs: do not add `?p=`; browser readers unlock through the trusted gateway. Owner tokens and API calls stay on the configured apex API origin.
+
+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`.
+
+### Hosting
+
+### `update_hosting`
+
+Change an eligible NEW public non-site between Promotion and Dedicated subdomain. Parameters: `type` (`html` | `file` | `json` | `kv`), `namespace`, `id`, `ownerToken`, `deliveryMode` (`path` | `subdomain`), and `expectedVersion` (current server `hostingVersion`, integer ≥1).
+
+The tool sends owner-only `PATCH /api/{html|files|json|kv}/{namespace}/{id}/hosting` with `{deliveryMode, expectedVersion}` and `X-Owner-Token`. OLD links, sites and non-public publications are locked. The server returns 403 for invalid owner authority, 400 for locked hosting, and 409 for a stale version; reload current metadata before retrying. A paused real change returns 503. Selecting the current mode returns 200 without incrementing the version. Use the returned primary link after a successful change; the publication host identity is retained through both directions.
+
+```text
+update_hosting(type="html", namespace="public", id="aBcDeFgHiJ", ownerToken="tok_...", deliveryMode="subdomain", expectedVersion=1)
+```
 
 ### HTML
 
@@ -92,7 +130,9 @@ Fourteen tools are available, grouped by resource: **HTML**, **JSON**, **KV**, *
 
 Publish HTML or Markdown content to BrewPage. Returns a public URL and owner token.
 
-Parameters: `content` (string), `format` (`HTML` | `MARKDOWN`, default `HTML`), `namespace` (optional -- **omit to keep the page private/unlisted**: reachable only by its link, not in the gallery, not indexed by search engines; pass `public` only when the user explicitly wants it gallery-listed and search-indexed), `password` (optional), `ttlDays` (1--30, default 15), `filename` (optional, used as title fallback), `showTopBar` (optional boolean -- adds a toolbar with filename, Download button, and theme toggle).
+Parameters: `content` (string), `format` (`HTML` | `MARKDOWN`, default `HTML`), `namespace` (optional -- **omit for unlisted content**; pass `public` only for gallery/search eligibility, except when password-protected), `password` (optional), `ttlDays` (1--30, default 15), `filename` (optional, used as title fallback), `showTopBar` (optional boolean -- adds a toolbar with filename, Download button, and theme toggle), `deliveryMode` (optional).
+
+The result includes `deliveryModeReason` and a `Delivery notice:` line when the server returns them (see above).
 
 Example prompt that invokes this tool:
 
@@ -108,7 +148,9 @@ 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` | `code`, defaults to `HTML`).
+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).
+
+An update never changes the link or delivery mode; an advisory `deliveryModeReason` and `Delivery notice:` line are printed when the server returns them.
 
 Example prompt:
 
@@ -124,6 +166,8 @@ update_html(namespace="public", id="aBcDeFgHiJ", content="<h1>Updated</h1>...",
 
 Fetch the content of a published BrewPage HTML page by namespace and ID.
 
+Returns the actual response body as text, including authored HTML or JSON code. Hosting metadata and the primary link come only from server response headers; JSON fields inside the publication are never treated as platform metadata. The existing apex HTML API route is retained.
+
 Parameters: `namespace` (string), `id` (string), `password` (optional, if the page is password-protected).
 
 Example prompt:
@@ -142,7 +186,7 @@ get_page(namespace="public", id="aBcDeFgHiJ")
 
 Upload a file to BrewPage by fetching it from a URL. Returns a public URL and owner token. Supports images, PDFs, video, audio, code files, and archives.
 
-Parameters: `url` (string, the source URL to fetch), `namespace` (optional -- omit to keep the file private/unlisted: reachable only by its link, not in the gallery, not search-indexed; pass `public` only to list and index it), `filename` (optional custom filename).
+Parameters: `url` (string, the source URL to fetch), `namespace` (optional -- omit to keep the file private/unlisted: reachable only by its link, not in the gallery, not search-indexed; pass `public` only for gallery/search eligibility), `filename` (optional custom filename), `deliveryMode` (optional). This tool does not expose base64, password, or TTL inputs.
 
 Example prompt:
 
@@ -160,7 +204,7 @@ publish_file(url="https://example.com/diagram.png")
 
 Publish a single-page or multi-file HTML site. Pass `entryContent` for a single page or `files` (array of `{path, content}`) for a multi-file site. Supports password protection, TTL, and owner token grouping.
 
-Parameters: `entryContent` (string, mutually exclusive with `files`), `files` (array of `{path, content}`, mutually exclusive with `entryContent`), `entry` (optional entry file path, default `index.html`), `namespace` (optional -- omit to keep the site private/unlisted: reachable only by its link, not in the gallery, not search-indexed; pass `public` only to list and index it), `password` (optional), `ttlDays` (1--30, default 15), `ownerToken` (optional, groups site under an existing owner).
+Parameters: exactly one of `entryContent` (string) or non-empty `files` (array of `{path, content}`), `entry` (optional entry file path, default `index.html`), `namespace` (optional -- omit for unlisted content; `public` grants gallery eligibility except when password-protected), `password` (optional), `ttlDays` (1--30, default 15), `ownerToken` (optional, groups site under an existing owner), `deliveryMode` (optional; fresh sites require `subdomain`).
 
 Example prompt:
 
@@ -172,13 +216,25 @@ publish_site(files=[{"path": "index.html", "content": "..."}, {"path": "style.cs
 
 ---
 
+### `republish_site`
+
+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`.
+
+```text
+republish_site(namespace="public", id="aBcDeFgHiJ", ownerToken="tok_...", files=[{"path":"index.html","content":"<h1>Updated site</h1>"}])
+```
+
+---
+
 ### JSON
 
 ### `publish_json`
 
 Publish a JSON document to BrewPage. Returns a public URL and owner token. The body may be passed as a JSON string or as a structured object.
 
-Parameters: `json` (string or object, the JSON payload), `namespace` (optional -- omit to keep the document private/unlisted: reachable only by its link, not in the gallery, not search-indexed; pass `public` only to list and index it), `password` (optional), `ttlDays` (optional, 1--30, default 15), `tags` (optional `string[]`).
+Parameters: `json` (string, object, or array), `namespace` (optional -- omit for unlisted content; `public` grants gallery/search eligibility, except when password-protected), `password` (optional), `ttlDays` (1--30, default 15), `tags` (optional `string[]`), `ownerToken` (optional existing owner), `deliveryMode` (optional).
 
 Example prompt:
 
@@ -210,7 +266,7 @@ get_json(namespace="public", id="aBcDeFgHiJ")
 
 Update an existing JSON document in place, preserving its short URL. Requires the original `ownerToken`.
 
-Parameters: `namespace` (string), `id` (string), `json` (string or object, the new payload), `ownerToken` (string).
+Parameters: `namespace` (string), `id` (string), `json` (string, object, or array), `ownerToken` (string).
 
 Example prompt:
 
@@ -228,14 +284,14 @@ update_json(namespace="public", id="aBcDeFgHiJ", json={"mode": "dark", "version"
 
 Create a new KV (key/value) entry. Returns a public URL and owner token. The KV entry is addressed by `(namespace, id, key)`; this tool creates the entry and emits the generated `id` along with the owner token.
 
-Parameters: `key` (string), `value` (string), `namespace` (optional -- omit to keep the KV store private/unlisted: reachable only by its link, not in the gallery, not search-indexed; pass `public` only to list and index it), `password` (optional), `ttlDays` (optional, 1--30, default 15), `tags` (optional `string[]`).
+Parameters: `key` (string), `value` (string), `namespace` (optional -- omit for unlisted content; `public` grants gallery/search eligibility, except when password-protected), `password` (optional), `ttlDays` (1--30, default 15), `tags` (optional `string[]`), `ownerToken` (optional existing owner), `deliveryMode` (optional).
 
 Example prompt:
 
-> "Store the API key under the label 'staging-token' so I can reuse it next session."
+> "Store the selected theme so I can reuse it next session."
 
 ```
-publish_kv(key="staging-token", value="abc123")
+publish_kv(key="theme", value="dark")
 ```
 
 ---
@@ -248,10 +304,10 @@ Parameters: `namespace` (string), `id` (string), `key` (string), `value` (string
 
 Example prompt:
 
-> "Update the staging-token value to the new secret."
+> "Change the selected theme to light."
 
 ```
-set_kv(namespace="public", id="aBcDeFgHiJ", key="staging-token", value="def456", ownerToken="tok_...")
+set_kv(namespace="public", id="aBcDeFgHiJ", key="theme", value="light", ownerToken="tok_...")
 ```
 
 ---
@@ -264,10 +320,10 @@ Parameters: `namespace` (string), `id` (string), `key` (string), `password` (opt
 
 Example prompt:
 
-> "What did I store under staging-token?"
+> "What theme did I store?"
 
 ```
-get_kv(namespace="public", id="aBcDeFgHiJ", key="staging-token")
+get_kv(namespace="public", id="aBcDeFgHiJ", key="theme")
 ```
 
 ---
@@ -298,6 +354,8 @@ Delete a BrewPage resource (HTML page, KV store, JSON collection, or file) using
 
 Parameters: `type` (`html` | `kv` | `json` | `file`), `namespace` (string), `id` (string), `ownerToken` (string).
 
+Sites are not supported by this tool; use the REST site deletion endpoint.
+
 Example prompt:
 
 > "Delete the page I just published -- namespace public, id aBcDeFgHiJ."
@@ -328,9 +386,11 @@ get_stats()
 |--------------------|------|-------|
 | "Publish this HTML so I can share it" | `publish_html` | `format=HTML`; save `ownerToken` |
 | "Share these meeting notes as a link" | `publish_html` | `format=MARKDOWN`; readable rendered output |
-| "Host this AI-generated artifact" | `publish_html` | `namespace` optional; **private/unlisted by default** -- pass `public` to gallery-list + index |
+| "Host this AI-generated artifact" | `publish_html` | `namespace` optional; **private/unlisted by default**; `public` grants gallery/search eligibility except when protected |
 | "Upload this image / PDF / video" | `publish_file` | Fetches from URL; inline preview on short URL |
 | "Deploy this static site" | `publish_site` | Pass `files` array or `entryContent` |
+| "Replace the site I published" | `republish_site` | Owner token; complete bundle replaces all existing files |
+| "Give my public page a dedicated address" | `update_hosting` | NEW public non-site; owner token + current hosting version |
 | "Fix a typo in the page I shared -- same link" | `update_html` | Requires `ownerToken`; URL stays the same |
 | "Remove the page I published" | `delete_resource` | Requires `ownerToken` from creation |
 | "Read back the page I published" | `get_page` | Returns raw content for editing |
@@ -348,15 +408,15 @@ get_stats()
 
 Every publish response includes an **owner token** -- the only credential that allows updating or deleting your content. **Save it. It cannot be recovered.**
 
-- Reuse it via `X-Owner-Token` on subsequent creates to group resources under one owner.
+- Reuse it with `publish_site`, `publish_json`, or `publish_kv` to group new resources under one owner; REST creates accept `X-Owner-Token`.
 - Pass it to `delete_resource` to remove content.
-- Pass it to `get_page` (not needed for reads, but required for listing your own resources via the REST API).
+- Pass it to `search_gallery` with `mine=true` to list owned resources. `get_page` has no owner-token input; protected reads use `password`.
 
 ## Configuration
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `BREWPAGE_URL` | `https://brewpage.app` | API base URL |
+| `BREWPAGE_URL` | `https://brewpage.app` | Authorized apex API base URL; never a publication host |
 
 ## Links
 

package/dist/index.js

@@ -5,7 +5,7 @@ import { z } from "zod";
 const BASE_URL = process.env.BREWPAGE_URL || "https://brewpage.app";
 const server = new McpServer({
     name: "brewpage-mcp",
-    version: "1.7.0",
+    version: "1.9.0",
 });
 const PUBLIC_NAMESPACE = "public";
 /**
@@ -30,12 +30,37 @@ function resolveNamespace(namespace) {
     return namespace && namespace.length > 0 ? namespace : defaultPrivateNamespace();
 }
 const UNLISTED_NOTICE = "Unlisted link — anyone who has it can open it, but it's not in the gallery or search. " +
-    "Publish with namespace `public` to list it in the gallery and have search engines index it.";
+    "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 the page " +
-    "listed in the brewpage.app gallery and indexed by search engines.";
-async function apiRequest(method, path, body, headers) {
+    "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 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.");
+function hostingResponseLines(data) {
+    const fields = ["routingCohort", "deliveryMode", "requestedDeliveryMode", "effectiveDeliveryMode",
+        "deliveryModeMatched", "modeLocked", "hostingVersion", "access", "managementLink"];
+    const lines = fields.filter((field) => field in data).map((field) => `${field}: ${JSON.stringify(data[field])}`);
+    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(...deliveryReasonLines(data));
+    return lines;
+}
+/** Optional HTML create/update fields: why the delivery mode was chosen or flagged. */
+function deliveryReasonLines(data) {
+    const { deliveryModeReason: reason, deliveryNotice: notice } = data;
+    const lines = [];
+    if (typeof reason === "string" && reason.length > 0)
+        lines.push(`deliveryModeReason: ${JSON.stringify(reason)}`);
+    if (typeof notice === "string" && notice.length > 0)
+        lines.push(`Delivery notice: ${notice}`);
+    return lines;
+}
+async function apiRequest(method, path, body, headers, responseType = "json") {
     const url = `${BASE_URL}${path}`;
     const res = await fetch(url, {
         method,
@@ -45,24 +70,25 @@ async function apiRequest(method, path, body, headers) {
         },
         body: body ? JSON.stringify(body) : undefined,
     });
-    const data = await res.json().catch(() => null);
-    return { ok: res.ok, status: res.status, data };
+    const data = responseType === "text" ? await res.text() : await res.json().catch(() => null);
+    return { ok: res.ok, status: res.status, data, headers: res.headers };
 }
 function formatPublishResponse(data, effectiveNamespace) {
     const lines = [
         `Published successfully!`,
         ``,
-        `URL: ${data.url || data.link || "N/A"}`,
+        `URL: ${data.link || data.url || "N/A"}`,
     ];
     if (data.shortUrl)
         lines.push(`Short URL: ${data.shortUrl}`);
     lines.push(`Namespace: ${data.namespace || "N/A"}`, `ID: ${data.id || "N/A"}`);
     if (data.expiresAt)
         lines.push(`Expires: ${data.expiresAt}`);
+    lines.push(...hostingResponseLines(data));
     lines.push(``, `===================================`, `OWNER TOKEN: ${data.ownerToken}`, `===================================`, ``, `IMPORTANT: Save your owner token! You need it to update or delete this resource later. It cannot be recovered if lost.`);
-    const ns = (effectiveNamespace ?? data.namespace) || "";
+    const ns = (data.namespace ?? effectiveNamespace) || "";
     if (ns !== PUBLIC_NAMESPACE) {
-        lines.push(``, UNLISTED_NOTICE);
+        lines.push(``, data.access === "protected" ? PROTECTED_UNLISTED_NOTICE : UNLISTED_NOTICE);
     }
     return lines.join("\n");
 }
@@ -70,7 +96,7 @@ function formatUpdateResponse(data) {
     const lines = [
         `Updated successfully!`,
         ``,
-        `URL: ${data.url || data.link || "N/A"}`,
+        `URL: ${data.link || data.url || "N/A"}`,
     ];
     if (data.shortUrl)
         lines.push(`Short URL: ${data.shortUrl}`);
@@ -79,10 +105,14 @@ function formatUpdateResponse(data) {
         lines.push(`Expires: ${data.expiresAt}`);
     if (data.updatedAt)
         lines.push(`Updated: ${data.updatedAt}`);
+    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. Returns a public URL 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"),
+    deliveryMode: DELIVERY_MODE_SCHEMA,
     format: z
         .enum(["HTML", "MARKDOWN"])
         .default("HTML")
@@ -111,19 +141,22 @@ server.tool("publish_html", "Publish HTML or Markdown content to BrewPage. Retur
         .boolean()
         .optional()
         .describe("Add a thin top toolbar (filename + Download button + theme toggle) on the served page. Default: hidden."),
-}, async ({ content, format, namespace, password, ttlDays, filename, showTopBar }) => {
+}, async ({ content, format, namespace, password, ttlDays, filename, showTopBar, deliveryMode }) => {
     const effectiveNamespace = resolveNamespace(namespace);
-    const body = { content, format };
-    body.namespace = effectiveNamespace;
-    if (password)
-        body.password = password;
-    if (ttlDays)
-        body.ttlDays = ttlDays;
+    const qsParams = [`ns=${encodeURIComponent(effectiveNamespace)}`, `format=${encodeURIComponent(format.toLowerCase())}`];
+    if (ttlDays !== undefined)
+        qsParams.push(`ttl=${encodeURIComponent(String(ttlDays))}`);
+    const body = { content };
     if (filename)
         body.filename = filename;
     if (showTopBar !== undefined)
         body.showTopBar = showTopBar;
-    const { ok, data } = await apiRequest("POST", "/api/html", body);
+    const headers = {};
+    if (password)
+        headers["X-Password"] = password;
+    if (deliveryMode)
+        headers["X-Delivery-Mode"] = deliveryMode;
+    const { ok, data } = await apiRequest("POST", `/api/html?${qsParams.join("&")}`, body, headers);
     if (!ok) {
         return {
             content: [
@@ -146,12 +179,13 @@ 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.", {
     url: z.string().url().describe("URL of the file to upload"),
+    deliveryMode: DELIVERY_MODE_SCHEMA,
     namespace: z
         .string()
         .optional()
         .describe(NAMESPACE_DESCRIPTION),
     filename: z.string().optional().describe("Custom filename (optional)"),
-}, async ({ url: fileUrl, namespace, filename }) => {
+}, async ({ url: fileUrl, namespace, filename, deliveryMode }) => {
     const effectiveNamespace = resolveNamespace(namespace);
     const fileRes = await fetch(fileUrl);
     if (!fileRes.ok) {
@@ -168,9 +202,9 @@ server.tool("publish_file", "Upload a file to BrewPage via URL. Returns a public
     const blob = await fileRes.blob();
     const formData = new FormData();
     formData.append("file", blob, filename || fileUrl.split("/").pop() || "file");
-    formData.append("namespace", effectiveNamespace);
-    const res = await fetch(`${BASE_URL}/api/files`, {
+    const res = await fetch(`${BASE_URL}/api/files?ns=${encodeURIComponent(effectiveNamespace)}`, {
         method: "POST",
+        headers: deliveryMode ? { "X-Delivery-Mode": deliveryMode } : undefined,
         body: formData,
     });
     const data = await res.json().catch(() => null);
@@ -194,6 +228,27 @@ server.tool("publish_file", "Upload a file to BrewPage via URL. Returns a public
         ],
     };
 });
+server.tool("update_hosting", "Change delivery mode for a NEW public non-site publication. Requires owner token and current hostingVersion. OLD links and forced subdomain modes are locked; reload after a 409 conflict. Content updates never change hosting.", {
+    type: z.enum(["html", "file", "json", "kv"]).describe("Resource type; sites have no hosting-choice endpoint"),
+    namespace: z.string().describe("Resource namespace; only public is eligible"),
+    id: z.string().describe("Resource ID"),
+    ownerToken: z.string().describe("Original resource owner token"),
+    deliveryMode: z.enum(["path", "subdomain"]).describe("path = Promotion; subdomain = Dedicated subdomain"),
+    expectedVersion: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER).describe("Current hostingVersion from the server; required for concurrency control"),
+}, async ({ type, namespace, id, ownerToken, deliveryMode, expectedVersion }) => {
+    const segment = type === "file" ? "files" : type;
+    const path = `/api/${segment}/${encodeURIComponent(namespace)}/${encodeURIComponent(id)}/hosting`;
+    const { ok, status, data } = await apiRequest("PATCH", path, { deliveryMode, expectedVersion }, { "X-Owner-Token": ownerToken });
+    if (!ok) {
+        return {
+            content: [{ type: "text", text: `Failed to update hosting (${status}): ${JSON.stringify(data)}` }],
+            isError: true,
+        };
+    }
+    return {
+        content: [{ type: "text", text: formatUpdateResponse(data) }],
+    };
+});
 server.tool("delete_resource", "Delete a BrewPage resource (HTML page, KV store, JSON collection, or file) using the owner token.", {
     type: z
         .enum(["html", "kv", "json", "file"])
@@ -242,27 +297,35 @@ server.tool("get_page", "Fetch a published BrewPage HTML page content by namespa
     const headers = {};
     if (password)
         headers["X-Password"] = password;
-    const { ok, status, data } = await apiRequest("GET", `/api/html/${namespace}/${id}`, undefined, headers);
+    const { ok, status, data, headers: responseHeaders } = await apiRequest("GET", `/api/html/${namespace}/${id}`, undefined, headers, "text");
     if (!ok) {
+        let errorData = data;
+        try {
+            errorData = JSON.parse(data);
+        }
+        catch { }
         return {
             content: [
                 {
                     type: "text",
-                    text: `Failed to fetch page (${status}): ${JSON.stringify(data)}`,
+                    text: `Failed to fetch page (${status}): ${JSON.stringify(errorData)}`,
                 },
             ],
             isError: true,
         };
     }
-    const page = data;
+    const routingCohort = responseHeaders.get("X-Routing-Cohort");
+    const deliveryMode = responseHeaders.get("X-Delivery-Mode");
+    const hosting = { ...(routingCohort !== null ? { routingCohort } : {}), ...(deliveryMode !== null ? { deliveryMode } : {}) };
+    const hasNewMarkers = (routingCohort !== null && routingCohort !== "old") || deliveryMode !== null;
     const lines = [
         `Page: ${namespace}/${id}`,
-        `URL: ${page.url || `${BASE_URL}/${namespace}/${id}`}`,
-        `Format: ${page.format || "HTML"}`,
-        `Created: ${page.createdAt || "N/A"}`,
+        `URL: ${responseHeaders.get("X-Canonical-Link") ?? (hasNewMarkers ? "N/A" : `${BASE_URL}/${namespace}/${id}`)}`,
+        `Content-Type: ${responseHeaders.get("Content-Type") || "N/A"}`,
+        ...hostingResponseLines(hosting),
         ``,
         `--- Content ---`,
-        `${page.content || ""}`,
+        data,
     ];
     return {
         content: [{ type: "text", text: lines.join("\n") }],
@@ -297,6 +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`.", {
+    deliveryMode: DELIVERY_MODE_SCHEMA,
     entryContent: z
         .string()
         .optional()
@@ -327,7 +391,7 @@ server.tool("publish_site", "Publish an HTML site to BrewPage. Single-page: pass
         .string()
         .optional()
         .describe("Existing owner token to group this site under the same owner as previous content"),
-}, async ({ entryContent, files, entry, namespace, password, ttlDays, ownerToken }) => {
+}, async ({ entryContent, files, entry, namespace, password, ttlDays, ownerToken, deliveryMode }) => {
     const hasEntry = typeof entryContent === "string";
     const hasFiles = Array.isArray(files) && files.length > 0;
     if (hasEntry === hasFiles) {
@@ -359,6 +423,8 @@ server.tool("publish_site", "Publish an HTML site to BrewPage. Single-page: pass
         headers["X-Password"] = password;
     if (ownerToken)
         headers["X-Owner-Token"] = ownerToken;
+    if (deliveryMode)
+        headers["X-Delivery-Mode"] = deliveryMode;
     const effectiveNamespace = resolveNamespace(namespace);
     const qsParams = [];
     if (entry)
@@ -399,10 +465,11 @@ server.tool("publish_site", "Publish an HTML site to BrewPage. Single-page: pass
         lines.push(`Tags: ${site.tags.join(", ")}`);
     if (site.expiresAt)
         lines.push(`Expires: ${site.expiresAt}`);
+    lines.push(...hostingResponseLines(site));
     lines.push(``, `===================================`, `OWNER TOKEN: ${site.ownerToken}`, `===================================`, ``, `IMPORTANT: Save your owner token! You need it to view info or delete this site. It cannot be recovered if lost.`);
     const ns = (site.namespace || effectiveNamespace) || "";
     if (ns !== PUBLIC_NAMESPACE) {
-        lines.push(``, UNLISTED_NOTICE);
+        lines.push(``, site.access === "protected" ? PROTECTED_UNLISTED_NOTICE : UNLISTED_NOTICE);
     }
     return {
         content: [{ type: "text", text: lines.join("\n") }],
@@ -506,13 +573,15 @@ server.tool("republish_site", "Republish (full-replace) an existing multi-file B
         lines.push(`Expires: ${site.expiresAt}`);
     if (site.result)
         lines.push(`Result: ${site.result}`);
+    lines.push(...hostingResponseLines(site));
     if (site.visibilityNotice)
         lines.push(``, String(site.visibilityNotice));
     return {
         content: [{ type: "text", text: lines.join("\n") }],
     };
 });
-server.tool("update_html", "Update an existing BrewPage HTML/Markdown page. Requires owner token. Returns the updated page metadata.", {
+server.tool("update_html", "Update an existing BrewPage HTML/Markdown page. Requires owner token. Returns the updated page metadata. " +
+    "The link and delivery mode never change on update; an advisory deliveryModeReason and delivery notice are included when the new content uses browser features that may not work fully on a BrewPage link.", {
     namespace: z.string().describe("Page namespace"),
     id: z.string().describe("Page ID"),
     content: z.string().describe("New HTML or Markdown content"),
@@ -552,6 +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.", {
+    deliveryMode: DELIVERY_MODE_SCHEMA,
     json: z
         .union([z.string(), z.record(z.unknown()), z.array(z.unknown())])
         .describe("JSON document to publish (object, array, or JSON-encoded string)"),
@@ -578,7 +648,7 @@ server.tool("publish_json", "Publish a JSON document to BrewPage. Accepts a JSON
         .string()
         .optional()
         .describe("Existing owner token to group this document under the same owner as previous content"),
-}, async ({ json, namespace, password, ttlDays, tags, ownerToken }) => {
+}, async ({ json, namespace, password, ttlDays, tags, ownerToken, deliveryMode }) => {
     const jsonString = typeof json === "string" ? json : JSON.stringify(json);
     const effectiveNamespace = resolveNamespace(namespace);
     const qsParams = [];
@@ -595,6 +665,8 @@ server.tool("publish_json", "Publish a JSON document to BrewPage. Accepts a JSON
         headers["X-Password"] = password;
     if (ownerToken)
         headers["X-Owner-Token"] = ownerToken;
+    if (deliveryMode)
+        headers["X-Delivery-Mode"] = deliveryMode;
     const res = await fetch(`${BASE_URL}/api/json${qs}`, {
         method: "POST",
         headers,
@@ -696,6 +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.", {
+    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"),
     namespace: z
@@ -721,7 +794,7 @@ server.tool("publish_kv", "Publish a key/value entry to BrewPage. Creates a KV s
         .string()
         .optional()
         .describe("Existing owner token to group this KV store under the same owner as previous content"),
-}, async ({ key, value, namespace, password, ttlDays, tags, ownerToken }) => {
+}, async ({ key, value, namespace, password, ttlDays, tags, ownerToken, deliveryMode }) => {
     const body = { key, value };
     const effectiveNamespace = resolveNamespace(namespace);
     const qsParams = [];
@@ -738,6 +811,8 @@ server.tool("publish_kv", "Publish a key/value entry to BrewPage. Creates a KV s
         headers["X-Password"] = password;
     if (ownerToken)
         headers["X-Owner-Token"] = ownerToken;
+    if (deliveryMode)
+        headers["X-Delivery-Mode"] = deliveryMode;
     const { ok, status, data } = await apiRequest("POST", `/api/kv${qs}`, body, headers);
     if (!ok) {
         return {

package/package.json

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