brewpage-mcp 1.5.1 → 1.7.0

package/README.md

@@ -92,7 +92,7 @@ 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, defaults to `public`), `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 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).
 
 Example prompt that invokes this tool:
 
@@ -142,7 +142,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), `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 to list and index it), `filename` (optional custom filename).
 
 Example prompt:
 
@@ -160,7 +160,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), `password` (optional), `ttlDays` (1--30, default 15), `ownerToken` (optional, groups site under an existing owner).
+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).
 
 Example prompt:
 
@@ -178,7 +178,7 @@ publish_site(files=[{"path": "index.html", "content": "..."}, {"path": "style.cs
 
 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, defaults to `public`), `password` (optional), `ttlDays` (optional, 1--30, default 15), `tags` (optional `string[]`).
+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[]`).
 
 Example prompt:
 
@@ -228,7 +228,7 @@ 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, defaults to `public`), `password` (optional), `ttlDays` (optional, 1--30, default 15), `tags` (optional `string[]`).
+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[]`).
 
 Example prompt:
 
@@ -328,7 +328,7 @@ 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; public by default |
+| "Host this AI-generated artifact" | `publish_html` | `namespace` optional; **private/unlisted by default** -- pass `public` to gallery-list + index |
 | "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` |
 | "Fix a typo in the page I shared -- same link" | `update_html` | Requires `ownerToken`; URL stays the same |
@@ -371,6 +371,12 @@ Every publish response includes an **owner token** -- the only credential that a
 
 ## Changelog
 
+## 1.6.0 -- 2026-06-05
+
+- **Private-by-default publishing.** When `namespace` is omitted, all five publish tools (`publish_html`, `publish_file`, `publish_site`, `publish_json`, `publish_kv`) now send an explicit unlisted namespace (`priv-<random>`) instead of letting the backend default to `public`. Omitted namespace = unlisted (reachable only by its link, not gallery-listed, not search-indexed); pass `namespace: "public"` explicitly to list + index. Non-breaking: `namespace` stays optional.
+- Publish responses for non-public namespaces now append an "Unlisted link" notice explaining how to make content public.
+- Tool descriptions and README rewritten to reflect the private-by-default model.
+
 ## 1.5.0 -- 2026-05-21
 
 - Add 8 new MCP tools: `update_html`, `publish_json`, `get_json`, `update_json`, `publish_kv`, `set_kv`, `get_kv`, `search_gallery`.

package/dist/index.js

@@ -5,8 +5,36 @@ import { z } from "zod";
 const BASE_URL = process.env.BREWPAGE_URL || "https://brewpage.app";
 const server = new McpServer({
     name: "brewpage-mcp",
-    version: "1.5.1",
+    version: "1.7.0",
 });
+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.
+ * Format: `priv-<6 lowercase-alphanumeric chars>`.
+ */
+function defaultPrivateNamespace() {
+    const alphabet = "abcdefghijklmnopqrstuvwxyz0123456789";
+    let slug = "";
+    for (let i = 0; i < 6; i++) {
+        slug += alphabet[Math.floor(Math.random() * alphabet.length)];
+    }
+    return `priv-${slug}`;
+}
+/**
+ * Resolve the effective namespace actually sent to the API: the caller's value
+ * verbatim when provided (including `public`), otherwise a generated private slug.
+ */
+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.";
+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) {
     const url = `${BASE_URL}${path}`;
     const res = await fetch(url, {
@@ -20,7 +48,7 @@ async function apiRequest(method, path, body, headers) {
     const data = await res.json().catch(() => null);
     return { ok: res.ok, status: res.status, data };
 }
-function formatPublishResponse(data) {
+function formatPublishResponse(data, effectiveNamespace) {
     const lines = [
         `Published successfully!`,
         ``,
@@ -32,6 +60,10 @@ function formatPublishResponse(data) {
     if (data.expiresAt)
         lines.push(`Expires: ${data.expiresAt}`);
     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) || "";
+    if (ns !== PUBLIC_NAMESPACE) {
+        lines.push(``, UNLISTED_NOTICE);
+    }
     return lines.join("\n");
 }
 function formatUpdateResponse(data) {
@@ -58,7 +90,7 @@ server.tool("publish_html", "Publish HTML or Markdown content to BrewPage. Retur
     namespace: z
         .string()
         .optional()
-        .describe("Namespace for the page (optional, defaults to 'public')"),
+        .describe(NAMESPACE_DESCRIPTION),
     password: z
         .string()
         .optional()
@@ -80,9 +112,9 @@ server.tool("publish_html", "Publish HTML or Markdown content to BrewPage. Retur
         .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 }) => {
+    const effectiveNamespace = resolveNamespace(namespace);
     const body = { content, format };
-    if (namespace)
-        body.namespace = namespace;
+    body.namespace = effectiveNamespace;
     if (password)
         body.password = password;
     if (ttlDays)
@@ -107,7 +139,7 @@ server.tool("publish_html", "Publish HTML or Markdown content to BrewPage. Retur
         content: [
             {
                 type: "text",
-                text: formatPublishResponse(data),
+                text: formatPublishResponse(data, effectiveNamespace),
             },
         ],
     };
@@ -117,9 +149,10 @@ server.tool("publish_file", "Upload a file to BrewPage via URL. Returns a public
     namespace: z
         .string()
         .optional()
-        .describe("Namespace for the file (optional, defaults to 'public')"),
+        .describe(NAMESPACE_DESCRIPTION),
     filename: z.string().optional().describe("Custom filename (optional)"),
 }, async ({ url: fileUrl, namespace, filename }) => {
+    const effectiveNamespace = resolveNamespace(namespace);
     const fileRes = await fetch(fileUrl);
     if (!fileRes.ok) {
         return {
@@ -135,8 +168,7 @@ 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");
-    if (namespace)
-        formData.append("namespace", namespace);
+    formData.append("namespace", effectiveNamespace);
     const res = await fetch(`${BASE_URL}/api/files`, {
         method: "POST",
         body: formData,
@@ -157,7 +189,7 @@ server.tool("publish_file", "Upload a file to BrewPage via URL. Returns a public
         content: [
             {
                 type: "text",
-                text: formatPublishResponse(data),
+                text: formatPublishResponse(data, effectiveNamespace),
             },
         ],
     };
@@ -280,7 +312,7 @@ server.tool("publish_site", "Publish an HTML site to BrewPage. Single-page: pass
     namespace: z
         .string()
         .optional()
-        .describe("Namespace for the site (optional, defaults to 'public')"),
+        .describe(NAMESPACE_DESCRIPTION),
     password: z
         .string()
         .optional()
@@ -327,11 +359,11 @@ server.tool("publish_site", "Publish an HTML site to BrewPage. Single-page: pass
         headers["X-Password"] = password;
     if (ownerToken)
         headers["X-Owner-Token"] = ownerToken;
+    const effectiveNamespace = resolveNamespace(namespace);
     const qsParams = [];
     if (entry)
         qsParams.push(`entry=${encodeURIComponent(entry)}`);
-    if (namespace)
-        qsParams.push(`ns=${encodeURIComponent(namespace)}`);
+    qsParams.push(`ns=${encodeURIComponent(effectiveNamespace)}`);
     if (ttlDays)
         qsParams.push(`ttl=${encodeURIComponent(String(ttlDays))}`);
     const qs = qsParams.length ? `?${qsParams.join("&")}` : "";
@@ -368,6 +400,114 @@ server.tool("publish_site", "Publish an HTML site to BrewPage. Single-page: pass
     if (site.expiresAt)
         lines.push(`Expires: ${site.expiresAt}`);
     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);
+    }
+    return {
+        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`.", {
+    namespace: z.string().describe("Site namespace"),
+    id: z.string().describe("Site ID"),
+    ownerToken: z
+        .string()
+        .describe("Owner token received when the site was created (required for republish)"),
+    entryContent: z
+        .string()
+        .optional()
+        .describe("HTML content for a single-page site (entry file). Mutually exclusive with `files`."),
+    files: z
+        .array(z.object({ path: z.string(), content: z.string() }))
+        .optional()
+        .describe("Multi-file site: array of `{path, content}`. Mutually exclusive with `entryContent`."),
+    entry: z
+        .string()
+        .optional()
+        .describe("Entry file path, default index.html"),
+    ttlDays: z
+        .number()
+        .min(1)
+        .max(30)
+        .optional()
+        .describe("Time to live in days (1-30, default: 15)"),
+    tags: z
+        .array(z.string())
+        .optional()
+        .describe("Optional tags (replaces the site's existing tags)"),
+}, async ({ namespace, id, ownerToken, entryContent, files, entry, ttlDays, tags }) => {
+    const hasEntry = typeof entryContent === "string";
+    const hasFiles = Array.isArray(files) && files.length > 0;
+    if (hasEntry === hasFiles) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "Provide exactly one of `entryContent` (single-page) or `files` (multi-page).",
+                },
+            ],
+            isError: true,
+        };
+    }
+    const formData = new FormData();
+    if (hasFiles) {
+        for (const f of files) {
+            formData.append("files", new Blob([f.content], { type: "text/html" }), f.path);
+            formData.append("paths", f.path);
+        }
+    }
+    else {
+        const entryBlob = new Blob([entryContent], { type: "text/html" });
+        const entryName = entry || "index.html";
+        formData.append("files", entryBlob, entryName);
+        formData.append("paths", entryName);
+    }
+    const headers = { "X-Owner-Token": ownerToken };
+    const qsParams = [];
+    if (entry)
+        qsParams.push(`entry=${encodeURIComponent(entry)}`);
+    if (ttlDays)
+        qsParams.push(`ttl=${encodeURIComponent(String(ttlDays))}`);
+    if (tags && tags.length)
+        qsParams.push(`tags=${encodeURIComponent(tags.join(","))}`);
+    const qs = qsParams.length ? `?${qsParams.join("&")}` : "";
+    const url = `${BASE_URL}/api/sites/${encodeURIComponent(namespace)}/${encodeURIComponent(id)}${qs}`;
+    const res = await fetch(url, { method: "PUT", headers, body: formData });
+    const data = await res.json().catch(() => null);
+    if (!res.ok) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to republish site (${res.status}): ${JSON.stringify(data)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const site = data;
+    const lines = [
+        `Site republished successfully (full replace)!`,
+        ``,
+        `URL: ${site.link || "N/A"}`,
+        `Namespace: ${site.namespace || namespace}`,
+        `ID: ${site.id || id}`,
+        `Entry file: ${site.entryFile || "index.html"}`,
+        `Files: ${site.fileCount || 1}`,
+    ];
+    if (site.totalSizeBytes !== undefined)
+        lines.push(`Size: ${site.totalSizeBytes} bytes`);
+    if (site.ownerLink)
+        lines.push(`Owner link: ${site.ownerLink}`);
+    if (Array.isArray(site.tags) && site.tags.length)
+        lines.push(`Tags: ${site.tags.join(", ")}`);
+    if (site.expiresAt)
+        lines.push(`Expires: ${site.expiresAt}`);
+    if (site.result)
+        lines.push(`Result: ${site.result}`);
+    if (site.visibilityNotice)
+        lines.push(``, String(site.visibilityNotice));
     return {
         content: [{ type: "text", text: lines.join("\n") }],
     };
@@ -418,7 +558,7 @@ server.tool("publish_json", "Publish a JSON document to BrewPage. Accepts a JSON
     namespace: z
         .string()
         .optional()
-        .describe("Namespace for the document (optional, defaults to 'public')"),
+        .describe(NAMESPACE_DESCRIPTION),
     password: z
         .string()
         .optional()
@@ -440,9 +580,9 @@ server.tool("publish_json", "Publish a JSON document to BrewPage. Accepts a JSON
         .describe("Existing owner token to group this document under the same owner as previous content"),
 }, async ({ json, namespace, password, ttlDays, tags, ownerToken }) => {
     const jsonString = typeof json === "string" ? json : JSON.stringify(json);
+    const effectiveNamespace = resolveNamespace(namespace);
     const qsParams = [];
-    if (namespace)
-        qsParams.push(`ns=${encodeURIComponent(namespace)}`);
+    qsParams.push(`ns=${encodeURIComponent(effectiveNamespace)}`);
     if (ttlDays !== undefined)
         qsParams.push(`ttl=${encodeURIComponent(String(ttlDays))}`);
     if (tags && tags.length) {
@@ -476,7 +616,7 @@ server.tool("publish_json", "Publish a JSON document to BrewPage. Accepts a JSON
         content: [
             {
                 type: "text",
-                text: formatPublishResponse(data),
+                text: formatPublishResponse(data, effectiveNamespace),
             },
         ],
     };
@@ -561,7 +701,7 @@ server.tool("publish_kv", "Publish a key/value entry to BrewPage. Creates a KV s
     namespace: z
         .string()
         .optional()
-        .describe("Namespace for the KV store (optional, defaults to 'public')"),
+        .describe(NAMESPACE_DESCRIPTION),
     password: z
         .string()
         .optional()
@@ -583,9 +723,9 @@ server.tool("publish_kv", "Publish a key/value entry to BrewPage. Creates a KV s
         .describe("Existing owner token to group this KV store under the same owner as previous content"),
 }, async ({ key, value, namespace, password, ttlDays, tags, ownerToken }) => {
     const body = { key, value };
+    const effectiveNamespace = resolveNamespace(namespace);
     const qsParams = [];
-    if (namespace)
-        qsParams.push(`ns=${encodeURIComponent(namespace)}`);
+    qsParams.push(`ns=${encodeURIComponent(effectiveNamespace)}`);
     if (ttlDays !== undefined)
         qsParams.push(`ttl=${encodeURIComponent(String(ttlDays))}`);
     if (tags && tags.length) {
@@ -614,7 +754,7 @@ server.tool("publish_kv", "Publish a key/value entry to BrewPage. Creates a KV s
         content: [
             {
                 type: "text",
-                text: formatPublishResponse(data),
+                text: formatPublishResponse(data, effectiveNamespace),
             },
         ],
     };

package/package.json

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