brewpage-mcp 1.5.0 → 1.6.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.0",
+    version: "1.6.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,10 @@ 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") }],
     };
@@ -418,7 +454,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 +476,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 +512,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 +597,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 +619,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 +650,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.0",
+  "version": "1.6.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",
@@ -15,12 +15,13 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "scripts": {
     "build": "tsc",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts",
+    "test": "npm run build && node --import tsx --test test/smoke.test.ts",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -52,7 +53,7 @@
     "url": "https://github.com/kochetkov-ma/brewpage-openapi/issues"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^3.24.0"
   },
   "devDependencies": {