@seldonframe/mcp 1.59.1 → 1.60.0

package/LICENSE

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2026 SeldonFrame (Maxime Houle)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Note: this MIT license applies to the `skills/mcp-server` package (the
+SeldonFrame MCP connector) only. The SeldonFrame platform in the rest of
+this repository remains licensed under AGPL-3.0 — see the LICENSE file at
+the repository root.

package/README.md

@@ -1,113 +1,127 @@
-<!-- mcp-name: io.github.seldonframe/mcp -->
-# @seldonframe/mcp
-
-Official SeldonFrame MCP server for Claude Code and Claude Desktop.
-
-**One command, one real workspace.** The first time you run it, no API key is needed. Say `create_workspace({ name: "Dental Clinic Laval" })` and the server mints a real hosted workspace on `dental-clinic-laval.app.seldonframe.com` — with CRM, Cal.diy booking, Formbricks intake, and Brain v2 pre-installed — and returns live URLs. No signup wall, no "guest mode", no claim step.
-
-## 60-second quickstart
-
-```bash
-# 1. From the repo root
-cd skills/mcp-server && npm install
-
-# 2. Register with Claude Code — no env vars needed
-claude mcp add seldonframe -s user -- node "$(pwd)/src/index.js"
-
-# 3. In Claude Code, just ask:
-#    create_workspace({ name: "My Business OS" })
-```
-
-That call returns something like:
-
-```json
-{
-  "workspace": { "id": "wsp_…", "slug": "my-business-os", "tier": "free" },
-  "urls": {
-    "dashboard": "https://my-business-os.app.seldonframe.com",
-    "book": "https://my-business-os.app.seldonframe.com/book",
-    "intake": "https://my-business-os.app.seldonframe.com/intake"
-  },
-  "installed": ["crm", "caldiy-booking", "formbricks-intake", "brain-v2"],
-  "next": [ "…" ]
-}
-```
-
-Every subsequent tool response includes a `next:` array — follow the rails.
-
-## How auth works
-
-| Situation | What happens |
-|---|---|
-| First ever call | `create_workspace` POSTs with no auth. Server mints a workspace + bearer token. MCP stores the token in `~/.seldonframe/device.json`. |
-| Subsequent calls | MCP sends `Authorization: Bearer <workspace token>` automatically. |
-| `SELDONFRAME_API_KEY` set | Takes precedence over device tokens. Unlocks Pro capabilities. |
-
-You never have to juggle modes. The first workspace is free forever.
-
-## When you need `SELDONFRAME_API_KEY`
-
-- Adding a **second workspace**
-- Connecting a **custom domain**
-- **Full Brain v2** intelligence (heuristic Brain is always free)
-- Publishing, exporting, org-scoped secret rotation
-
-Get one at <https://app.seldonframe.com/settings/api>, then:
-
-```bash
-export SELDONFRAME_API_KEY=sk-…
-```
-
-Restart the MCP server. Your existing workspaces continue to work untouched.
-
-## Install via plugin manifest (one-shot)
-
-The repo ships a `.claude-plugin/plugin.json` at the root. From inside Claude Code:
-
-```
-/plugin install <path-to-repo>
-```
-
-## Install via npm
-
-```bash
-claude mcp add seldonframe -- npx -y @seldonframe/mcp
-```
-
-This is the canonical install command surfaced on the marketing site,
-the `/docs/quickstart` page, and the repo README. It uses `npx -y`
-so users never have to globally install anything; the latest version
-is fetched and run on demand.
-
-## Environment
-
-- `SELDONFRAME_API_KEY` *(optional)* — Enables Pro capabilities (second workspace, custom domains, full Brain v2).
-- `SELDONFRAME_API_BASE` *(optional)* — Override the API base URL. Defaults to `https://app.seldonframe.com/api/v1`.
-
-## Tools
-
-**Workspace:** `create_workspace`, `list_workspaces`, `switch_workspace`, `clone_workspace`, `link_workspace_owner`, `get_workspace_snapshot`.
-**Blocks:** `install_caldiy_booking`, `install_formbricks_intake`, `install_vertical_pack`.
-**Customize (typed, no backend LLM):** `update_landing_content`, `customize_intake_form`, `configure_booking`, `update_theme`.
-**Soul:** `fetch_source_for_soul`, `submit_soul`.
-**Ops:** `list_automations`, `connect_custom_domain`, `export_agent`, `store_secret`, `list_secrets`, `rotate_secret`.
-
-### Architecture: zero backend LLM cost
-
-Natural-language reasoning happens in the MCP session (Claude Code on the user's side). The backend only accepts **structured** commands and applies them deterministically. There is no `seldon_it` endpoint that parses prompts server-side; the old `query_brain` is replaced by `get_workspace_snapshot`, which returns raw state for Claude to reason over. Seldon spends $0 on LLM for the free tier — the user's Claude Code subscription is the reasoning engine.
-
-### Soul compilation (zero cost to Seldon)
-
-Soul compilation runs in **your** Claude Code session, not on Seldon's servers:
-
-1. `fetch_source_for_soul({ url })` — returns up to 256KB of normalized text.
-2. You (the agent) extract a structured Soul object.
-3. `submit_soul({ soul })` — persists it to the workspace.
-
-## Troubleshooting
-
-**`Seldon API 401`** — Your `SELDONFRAME_API_KEY` is invalid or expired. Regenerate at <https://app.seldonframe.com/settings/api>, or unset the env var to fall back to your device token.
-
-**`Seldon API 402`** — You tried a Pro capability without a key. Set `SELDONFRAME_API_KEY` and restart.
-
-**Want to reset device state?** Delete `~/.seldonframe/device.json`. Your hosted workspaces stay live at `app.seldonframe.com`; only the local tokens are cleared.
+<!-- mcp-name: io.github.seldonframe/mcp -->
+# @seldonframe/mcp
+
+Official SeldonFrame MCP server for Claude Code and Claude Desktop.
+
+**One command, one real workspace.** The first time you run it, no API key is needed. Say `create_workspace({ name: "Dental Clinic Laval" })` and the server mints a real hosted workspace on `dental-clinic-laval.app.seldonframe.com` — with CRM, Cal.diy booking, Formbricks intake, and Brain v2 pre-installed — and returns live URLs. No signup wall, no "guest mode", no claim step.
+
+## 60-second quickstart
+
+```bash
+# 1. From the repo root
+cd skills/mcp-server && npm install
+
+# 2. Register with Claude Code — no env vars needed
+claude mcp add seldonframe -s user -- node "$(pwd)/src/index.js"
+
+# 3. In Claude Code, just ask:
+#    create_workspace({ name: "My Business OS" })
+```
+
+That call returns something like:
+
+```json
+{
+  "workspace": { "id": "wsp_…", "slug": "my-business-os", "tier": "free" },
+  "urls": {
+    "dashboard": "https://my-business-os.app.seldonframe.com",
+    "book": "https://my-business-os.app.seldonframe.com/book",
+    "intake": "https://my-business-os.app.seldonframe.com/intake"
+  },
+  "installed": ["crm", "caldiy-booking", "formbricks-intake", "brain-v2"],
+  "next": [ "…" ]
+}
+```
+
+Every subsequent tool response includes a `next:` array — follow the rails.
+
+## How auth works
+
+| Situation | What happens |
+|---|---|
+| First ever call | `create_workspace` POSTs with no auth. Server mints a workspace + bearer token. MCP stores the token in `~/.seldonframe/device.json`. |
+| Subsequent calls | MCP sends `Authorization: Bearer <workspace token>` automatically. |
+| `SELDONFRAME_API_KEY` set | Takes precedence over device tokens. Unlocks Pro capabilities. |
+
+You never have to juggle modes. The first workspace is free forever.
+
+## When you need `SELDONFRAME_API_KEY`
+
+- Adding a **second workspace**
+- Connecting a **custom domain**
+- **Full Brain v2** intelligence (heuristic Brain is always free)
+- Publishing, exporting, org-scoped secret rotation
+
+Get one at <https://app.seldonframe.com/settings/api>, then:
+
+```bash
+export SELDONFRAME_API_KEY=sk-…
+```
+
+Restart the MCP server. Your existing workspaces continue to work untouched.
+
+## Install via plugin manifest (one-shot)
+
+The repo ships a `.claude-plugin/plugin.json` at the root. From inside Claude Code:
+
+```
+/plugin install <path-to-repo>
+```
+
+## Install via npm
+
+```bash
+claude mcp add seldonframe -- npx -y @seldonframe/mcp
+```
+
+This is the canonical install command surfaced on the marketing site,
+the `/docs/quickstart` page, and the repo README. It uses `npx -y`
+so users never have to globally install anything; the latest version
+is fetched and run on demand.
+
+## Environment
+
+- `SELDONFRAME_API_KEY` *(optional)* — Enables Pro capabilities (second workspace, custom domains, full Brain v2).
+- `SELDONFRAME_API_BASE` *(optional)* — Override the API base URL. Defaults to `https://app.seldonframe.com/api/v1`.
+
+## Tools
+
+**Workspace:** `create_workspace`, `list_workspaces`, `switch_workspace`, `clone_workspace`, `link_workspace_owner`, `get_workspace_snapshot`.
+**Blocks:** `install_caldiy_booking`, `install_formbricks_intake`, `install_vertical_pack`.
+**Customize (typed, no backend LLM):** `update_landing_content`, `customize_intake_form`, `configure_booking`, `update_theme`.
+**Soul:** `fetch_source_for_soul`, `submit_soul`.
+**Ops:** `list_automations`, `connect_custom_domain`, `export_agent`, `store_secret`, `list_secrets`, `rotate_secret`.
+
+### Architecture: zero backend LLM cost
+
+Natural-language reasoning happens in the MCP session (Claude Code on the user's side). The backend only accepts **structured** commands and applies them deterministically. There is no `seldon_it` endpoint that parses prompts server-side; the old `query_brain` is replaced by `get_workspace_snapshot`, which returns raw state for Claude to reason over. Seldon spends $0 on LLM for the free tier — the user's Claude Code subscription is the reasoning engine.
+
+### Soul compilation (zero cost to Seldon)
+
+Soul compilation runs in **your** Claude Code session, not on Seldon's servers:
+
+1. `fetch_source_for_soul({ url })` — returns up to 256KB of normalized text.
+2. You (the agent) extract a structured Soul object.
+3. `submit_soul({ soul })` — persists it to the workspace.
+
+## Troubleshooting
+
+**`Seldon API 401`** — Your `SELDONFRAME_API_KEY` is invalid or expired. Regenerate at <https://app.seldonframe.com/settings/api>, or unset the env var to fall back to your device token.
+
+**`Seldon API 402`** — You tried a Pro capability without a key. Set `SELDONFRAME_API_KEY` and restart.
+
+**Want to reset device state?** Delete `~/.seldonframe/device.json`. Your hosted workspaces stay live at `app.seldonframe.com`; only the local tokens are cleared.
+
+## Privacy Policy
+
+Full policy: **<https://www.seldonframe.com/privacy>**
+
+- **Data collection.** The connector runs locally and sends only what you ask it to send: the structured tool commands and business content (workspace names, URLs you point it at, contact and booking details you create) go to `app.seldonframe.com` over HTTPS. The only thing it stores on your machine is a workspace bearer token in `~/.seldonframe/device.json`.
+- **Usage and storage.** Data you submit is stored in your hosted SeldonFrame workspace and used to run it (website, CRM, booking, agents). It is not used to train AI models.
+- **Third-party sharing.** We don't sell your data. Workspace features rely on infrastructure subprocessors (hosting, database, email/SMS delivery when you configure them) as described in the policy above.
+- **Retention.** Workspace data is retained while your workspace is active and deleted on account deletion or on request. The local device token can be removed at any time by deleting `~/.seldonframe/device.json`.
+- **Contact.** <hello@seldonframe.com>
+
+## License
+
+This package (`skills/mcp-server`, the SeldonFrame MCP connector) is [MIT-licensed](./LICENSE). The SeldonFrame platform in the rest of the repository remains AGPL-3.0 — see the repository root `LICENSE`.

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@seldonframe/mcp",
-  "version": "1.59.1",
+  "version": "1.60.0",
   "mcpName": "io.github.seldonframe/mcp",
-  "description": "Open-source GoHighLevel alternative for agencies. 146+ MCP tools that let Claude Code spin up white-labeled client workspaces — CRM, booking, intake forms, landing pages, AI chatbot, and pre-wired agent archetypes (speed-to-lead, missed-call-text-back, review-requester) — in minutes. AGPL-3.0.",
-  "license": "AGPL-3.0-or-later",
+  "description": "Open-source GoHighLevel alternative for agencies. 146+ MCP tools that let Claude Code spin up white-labeled client workspaces — CRM, booking, intake forms, landing pages, AI chatbot, and pre-wired agent archetypes (speed-to-lead, missed-call-text-back, review-requester) — in minutes. MIT-licensed connector (platform: AGPL-3.0).",
+  "license": "MIT",
   "type": "module",
   "bin": {
     "seldonframe-mcp": "src/index.js"
@@ -17,8 +17,10 @@
   },
   "scripts": {
     "start": "node src/index.js",
-    "check:syntax": "node --check --input-type=module < src/index.js && node --check --input-type=module < src/client.js && node --check --input-type=module < src/tools.js && node --check --input-type=module < src/welcome.js",
-    "prepublishOnly": "npm run check:syntax"
+    "check:syntax": "node --check --input-type=module < src/index.js && node --check --input-type=module < src/client.js && node --check --input-type=module < src/tools.js && node --check --input-type=module < src/welcome.js && node --check --input-type=module < src/security.js",
+    "test": "node --test tests/*.test.mjs",
+    "prepublishOnly": "npm run check:syntax && npm run test",
+    "build:mcpb": "npm ci --omit=dev && npx @anthropic-ai/mcpb pack . seldonframe.mcpb"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.4"

package/src/client.js

@@ -2,6 +2,10 @@ import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
 import { homedir, hostname } from "node:os";
 import { join } from "node:path";
 import { VERSION } from "./welcome.js";
+// v1.59.2 — SSRF guard for fetchText, which fetches operator-supplied URLs
+// directly from the MCP server's machine (fetch_source_for_soul's
+// underlying implementation). See src/security.js for the guard + tests.
+import { assertPublicHttpUrl } from "./security.js";
 
 const API_BASE =
   process.env.SELDONFRAME_API_BASE ?? "https://app.seldonframe.com/api/v1";
@@ -170,18 +174,48 @@ export async function api(method, path, opts = {}) {
   return data;
 }
 
+// v1.59.2 — this fetches a URL the OPERATOR supplies (fetch_source_for_soul's
+// "scrape my existing website" feature), directly from the machine the MCP
+// server runs on. Without a guard, an operator (or a compromised/malicious
+// upstream prompt) could point this at http://localhost:PORT, a LAN device,
+// or a cloud metadata endpoint and have the MCP process fetch it on their
+// behalf. assertPublicHttpUrl rejects non-public targets; redirects are
+// followed MANUALLY (max 3 hops) so a public URL that 30x's to a private
+// one can't slip past the initial check.
+const MAX_REDIRECTS = 3;
+
 export async function fetchText(url, { maxBytes = 256 * 1024 } = {}) {
-  const res = await fetch(url, {
-    headers: { "User-Agent": `seldonframe-mcp/${VERSION} (+soul-compiler)` },
-    redirect: "follow",
-  });
+  let currentUrl = url;
+  let res;
+  for (let hop = 0; ; hop++) {
+    await assertPublicHttpUrl(currentUrl);
+    res = await fetch(currentUrl, {
+      headers: { "User-Agent": `seldonframe-mcp/${VERSION} (+soul-compiler)` },
+      redirect: "manual",
+    });
+    const isRedirect = res.status >= 300 && res.status < 400;
+    if (!isRedirect) break;
+    if (hop >= MAX_REDIRECTS) {
+      throw new Error(
+        `Fetch ${url} failed: exceeded ${MAX_REDIRECTS} redirects (stopped at ${currentUrl}).`,
+      );
+    }
+    const location = res.headers.get("location");
+    if (!location) {
+      throw new Error(
+        `Fetch ${currentUrl} returned redirect status ${res.status} with no Location header.`,
+      );
+    }
+    // Location may be relative — resolve against the URL that produced it.
+    currentUrl = new URL(location, currentUrl).toString();
+  }
   if (!res.ok) {
     throw new Error(`Fetch ${url} failed: ${res.status} ${res.statusText}`);
   }
   const raw = await res.text();
   const truncated = raw.length > maxBytes;
   const html = truncated ? raw.slice(0, maxBytes) : raw;
-  return { html, truncated, status: res.status, final_url: res.url };
+  return { html, truncated, status: res.status, final_url: res.url || currentUrl };
 }
 
 export function htmlToText(html) {

package/src/security.js

@@ -0,0 +1,241 @@
+// v1.59.2 — security hardening helpers shared by tools.js.
+//
+// Two independent concerns live here:
+//   1. sniffImageKind — magic-byte detection so upload_workspace_image only
+//      ever forwards bytes that are actually image files (not arbitrary
+//      local files an agent was pointed at).
+//   2. assertPublicHttpUrl — an SSRF guard for machine-side fetches of
+//      operator-supplied URLs (fetch_source_for_soul today). Rejects
+//      loopback / private / link-local targets so the MCP process can't be
+//      used to probe the operator's own LAN or cloud metadata endpoints.
+//
+// Both are pure-ish (assertPublicHttpUrl takes an injectable `lookup` for
+// tests) and have zero dependency on the rest of tools.js so they can be
+// unit-tested in isolation (see tests/security.test.mjs).
+
+const MAX_SVG_BYTES = 1 * 1024 * 1024; // 1MB
+
+// Loose but sufficient: optional UTF-8 BOM, optional XML prolog, optional
+// DOCTYPE, then an <svg ...> or <svg> root tag. Case-insensitive.
+const SVG_PATTERN =
+  /^?\s*(<\?xml[^>]*>\s*)?(<!DOCTYPE[^>]*>\s*)?<svg[\s>]/i;
+
+/**
+ * Sniff the image kind of a buffer from its magic bytes. Returns one of
+ * "png" | "jpeg" | "gif" | "webp" | "svg", or null if the buffer doesn't
+ * look like a recognized image format.
+ *
+ * @param {Buffer} buffer
+ * @returns {"png"|"jpeg"|"gif"|"webp"|"svg"|null}
+ */
+export function sniffImageKind(buffer) {
+  if (!Buffer.isBuffer(buffer) || buffer.length === 0) return null;
+
+  // PNG: 89 50 4E 47 (plus the usual 0D 0A 1A 0A trailer, but the first
+  // four bytes are sufficient to identify it unambiguously).
+  if (
+    buffer.length >= 4 &&
+    buffer[0] === 0x89 &&
+    buffer[1] === 0x50 &&
+    buffer[2] === 0x4e &&
+    buffer[3] === 0x47
+  ) {
+    return "png";
+  }
+
+  // JPEG: FF D8 FF
+  if (
+    buffer.length >= 3 &&
+    buffer[0] === 0xff &&
+    buffer[1] === 0xd8 &&
+    buffer[2] === 0xff
+  ) {
+    return "jpeg";
+  }
+
+  // GIF: ASCII "GIF8" (covers both GIF87a and GIF89a).
+  if (buffer.length >= 4 && buffer.toString("ascii", 0, 4) === "GIF8") {
+    return "gif";
+  }
+
+  // WebP: "RIFF" at offset 0, "WEBP" at offset 8.
+  if (
+    buffer.length >= 12 &&
+    buffer.toString("ascii", 0, 4) === "RIFF" &&
+    buffer.toString("ascii", 8, 12) === "WEBP"
+  ) {
+    return "webp";
+  }
+
+  // SVG: text-based, so magic bytes don't apply — sniff the text instead.
+  // Bound the size before decoding so a huge non-image file doesn't get
+  // fully UTF-8-decoded just to fail this check.
+  if (buffer.length <= MAX_SVG_BYTES) {
+    const text = buffer.toString("utf8");
+    if (SVG_PATTERN.test(text)) return "svg";
+  }
+
+  return null;
+}
+
+// ── SSRF guard ──────────────────────────────────────────────────────────
+
+const BLOCKED_HOSTNAME_SUFFIXES = [".localhost", ".local", ".internal"];
+
+function isBlockedHostname(hostname) {
+  const host = hostname.toLowerCase();
+  if (host === "localhost") return true;
+  return BLOCKED_HOSTNAME_SUFFIXES.some((suffix) => host.endsWith(suffix));
+}
+
+/**
+ * Parse an IPv4 dotted-quad string into four octet numbers, or null if it
+ * isn't a valid literal IPv4 address.
+ * @param {string} host
+ * @returns {[number,number,number,number]|null}
+ */
+function parseIPv4(host) {
+  const parts = host.split(".");
+  if (parts.length !== 4) return null;
+  const octets = [];
+  for (const part of parts) {
+    if (!/^\d{1,3}$/.test(part)) return null;
+    const n = Number(part);
+    if (n < 0 || n > 255) return null;
+    octets.push(n);
+  }
+  return octets;
+}
+
+/**
+ * Is this IPv4 (as an octet quad) inside a non-public range?
+ * @param {[number,number,number,number]} o
+ */
+function isNonPublicIPv4(o) {
+  const [a, b] = o;
+  if (a === 0) return true; // 0.0.0.0/8
+  if (a === 10) return true; // 10/8
+  if (a === 127) return true; // 127/8 (loopback)
+  if (a === 169 && b === 254) return true; // 169.254/16 (link-local)
+  if (a === 172 && b >= 16 && b <= 31) return true; // 172.16/12
+  if (a === 192 && b === 168) return true; // 192.168/16
+  if (a === 100 && b >= 64 && b <= 127) return true; // 100.64/10 (CGNAT)
+  return false;
+}
+
+/**
+ * Is this literal address (v4 or v6 string form) non-public? Handles
+ * IPv4-mapped IPv6 (::ffff:x.x.x.x) by unwrapping to the embedded IPv4.
+ * @param {string} address
+ */
+function isNonPublicIpLiteral(address) {
+  const addr = address.toLowerCase();
+
+  // IPv4-mapped IPv6: ::ffff:x.x.x.x (or the rarer ::ffff:0:x.x.x.x form).
+  const mappedMatch = addr.match(/^::ffff:(?:0:)?(\d{1,3}(?:\.\d{1,3}){3})$/);
+  if (mappedMatch) {
+    const v4 = parseIPv4(mappedMatch[1]);
+    return v4 ? isNonPublicIPv4(v4) : true; // malformed embedded v4 = reject
+  }
+
+  const v4 = parseIPv4(addr);
+  if (v4) return isNonPublicIPv4(v4);
+
+  // IPv6 literal checks.
+  if (addr === "::1") return true; // loopback
+  if (addr === "::") return true; // unspecified
+  if (/^fc[0-9a-f]{2}:/.test(addr) || /^fd[0-9a-f]{2}:/.test(addr)) {
+    return true; // fc00::/7 (unique local) — first byte 0xfc or 0xfd
+  }
+  if (/^fe[89ab][0-9a-f]:/.test(addr)) return true; // fe80::/10 (link-local)
+
+  // Not a recognized literal at all (shouldn't happen given callers only
+  // pass here after confirming it parses as an IP) — fail closed.
+  return false;
+}
+
+/**
+ * Does this string parse as a literal IP address (v4 or v6)? Deliberately
+ * simple — good enough to distinguish "the caller already resolved this to
+ * an IP" from "this is a hostname that still needs DNS resolution."
+ * @param {string} host
+ */
+function isIpLiteral(host) {
+  if (parseIPv4(host)) return true;
+  // Very small heuristic for IPv6 literal form: contains a colon and only
+  // hex digits / colons (optionally with an embedded dotted-quad tail for
+  // the IPv4-mapped form).
+  return /^[0-9a-f:]+(:\d{1,3}(?:\.\d{1,3}){3})?$/i.test(host) && host.includes(":");
+}
+
+/**
+ * Assert that a URL is safe for the MCP server (running on the operator's
+ * machine) to fetch directly: http(s) only, and resolves exclusively to
+ * public IP addresses. Throws with a clear message otherwise.
+ *
+ * Guards against SSRF-style abuse where an operator-supplied "scrape this
+ * URL" argument actually points at localhost, a LAN device, or a cloud
+ * metadata endpoint (169.254.169.254) reachable from wherever the MCP
+ * process happens to run.
+ *
+ * @param {string} urlString
+ * @param {{ lookup?: (hostname: string, opts: { all: true }) => Promise<{address:string,family:number}[]> }} [opts]
+ */
+export async function assertPublicHttpUrl(urlString, opts = {}) {
+  let parsed;
+  try {
+    parsed = new URL(urlString);
+  } catch {
+    throw new Error(`assertPublicHttpUrl: "${urlString}" is not a valid URL.`);
+  }
+
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(
+      `assertPublicHttpUrl: protocol "${parsed.protocol}" is not allowed for "${urlString}" — only http: and https: are permitted.`,
+    );
+  }
+
+  // URL.hostname strips brackets from IPv6 literals (e.g. "[::1]" -> "::1").
+  const hostname = parsed.hostname;
+
+  if (isBlockedHostname(hostname)) {
+    throw new Error(
+      `assertPublicHttpUrl: hostname "${hostname}" is blocked (localhost / .localhost / .local / .internal).`,
+    );
+  }
+
+  if (isIpLiteral(hostname)) {
+    if (isNonPublicIpLiteral(hostname)) {
+      throw new Error(
+        `assertPublicHttpUrl: "${hostname}" is not a public IP address.`,
+      );
+    }
+    return;
+  }
+
+  const lookup =
+    opts.lookup ?? (await import("node:dns/promises")).lookup;
+  let records;
+  try {
+    records = await lookup(hostname, { all: true });
+  } catch (err) {
+    throw new Error(
+      `assertPublicHttpUrl: DNS lookup for "${hostname}" failed — ${err?.message ?? err}`,
+    );
+  }
+
+  if (!Array.isArray(records) || records.length === 0) {
+    throw new Error(
+      `assertPublicHttpUrl: DNS lookup for "${hostname}" returned no addresses.`,
+    );
+  }
+
+  for (const record of records) {
+    const address = record?.address ?? record;
+    if (typeof address !== "string" || isNonPublicIpLiteral(address)) {
+      throw new Error(
+        `assertPublicHttpUrl: "${hostname}" resolves to a non-public address (${address}) — refusing to fetch.`,
+      );
+    }
+  }
+}

package/src/tools.js

@@ -31,6 +31,10 @@ import { buildFinalizeSummary } from "./finalize-summary.js";
 // the agent token budget that v1.10.0's image_data_b64 path was bound by.
 import { readFileSync } from "node:fs";
 import path from "node:path";
+// v1.59.2 — security hardening: image-content sniffing (upload_workspace_image)
+// and the SSRF guard for machine-side fetches of operator-supplied URLs
+// (fetch_source_for_soul). See src/security.js for details + tests.
+import { sniffImageKind, assertPublicHttpUrl } from "./security.js";
 
 const str = (description, extra = {}) => ({ type: "string", description, ...extra });
 const obj = (properties, required = []) => ({
@@ -629,12 +633,17 @@ export const TOOLS = [
   {
     name: "send_welcome_email",
     description:
-      "Email the active workspace's four key URLs (landing, booking, intake, admin dashboard) to a user. Use this AFTER create_workspace, only when the user has explicitly given their email — never auto-send. The admin URL is bearer-token-scoped and expires in 7 days. Example: send_welcome_email({ email: 'alice@example.com', name: 'Alice' }).",
+      "Email the active workspace's four key URLs (landing, booking, intake, admin dashboard) to a user. Use this AFTER create_workspace, only when the user has explicitly given their email — never auto-send. The admin URL is bearer-token-scoped and expires in 7 days. " +
+      "If the workspace has an AI chatbot (create_full_workspace's response includes chatbot_embed_snippet + chatbot_agent_id), pass chatbot_url + chatbot_embed_snippet + chatbot_status so the welcome email also shows the chatbot card with its embed snippet — operators otherwise never learn the workspace shipped with a chatbot. All three are optional; omit them to send the classic 4-URL email. " +
+      "Example: send_welcome_email({ email: 'alice@example.com', name: 'Alice', chatbot_url: 'https://acme.app.seldonframe.com/chat', chatbot_embed_snippet: '<script src=\"...\" async></script>', chatbot_status: 'test' }).",
     inputSchema: obj(
       {
         email: str("Recipient email address."),
         name: str("Optional recipient name (used in the greeting)."),
         workspace_id: str("Optional workspace override. Defaults to active workspace."),
+        chatbot_url: str("Optional. Public chatbot URL — include when the workspace has an AI chatbot (see chatbot_embed_snippet + chatbot_agent_id from create_full_workspace's response)."),
+        chatbot_embed_snippet: str("Optional. The <script> embed snippet for the chatbot (from create_full_workspace's chatbot_embed_snippet). Required alongside chatbot_url/chatbot_status to render the chatbot card."),
+        chatbot_status: str("Optional. \"live\" or \"test\" — reflects the chatbot's current publish status. Defaults the card copy accordingly."),
       },
       ["email"],
     ),
@@ -669,6 +678,18 @@ export const TOOLS = [
       const appHost = API_INFO.base.replace(/\/api\/v1\/?$/, "");
       const adminUrl = `${appHost}/admin/${encodeURIComponent(workspaceId)}?token=${encodeURIComponent(bearer)}`;
 
+      // Optional chatbot passthrough — only include the card when the
+      // caller supplied enough to render it (url + embed_snippet).
+      // Omitted entirely otherwise so this stays backward-compatible.
+      const chatbot =
+        a.chatbot_url && a.chatbot_embed_snippet
+          ? {
+              url: a.chatbot_url,
+              embed_snippet: a.chatbot_embed_snippet,
+              status: a.chatbot_status === "live" ? "live" : "test",
+            }
+          : undefined;
+
       await api("POST", "/email/send-welcome", {
         body: {
           email: a.email,
@@ -678,6 +699,7 @@ export const TOOLS = [
             booking_url: publicUrls.book,
             intake_url: publicUrls.intake,
             admin_url: adminUrl,
+            ...(chatbot ? { chatbot } : {}),
           },
         },
         workspace_id: workspaceId,
@@ -1399,10 +1421,13 @@ export const TOOLS = [
   {
     name: "fetch_source_for_soul",
     description:
-      "Fetch a URL and return normalized text (headings + body, up to 256KB). Use this to gather raw content from the operator's existing website; then extract a structured business profile and save it with submit_soul. Zero LLM cost to SeldonFrame — extraction runs in this session.",
+      "Fetch a URL and return normalized text (headings + body, up to 256KB). Use this to gather raw content from the operator's existing website; then extract a structured business profile and save it with submit_soul. Zero LLM cost to SeldonFrame — extraction runs in this session. " +
+      "v1.59.2 — only public http(s) URLs are fetched: the MCP server rejects localhost / private-network / link-local targets (and any redirect that lands on one) before making the request. Use this for the operator's real, public-facing website only.",
     inputSchema: obj(
       {
-        url: str("Absolute URL to fetch."),
+        url: str(
+          "Absolute URL to fetch. Must be a public http(s) URL — localhost, LAN, and other private-network addresses are rejected.",
+        ),
       },
       ["url"],
     ),
@@ -4088,6 +4113,7 @@ export const TOOLS = [
       "(b) `local_file_path` (v1.10.1+) — absolute path on the operator's machine. The MCP server (running locally) reads the file and forwards bytes to the backend. Best path for files on the operator's desktop. file_name + content_type derived from the path. " +
       "(c) `image_data_b64` (legacy v1.10.0) — image bytes base64-encoded. Use only when you've generated bytes yourself (e.g. dynamic image gen) and there's no URL or path. Be aware: the encoded string consumes your tool-call token budget; for files >~12 KB raw, prefer (a) or (b). " +
       "Max 5 MB across all paths. Allowed types: image/png, image/jpeg, image/webp, image/svg+xml, image/gif. " +
+      "v1.59.2 — for local_file_path and image_data_b64, the MCP server sniffs the actual bytes (magic numbers / SVG root tag) before uploading anything; a file that isn't a recognized image format is rejected locally and never reaches the network. This tool cannot be used to exfiltrate arbitrary local files under an image_url. " +
       "Returns the public Blob URL on success; that URL is now live on the workspace's public surface within seconds. " +
       "Antifragile design: server only validates file shape + applies URL to the right column. Your LLM picks which slot ('they said logo, that maps to slot=logo'). As you get better at intent-mapping, the harness doesn't change.",
     inputSchema: obj(
@@ -4162,6 +4188,26 @@ export const TOOLS = [
             `upload_workspace_image: failed to read local_file_path "${filePath}" — ${err?.message ?? err}`,
           );
         }
+        // v1.59.2 — this is the local-file-read path (the MCP server reads
+        // whatever absolute path it's given). Enforce the size cap and
+        // sniff the actual bytes BEFORE they're base64'd and sent anywhere,
+        // so this tool can only ever upload real images — not an
+        // agent-mediated read of an arbitrary local file.
+        if (buf.length > 5 * 1024 * 1024) {
+          return {
+            ok: false,
+            error: "file_too_large",
+            message: `upload_workspace_image: "${filePath}" is ${buf.length} bytes, over the 5MB max.`,
+          };
+        }
+        if (sniffImageKind(buf) === null) {
+          return {
+            ok: false,
+            error: "not_an_image",
+            message:
+              "Not a recognized image file (png, jpeg, gif, webp, svg). This tool only uploads images.",
+          };
+        }
         // Derive file_name + content_type from the path extension, mirroring
         // the server-side image_url logic so the two paths feel identical
         // to the operator.
@@ -4186,12 +4232,40 @@ export const TOOLS = [
         }
       } else {
         // image_data_b64 — caller supplied bytes directly.
-        body.image_data_b64 = args.image_data_b64;
         if (!args.file_name || !args.content_type) {
           throw new Error(
             "upload_workspace_image: file_name and content_type are required with image_data_b64. (image_url and local_file_path auto-derive them.)",
           );
         }
+        // v1.59.2 — same bytes-in, sniff-before-send discipline as the
+        // local_file_path branch above (this tool only uploads images,
+        // regardless of which of the three sources supplied the bytes).
+        let decoded;
+        try {
+          decoded = Buffer.from(args.image_data_b64, "base64");
+        } catch (err) {
+          return {
+            ok: false,
+            error: "invalid_base64",
+            message: `upload_workspace_image: image_data_b64 could not be decoded — ${err?.message ?? err}`,
+          };
+        }
+        if (decoded.length > 5 * 1024 * 1024) {
+          return {
+            ok: false,
+            error: "file_too_large",
+            message: `upload_workspace_image: decoded image_data_b64 is ${decoded.length} bytes, over the 5MB max.`,
+          };
+        }
+        if (sniffImageKind(decoded) === null) {
+          return {
+            ok: false,
+            error: "not_an_image",
+            message:
+              "Not a recognized image file (png, jpeg, gif, webp, svg). This tool only uploads images.",
+          };
+        }
+        body.image_data_b64 = args.image_data_b64;
         body.file_name = args.file_name;
         body.content_type = args.content_type;
       }
@@ -4588,7 +4662,8 @@ export const TOOLS = [
       "The OPERATOR pays the LLM provider directly (Anthropic / OpenAI / etc.); SF charges separately for agent platform usage. " +
       "Stored encrypted at rest using the deployment's ENCRYPTION_KEY. " +
       "Operators get keys from console.anthropic.com (recommended for v1.26.x — best tool-use support) or platform.openai.com. " +
-      "v1.28+ AUTO-DETECT: pass api_key='env' (or omit api_key entirely) and the MCP server will read process.env.ANTHROPIC_API_KEY / OPENAI_API_KEY from its own environment. Most Claude Code users already have this set (it's how Claude Code works), so this lets a solo SF client onboard with zero key-paste step. Returns { ok: false, error: 'no_env_key' } if the env var isn't set; in that case the user must paste the key explicitly. " +
+      "v1.28+ AUTO-DETECT: pass api_key='env' (or omit api_key entirely) to read process.env.ANTHROPIC_API_KEY / OPENAI_API_KEY from the MCP server's own environment. " +
+      "v1.59.2 — CONSENT REQUIRED before storing an env-detected key: ask the user first ('I found an Anthropic key in your environment — OK to store it in your SeldonFrame workspace?'), then re-call with confirm_store_env_key: true. Without that flag, this tool reports the env var it found and stops — it does NOT transmit the value. A key passed explicitly via api_key is consent by definition and is never gated. Returns { ok: false, error: 'no_env_key' } if the env var isn't set; in that case the user must paste the key explicitly. " +
       "Skip if the workspace already has a key — agents fail-graceful with 'I'm not set up yet' if no key configured, so a 'not configured' chatbot response means CALL THIS TOOL.",
     inputSchema: obj(
       {
@@ -4600,8 +4675,13 @@ export const TOOLS = [
             "LLM provider. v1.26 ships full Anthropic support (tool use, streaming-ready). OpenAI support for chat is partial — recommend Anthropic for production agents.",
         },
         api_key: str(
-          "API key. Anthropic keys start with 'sk-ant-...'. Stored encrypted; never echoed back. v1.28+ AUTO-DETECT: pass 'env' (literal string) or omit entirely to read process.env.{ANTHROPIC,OPENAI}_API_KEY from the MCP server's local environment.",
+          "API key. Anthropic keys start with 'sk-ant-...'. Stored encrypted; never echoed back. v1.28+ AUTO-DETECT: pass 'env' (literal string) or omit entirely to read process.env.{ANTHROPIC,OPENAI}_API_KEY from the MCP server's local environment (subject to the confirm_store_env_key consent gate below). Passing the key explicitly here IS consent — it's never gated.",
         ),
+        confirm_store_env_key: {
+          type: "boolean",
+          description:
+            "Set true ONLY after the user has explicitly confirmed storing the API key found in this machine's environment variables in their SeldonFrame workspace.",
+        },
       },
       ["workspace_id", "provider"],
     ),
@@ -4628,6 +4708,20 @@ export const TOOLS = [
             envName,
           };
         }
+        // v1.59.2 — CONSENT GATE. Finding a key in the environment is not
+        // the same as the operator agreeing to store it server-side.
+        // Without explicit confirm_store_env_key: true, stop here and
+        // tell the agent to go get consent — never transmit the value.
+        if (args.confirm_store_env_key !== true) {
+          return {
+            ok: true,
+            needs_consent: true,
+            env_var_found: envName,
+            message:
+              `Found ${envName} in the environment. SeldonFrame can store this key in the workspace (server-side, used only to power the hosted chatbot/agent). ` +
+              `Ask the user for permission first, then re-call this tool with confirm_store_env_key: true.`,
+          };
+        }
       }
 
       const result = await api("POST", "/agents", {
@@ -4652,7 +4746,7 @@ export const TOOLS = [
     name: "create_agent",
     description:
       "USE WHEN USER SAYS: 'add a chatbot to my website', 'add an AI assistant to my landing page', 'put a chat widget on my site', 'create a website chatbot', 'add an AI agent that answers customer questions', 'I want chat on my homepage', 'build me a chatbot for [business]'. " +
-      "DON'T confuse with: list_blocks (chat widgets are NOT a block type — agents are a separate primitive); send_conversation_turn (that's for inbound SMS/email auto-reply, NOT a website widget). If the operator wants chat on their website, THIS is the tool. " +
+      "DON'T confuse with: list_blocks (chat widgets are NOT a block type — agents are a separate primitive); send_conversation_turn (that's for inbound SMS/email auto-reply, NOT a website widget); generate_agent (for an agent that ACTS on bookings/leads/a schedule — review requester, speed-to-lead, follow-up — use generate_agent instead; THIS tool only builds a website chat widget with no trigger). If the operator wants chat on their website, THIS is the tool. " +
       "Creates a new agent for this workspace. Agents are conversational interfaces (web chat, voice, SMS) that answer FAQs, book appointments, and escalate to humans — composed from typed primitives + the workspace's Soul (industry, voice, services). " +
       "WHAT GETS COMPOSED AUTOMATICALLY: persona derived from soul.industry + soul.voice; FAQ knowledge from your `faq` array; pricing facts from `pricing_facts` (validators block any $-amount the agent invents that's not in this list); typed tools (look_up_availability, book_appointment, find_my_existing_appointment, escalate_to_human, provide_faq_answer). " +
       "WHAT YOU PROVIDE: name, archetype (website-chatbot for v1.26.x+; voice-receptionist + sms-followup-bot queued), channel (web_chat / voice / sms / email), inline FAQ pairs, allowed pricing facts, optional greeting. " +
@@ -4852,6 +4946,50 @@ export const TOOLS = [
     },
   },
 
+  // ───────────────────────────────────────────────────────────────────────
+  // v1.60.0 — GENERATE. Build an agent from ONE plain-English sentence. This
+  // is the front door for anything that DOES something on an event/schedule
+  // (review requester, speed-to-lead, after-hours receptionist) — a real,
+  // event-firing agent (trigger + skill + guardrails), not a website widget.
+  // Wires POST /api/v1/agents/generate → the same deterministic generator
+  // (parseAgentIntent → assembleAgentBundle, LLM-classify optional and
+  // fail-soft) the Studio dashboard uses. Returns a template_id; the next
+  // step is ALWAYS deploy_agent to make it live and firing.
+  // ───────────────────────────────────────────────────────────────────────
+
+  {
+    name: "generate_agent",
+    description:
+      "USE WHEN USER SAYS: 'create a google review requester for my dentist office', 'text new leads instantly', 'build a speed-to-lead texter', 'set up an after-hours receptionist', 'make an agent that follows up after every booking'. " +
+      "Build a working AI agent from a plain-English description. It classifies the intent and assembles a deployable agent — trigger (e.g. fires on booking.completed or lead.created, or answers inbound calls/chats) + skill (the playbook it follows) + guardrails (quiet hours, rate caps, safety rubric) — all wired automatically, no manual configuration. " +
+      "Returns a template_id — then call deploy_agent with { source: { template_id } } to make it live and firing on its trigger (e.g. after every booking, or the instant a new lead arrives). " +
+      "USE THIS (not create_agent) for ANY agent that DOES something on an event or a schedule — a review request after a job, an instant reply to a new lead, a scheduled recap. create_agent is ONLY for a website chat widget with no trigger. " +
+      "Delivery note: a freshly generated event-outbound agent (review-requester / speed-to-lead) defaults to EMAIL so it can send a real message today without the workspace connecting a phone number first (see `warnings` in the response); mention texting/SMS explicitly in your description if you want it to try SMS instead — full delivery still needs the workspace's own Twilio connected, surfaced by deploy_agent as a 'telephony' requirement.",
+    inputSchema: obj(
+      {
+        workspace_id: str("Workspace id (bearer workspace)."),
+        description: str(
+          "One plain-English sentence describing the agent to build, e.g. 'a Google review requester for a dentist' or 'a speed-to-lead texter for new website leads'.",
+        ),
+        review_url: str(
+          "Optional: the business's Google review link. Wins over any URL found in the description. Only relevant for a review-requester agent; omit otherwise.",
+        ),
+      },
+      ["workspace_id", "description"],
+    ),
+    handler: async (args) => {
+      const ws = args.workspace_id;
+      const result = await api("POST", "/agents/generate", {
+        body: {
+          description: args.description,
+          review_url: args.review_url ?? undefined,
+        },
+        workspace_id: ws,
+      });
+      return result;
+    },
+  },
+
   // ───────────────────────────────────────────────────────────────────────
   // v1.59.0 — IMPROVE. The 5th verb of the builder ladder: build → test →
   // deploy → sell → improve. `improve_agent` replays an agent's own recent
@@ -5009,7 +5147,8 @@ export const TOOLS = [
       "(2) creates a website-chatbot agent with the FAQ + pricing facts + greeting you provide; " +
       "(3) publishes to status='test' so the operator can sandbox-test before going live (the eval gate runs only on 'live'); " +
       "(4) returns the embed snippet, dashboard URL, and clear next-steps. " +
-      "USE THIS as the default for natural-language 'create a chatbot' requests. Fall back to the primitive tools (configure_llm_provider + create_agent + publish_agent) only when you need a custom flow (e.g. agency managing multiple operators with separate Anthropic billing — pass anthropic_api_key explicitly per workspace).",
+      "USE THIS as the default for natural-language 'create a chatbot' requests. Fall back to the primitive tools (configure_llm_provider + create_agent + publish_agent) only when you need a custom flow (e.g. agency managing multiple operators with separate Anthropic billing — pass anthropic_api_key explicitly per workspace). " +
+      "v1.59.2 — CONSENT REQUIRED before storing an env-detected key: if no anthropic_api_key is passed and process.env.ANTHROPIC_API_KEY is found, this tool does NOT store it on the first call. It reports what it found and stops (nothing else in the bundle runs yet). Ask the user for permission, then re-call with confirm_store_env_key: true to proceed with the full bundle. If neither an explicit key nor an env key is present, the bundle proceeds anyway on the SeldonFrame platform key — no consent needed because nothing of the operator's is transmitted.",
     inputSchema: obj(
       {
         workspace_id: str("Workspace id (bearer workspace)."),
@@ -5045,8 +5184,13 @@ export const TOOLS = [
           "First message shown when chat opens (~120 chars). E.g. 'Hi! Asking about HVAC service in Phoenix? I can book you in or answer common questions.' Default if omitted: 'Hi! How can I help you today?'",
         ),
         anthropic_api_key: str(
-          "Optional explicit Anthropic API key (sk-ant-...). If omitted, reads from process.env.ANTHROPIC_API_KEY in the MCP server's environment. Pass explicitly for white-label scenarios (different operator = different Anthropic billing). Skipped entirely if the workspace already has a key configured.",
+          "Optional explicit Anthropic API key (sk-ant-...). If omitted, reads from process.env.ANTHROPIC_API_KEY in the MCP server's environment (subject to the confirm_store_env_key consent gate below). Pass explicitly for white-label scenarios (different operator = different Anthropic billing) — passing it here IS consent, never gated. Skipped entirely if the workspace already has a key configured.",
         ),
+        confirm_store_env_key: {
+          type: "boolean",
+          description:
+            "Set true ONLY after the user has explicitly confirmed storing the API key found in this machine's environment variables in their SeldonFrame workspace.",
+        },
       },
       ["workspace_id", "name"],
     ),
@@ -5072,6 +5216,24 @@ export const TOOLS = [
       // that v1.40.9 Sunset Plumbing test exposed.
       const explicitKey = args.anthropic_api_key;
       const envKey = process.env.ANTHROPIC_API_KEY;
+
+      // v1.59.2 — CONSENT GATE. An env-inherited key is about to be
+      // transmitted to the SF API and stored on the workspace; the
+      // operator hasn't agreed to that yet just by virtue of having the
+      // var set in their shell. Stop the ENTIRE bundle here (before
+      // create_agent / publish_agent run) and ask first. An explicit
+      // anthropic_api_key arg is consent by definition and skips this.
+      if (!explicitKey && envKey && args.confirm_store_env_key !== true) {
+        return {
+          ok: true,
+          needs_consent: true,
+          env_var_found: "ANTHROPIC_API_KEY",
+          message:
+            "Found ANTHROPIC_API_KEY in the environment. SeldonFrame can store this key in the workspace (server-side, used only to power the hosted chatbot/agent). " +
+            "Ask the user for permission first, then re-call this tool with confirm_store_env_key: true.",
+        };
+      }
+
       const keyToUse = explicitKey || envKey;
       let llmMode = "platform";
       if (keyToUse) {

package/src/welcome.js

@@ -8,7 +8,7 @@
 // stripped. `create_full_workspace` is the only workspace-creation
 // path mentioned anywhere in this briefing.
 
-export const VERSION = "1.59.1";
+export const VERSION = "1.59.2";
 
 export const WELCOME_MARKDOWN = `# SeldonFrame — create a real Business OS in one conversation
 
@@ -108,8 +108,17 @@ of v1.28.0 this is **ONE tool call**:
      // platform key automatically. Operator can BYOK later via
      // /settings/integrations/llm. Pass explicitly only when you need
      // per-workspace billing isolation (white-label / agency).
+     //
+     // v1.59.2 — if you omit anthropic_api_key AND the MCP server's
+     // environment has ANTHROPIC_API_KEY set, this call returns
+     // needs_consent: true instead of building anything. ASK THE USER
+     // before storing a key found in the environment ("I found an
+     // Anthropic key in your environment — OK to store it in your
+     // SeldonFrame workspace?"), then re-call with
+     // confirm_store_env_key: true.
    })
    // → returns { agent, embed_url, turn_api_url, turn_api_method: "POST", dashboard_url, llm_mode, next_steps }
+   // or, if an env key needs consent first: { ok: true, needs_consent: true, env_var_found, message }.
    // Internally: creates agent, publishes to test. Skips set_llm_key when
    // no key supplied (platform fallback in lib/ai/client.ts handles inference).
 
@@ -125,18 +134,25 @@ billing (e.g. Acme AI agency managing Cypress Pine HVAC + Sunset
 Dental), pass anthropic_api_key explicitly per workspace instead of
 relying on platform fallback.
 
-### v1.40.10 — LLM key handling
+### v1.40.10 — LLM key handling (v1.59.2 — consent gate on path 2)
 
 build_website_chatbot has THREE possible LLM-key paths, in priority
 order:
 
 1. **Explicit** — \`anthropic_api_key: 'sk-ant-...'\` arg → workspace
-   stored as BYOK, operator pays Anthropic directly.
+   stored as BYOK, operator pays Anthropic directly. Passing the key
+   explicitly IS consent — this path is never gated.
 2. **Env-inherited** — process.env.ANTHROPIC_API_KEY in the MCP
-   server's environment → workspace stored as BYOK with that key.
+   server's environment → the DEFAULT is to ASK FIRST, not store
+   silently. The first call (no confirm_store_env_key) returns
+   \`{ needs_consent: true, env_var_found, message }\` and does nothing
+   else. Tell the operator what was found and ask permission; only
+   after they agree, re-call with \`confirm_store_env_key: true\` to
+   store the key as BYOK and continue the bundle.
 3. **Platform fallback** — neither explicit nor env → no BYOK
-   stored. The workspace uses SeldonFrame's platform Anthropic key
-   automatically (via lib/ai/client.ts -> getAIClient). Operator
+   stored, no consent needed (nothing of the operator's is
+   transmitted). The workspace uses SeldonFrame's platform Anthropic
+   key automatically (via lib/ai/client.ts -> getAIClient). Operator
    sees no setup friction; they can BYOK later in
    /settings/integrations/llm.
 
@@ -145,7 +161,8 @@ the operator: "Your chatbot is using SeldonFrame's shared Anthropic
 key. You can switch to your own anytime in Settings → Integrations
 → LLM, no code changes needed." This removes the "where do I get an
 Anthropic key" question from the critical path of a first-time
-chatbot setup.
+chatbot setup — and it means path 2's consent step only ever comes up
+when an env key actually exists, not as a blocking default.
 
 For custom flows (different archetype, custom capability allowlist,
 multi-step blueprint construction), drop down to the primitives: