mcp-scraper 0.81.0 → 0.83.1

package/CHANGELOG.md

@@ -4,6 +4,47 @@ All notable changes to MCP Scraper are documented here. The format is based on [
 
 ## [Unreleased]
 
+## [0.83.1] - 2026-09-01
+
+### Fixed
+
+- Allowed the X-Ray Pixel to authenticate normal same-origin runtime-manifest and health requests from their approved `Referer` hostname when browsers omit the `Origin` header, while preserving approved-domain enforcement and failing closed when neither header identifies an HTTP origin.
+
+## [0.83.0] - 2026-09-01
+
+### Added
+
+- Added a digest-bound X-Ray runtime manifest that remotely publishes versioned event rules through the globally installed Pixel, reports bounded selector health, observes SPA and dynamic DOM changes, and preserves consent and privacy boundaries without requiring site-source access.
+- Added pre-registered X-Ray experiments with deterministic assignment, separate exact-revision approval, canary and production states, five allowlisted presentation operations, exposure evidence, fixed-horizon evaluation, sample-ratio checks, and pause/kill rollback controls.
+- Added `analytics_create_experiment`, `analytics_set_experiment_state`, and `analytics_get_experiment`, expanding the governed unified MCP catalog to 363 tools.
+
+### Changed
+
+- Replaced X-Ray's repository, branch, writer, patch, and draft-PR setup model with one-time global tag verification followed by X-Ray-owned measurement-manifest publication. GitHub remains an optional general integration and is no longer part of X-Ray setup.
+- Advanced the canonical X-Ray install protocol to 2.0.0 and aligned its MCP Resource, Prompt, npm CLI, public Markdown, well-known JSON, REST contract, and dashboard projections around the tag-only control plane.
+
+### Migration
+
+- Advance the analytics schema to `2026-09-01.1` before enabling runtime manifests or experiments. Existing active event definitions remain compatible and measurement publication does not activate a visitor experiment.
+
+## [0.82.0] - 2026-08-31
+
+### Added
+
+- Added `analytics_setup_site` with explicit prepare, apply, and verify operations, durable owner-bound revisions and receipts, whole-site Pixel and CTA discovery, eight-dimensional readiness, and truthful first-customer answers at zero MCP Scraper Credit charge under an active X-Ray entitlement.
+- Added a versioned agent-install protocol across public Markdown/JSON, npm CLI output, an MCP Resource, an owner-isolated setup ResourceTemplate, and the `setup_xray_site` Prompt for Codex, Claude, Cursor, Windsurf, and Cline.
+- Added a trusted internal `xray_entitlement` extraction billing class that persists zero-charge jobs without wallet holds, debit keys, or ledger settlement.
+
+### Changed
+
+- Expanded the unified MCP catalog from 356 to 360 tools with operation-specific setup contracts, generated REST parity, private discovery caching where supported, and a measured reviewed catalog budget.
+- Added privacy-safe semantic CTA metadata for placement, component, action, destination, and plan while excluding labels, form values, URLs and query strings, email addresses, phone-like values, and arbitrary datasets.
+
+### Fixed
+
+- Installed exactly one first-party Pixel across both the Next.js marketing application and all eight static/API blog documents, and added reusable semantic CTA tagging to shared marketing components.
+- Removed the duplicate initial PageView caused by pre-granted consent while retaining one PageView for each actual SPA navigation or blocked-to-granted consent transition.
+
 ## [0.81.0] - 2026-08-31
 
 ### Added
@@ -1544,7 +1585,10 @@ All notable changes to MCP Scraper are documented here. The format is based on [
 - Write actions remain unavailable until the account owner explicitly enables them.
 - Provider-specific connection data is normalized into one agent-facing contract.
 
-[Unreleased]: https://github.com/VilovietaSEO/mcp-scraper/compare/v0.81.0...HEAD
+[Unreleased]: https://github.com/VilovietaSEO/mcp-scraper/compare/v0.83.1...HEAD
+[0.83.1]: https://github.com/VilovietaSEO/mcp-scraper/compare/v0.83.0...v0.83.1
+[0.83.0]: https://github.com/VilovietaSEO/mcp-scraper/compare/v0.82.0...v0.83.0
+[0.82.0]: https://github.com/VilovietaSEO/mcp-scraper/compare/v0.81.0...v0.82.0
 [0.81.0]: https://github.com/VilovietaSEO/mcp-scraper/compare/v0.80.0...v0.81.0
 [0.80.0]: https://github.com/VilovietaSEO/mcp-scraper/compare/v0.79.4...v0.80.0
 [0.79.4]: https://github.com/VilovietaSEO/mcp-scraper/compare/v0.79.3...v0.79.4

package/README.md

@@ -175,7 +175,7 @@ Build the branded one-click bundle:
 npm run build:mcpb
 ```
 
-The generated bundle is written to `build/mcpb/mcp-scraper-<version>.mcpb` and copied to `public/downloads/` for the hosted download. The current public bundle is `https://mcpscraper.dev/downloads/mcp-scraper.mcpb` (`0.81.0`, SHA-256 `866faf8d18568514b29f407c6789bc779e895c9780cfcee27eb958cb079cf244`). Install it by opening or dragging it into Claude Desktop. Claude displays the `MCP Scraper` install card, icon, API-key configuration field, and manually curated current-release message from the bundle manifest.
+The generated bundle is written to `build/mcpb/mcp-scraper-<version>.mcpb` and copied to `public/downloads/` for the hosted download. The current public bundle is `https://mcpscraper.dev/downloads/mcp-scraper.mcpb` (`0.83.1`, SHA-256 `57e9dfb6d83aa729cf90ca4654f72a4c8b16f219cbdbde737f72f23f36f3b46c`). Install it by opening or dragging it into Claude Desktop. Claude displays the `MCP Scraper` install card, icon, API-key configuration field, and manually curated current-release message from the bundle manifest.
 
 The MCPB install exposes every tool — web-intelligence plus all `browser_*` tools — through the one `mcp-scraper` server.
 
@@ -337,7 +337,7 @@ The `mcp-scraper` server (and the MCPB bundle, which runs it) exposes both secti
 
 All MCP tools return `structuredContent` with the IDs, URLs, CSV paths, transcripts, browser session handles, replay paths, artifacts, recipe fields, or blueprint fields needed by the next step, plus readable text content for compatibility. Runtime `tools/list` omits output schemas so strict clients can register the complete catalog; the generated developer manifest retains every canonical output schema for validation and typed SDK generation. All tools carry MCP annotations; file-writing tools such as replay downloads and annotations state their filesystem side effects.
 
-The canonical tool inventory is generated at `docs/mcp-tool-manifest.generated.json`. The unified server exposes 356 tools: 255 scraper, browser, workflow, billing, connected-service, and personal-assistant tools plus 101 durable-memory tools. The scraper-side inventory includes complete Gmail selection, message, attachment, export, bulk-action, and Memory-import workflows; governed personal-assistant commands, messaging, approvals, grants, number setup, and execution readback; durable PAA starts and status; rendered site-content similarity; governed Local Sourcebook and Transparent Commons workflows; direct site-export reads; Editorial Reading Room and News Publisher templates; and production X-Ray analytics, attribution, CRM policy and receipt, campaign, export, and scheduled-report tools. Successful evidence-compiled Local Sourcebook revisions publish automatically to their canonical `localsourcebook.com` category profile and review URLs; administrator controls handle exceptional rejection or unpublishing. Release verification compares the exact local and hosted tool-name sets, not only the count.
+The canonical tool inventory is generated at `docs/mcp-tool-manifest.generated.json`. The unified server exposes 363 tools: 262 scraper, browser, workflow, billing, connected-service, and personal-assistant tools plus 101 durable-memory tools. The scraper-side inventory includes complete Gmail selection, message, attachment, export, bulk-action, and Memory-import workflows; governed personal-assistant commands, messaging, approvals, grants, number setup, and execution readback; durable PAA starts and status; rendered site-content similarity; governed Local Sourcebook and Transparent Commons workflows; direct site-export reads; Editorial Reading Room and News Publisher templates; and production X-Ray setup, analytics, attribution, CRM policy and receipt, campaign, export, and scheduled-report tools. Successful evidence-compiled Local Sourcebook revisions publish automatically to their canonical `localsourcebook.com` category profile and review URLs; administrator controls handle exceptional rejection or unpublishing. Release verification compares the exact local and hosted tool-name sets, not only the count.
 
 For contract parity, stdio and MCPB memory calls invoke the matching public tool on the hosted MCP Scraper `/mcp` endpoint. The hosted aggregate runtime owns MCP Scraper-specific billing, scheduling, credential, and in-process cutover policy; its internal `/memory/mcp-call` bridge is a fallback to the standalone memory service, not the public stdio execution path. Direct `mcp-memory` OAuth and stdio clients continue to use `memory.mcpscraper.dev` and must be verified as a separate dependent release surface.
 

package/dist/{analytics-repository-YOY5KMOD.js → analytics-repository-GA6P5S5J.js}

@@ -85,7 +85,7 @@ import {
   updateAnalyticsPixel,
   upsertAnalyticsAdSpend,
   upsertAnalyticsHostGroup
-} from "./chunk-HEUMDX4I.js";
+} from "./chunk-CNAJWRJT.js";
 import "./chunk-C5Z4OFKW.js";
 import "./chunk-YXNDOQXN.js";
 export {

package/dist/bin/api-server.js

@@ -17,8 +17,8 @@ loadDotEnv();
 async function main() {
   const [{ serve }, { app, personalAssistantProductionStartup }, { startWorker }, { migrate }] = await Promise.all([
     import("@hono/node-server"),
-    import("../server-QRYEMF4H.js"),
-    import("../worker-2MY77WYY.js"),
+    import("../server-XBUOLGZ3.js"),
+    import("../worker-FM3ZRDY4.js"),
     import("../db-Z34LPZNR.js")
   ]);
   const PORT = parseInt(process.env.PORT ?? "3001");
@@ -26,7 +26,7 @@ async function main() {
     await personalAssistantProductionStartup;
     await migrate();
     if (process.env.ANALYTICS_DATABASE_URL) {
-      const { migrateAnalytics } = await import("../analytics-repository-YOY5KMOD.js");
+      const { migrateAnalytics } = await import("../analytics-repository-GA6P5S5J.js");
       await migrateAnalytics();
     }
     startWorker();

package/dist/bin/mcp-scraper-cli.js

@@ -6,14 +6,20 @@ import {
   openWorkflowReport,
   runWorkflow,
   workflowOutputBaseDir
-} from "../chunk-VEQPA65D.js";
+} from "../chunk-ACDNW7TG.js";
 import "../chunk-RJ7JVYKU.js";
 import "../chunk-OWF2JJKN.js";
-import "../chunk-VXLU74YZ.js";
+import {
+  XRAY_INSTALL_CONTRACT,
+  XRAY_INSTALL_PROTOCOL_DIGEST,
+  XRAY_INSTALL_PROTOCOL_VERSION,
+  renderXraySetupPrompt,
+  xrayHostRecipe
+} from "../chunk-BGD7U3AE.js";
 import "../chunk-GGZEC22A.js";
 import {
   PACKAGE_VERSION
-} from "../chunk-RSXDHQBA.js";
+} from "../chunk-62ROBG4P.js";
 
 // src/cli/human-cli.ts
 import { Command } from "commander";
@@ -38,26 +44,6 @@ function envConfig(options) {
   if (options.browserProfileSaveChanges === true) env.BROWSER_AGENT_PROFILE_SAVE_CHANGES = "true";
   return env;
 }
-function tomlInlineTable(value) {
-  const entries = Object.entries(value).map(([key, item]) => `${key} = ${JSON.stringify(item)}`);
-  return `{ ${entries.join(", ")} }`;
-}
-function renderCodexConfig(options = {}) {
-  return [
-    "[mcp_servers.mcp-scraper]",
-    'command = "npx"',
-    `args = ${JSON.stringify(combinedNpxArgs(options))}`,
-    `env = ${tomlInlineTable(envConfig(options))}`
-  ].join("\n");
-}
-function renderClaudeCommand(options = {}) {
-  const env = Object.entries(envConfig(options)).map(([key, value]) => `  --env ${key}=${value}`);
-  return [
-    "claude mcp add mcp-scraper --scope user",
-    ...env,
-    `  -- npx ${combinedNpxArgs(options).join(" ")}`
-  ].join(" \\\n");
-}
 function claudeMcpRemoveArgs() {
   return ["mcp", "remove", "mcp-scraper", "-s", "user"];
 }
@@ -101,28 +87,26 @@ function claudeMcpAddArgs(options = {}) {
 }
 function normalizeAgentHost(host) {
   if (host === "claude-code") return "claude";
-  if (host === "claude" || host === "codex" || host === "claude-desktop") return host;
-  throw new Error('Unknown host "' + host + '". Use: codex, claude, claude-code, or claude-desktop');
+  if (host === "claude" || XRAY_INSTALL_CONTRACT.hosts.some((candidate) => candidate.id === host)) return host;
+  throw new Error('Unknown host "' + host + '". Use: codex, claude, claude-code, claude-desktop, cursor, windsurf, cline, or user-action-only');
 }
-function renderClaudeDesktopConfig(options = {}) {
-  return JSON.stringify({
-    mcpServers: {
-      "mcp-scraper": {
-        command: "npx",
-        args: combinedNpxArgs(options),
-        env: envConfig(options)
-      }
-    }
-  }, null, 2);
+function agentHostCapability(host) {
+  return xrayHostRecipe(host === "claude" ? "claude-code" : host);
 }
-function renderAgentInstall(host, options = {}) {
+function renderAgentInstall(host, _options = {}) {
   const normalizedHost = normalizeAgentHost(host);
+  const recipe = agentHostCapability(normalizedHost);
   const restart = "Restart the MCP client so it starts a fresh npx process.";
-  const applyCommand = `MCP_SCRAPER_API_KEY=${apiKeyValue(options)} npx -y -p mcp-scraper@latest mcp-scraper-cli agent install claude --apply`;
+  const applyCommand = 'MCP_SCRAPER_API_KEY="$MCP_SCRAPER_API_KEY" npx -y -p mcp-scraper@latest mcp-scraper-cli agent install claude --apply';
+  const protocol = `X-Ray install protocol: ${XRAY_INSTALL_PROTOCOL_VERSION} (${XRAY_INSTALL_PROTOCOL_DIGEST})`;
   if (normalizedHost === "codex") {
     return [
       "# Codex MCP config",
-      renderCodexConfig(options),
+      protocol,
+      recipe.exactConfig,
+      "",
+      `Continuation: ${recipe.continuation}`,
+      `Rollback: ${recipe.rollback}`,
       "",
       restart
     ].join("\n");
@@ -130,20 +114,38 @@ function renderAgentInstall(host, options = {}) {
   if (normalizedHost === "claude") {
     return [
       "# Claude Code command",
-      renderClaudeCommand(options),
+      protocol,
+      recipe.exactConfig,
       "",
       "# One-command Claude Code setup",
       applyCommand,
       "",
+      `Continuation: ${recipe.continuation}`,
+      `Rollback: ${recipe.rollback}`,
+      "",
+      restart
+    ].join("\n");
+  }
+  if (normalizedHost === "claude-desktop") {
+    return [
+      "# Claude Desktop config",
+      protocol,
+      recipe.exactConfig,
+      "",
+      "Desktop Extension: https://mcpscraper.dev/downloads/mcp-scraper.mcpb",
+      `Continuation: ${recipe.continuation}`,
+      `Rollback: ${recipe.rollback}`,
       restart
     ].join("\n");
   }
   return [
-    "# Claude Desktop config",
-    renderClaudeDesktopConfig(options),
+    `# ${recipe.label} MCP config`,
+    protocol,
+    recipe.exactConfig,
     "",
-    "Desktop Extension: https://mcpscraper.dev/downloads/mcp-scraper.mcpb",
-    restart
+    `Continuation: ${recipe.continuation}`,
+    `Rollback: ${recipe.rollback}`,
+    ...recipe.restartRequired ? ["", restart] : []
   ].join("\n");
 }
 
@@ -288,6 +290,7 @@ function renderDoctor(output) {
 
 // src/cli/prompts.ts
 var AGENT_PROMPTS = {
+  "xray-setup": renderXraySetupPrompt(),
   "agent-packet": [
     "# MCP Scraper Agent Packet Prompt",
     "",
@@ -561,7 +564,7 @@ function buildHumanCli() {
     ].join("\n"), false);
   });
   const agent = program.command("agent").description("Generate AI-agent install configs and workflow prompts.");
-  agent.command("install <host>").description("Print or apply install/config instructions for codex, claude/claude-code, or claude-desktop.").option("--api-key <key>", "API key to place in generated config").option("--package <spec>", "npm package spec", "mcp-scraper@latest").option("--browser-profile <name>", "Default saved browser profile for browser_open sessions.").option("--save-browser-profile-changes", "Persist cookies and browser storage back to the named browser profile when sessions close").option("--apply", "Apply the config to this client when supported. For Claude Code, this upserts the user-scope mcp-scraper server.").option("--json", "Print machine-readable JSON").action(async (hostInput, opts) => {
+  agent.command("install <host>").description("Print or apply install/config instructions for Codex, Claude, Cursor, Windsurf, Cline, or a handoff-only MCP host.").option("--api-key <key>", "API key to place in generated config").option("--package <spec>", "npm package spec", "mcp-scraper@latest").option("--browser-profile <name>", "Default saved browser profile for browser_open sessions.").option("--save-browser-profile-changes", "Persist cookies and browser storage back to the named browser profile when sessions close").option("--apply", "Apply the config to this client when supported. For Claude Code, this upserts the user-scope mcp-scraper server.").option("--json", "Print machine-readable JSON").action(async (hostInput, opts) => {
     const host = normalizeAgentHost(hostInput);
     const apiKey = opts.apiKey ?? process.env.MCP_SCRAPER_API_KEY;
     if (opts.apply) {
@@ -631,7 +634,12 @@ ${result.list}` : ""
       browserProfileName: opts.browserProfile,
       browserProfileSaveChanges: opts.saveBrowserProfileChanges
     });
-    writeOutput(opts.json ? { host, text } : text, opts.json);
+    writeOutput(opts.json ? {
+      host,
+      protocolVersion: XRAY_INSTALL_PROTOCOL_VERSION,
+      protocolDigest: XRAY_INSTALL_PROTOCOL_DIGEST,
+      text
+    } : text, opts.json);
   });
   agent.command("prompt [name]").description("Print an agent prompt template.").option("--json", "Print machine-readable JSON").action((name, opts) => {
     if (!name) {
@@ -639,7 +647,14 @@ ${result.list}` : ""
       return;
     }
     const text = renderPrompt(name);
-    writeOutput(opts.json ? { name, text } : text, opts.json);
+    writeOutput(opts.json ? {
+      name,
+      ...name === "xray-setup" ? {
+        protocolVersion: XRAY_INSTALL_PROTOCOL_VERSION,
+        protocolDigest: XRAY_INSTALL_PROTOCOL_DIGEST
+      } : {},
+      text
+    } : text, opts.json);
   });
   const workflow = program.command("workflow").description("Run named SEO workflows.");
   workflow.command("list").description("List available workflows.").option("--json", "Print machine-readable JSON").action((opts) => {

package/dist/bin/mcp-scraper-core.js

@@ -1,19 +1,19 @@
 #!/usr/bin/env node
 import {
   runMcpScraperStdio
-} from "../chunk-Z63DQAO7.js";
-import "../chunk-XWXCLKXF.js";
+} from "../chunk-J2CRSYL3.js";
+import "../chunk-W54QRM7I.js";
 import "../chunk-PGJQDMC2.js";
 import "../chunk-DNM65UCK.js";
 import "../chunk-T3MZISOF.js";
 import "../chunk-6HAV7LCE.js";
-import "../chunk-PMONKQGJ.js";
+import "../chunk-4NZ6JFK5.js";
 import "../chunk-OM7HVEJ3.js";
 import "../chunk-OPQIGAFB.js";
-import "../chunk-M2A7YSJV.js";
-import "../chunk-VXLU74YZ.js";
+import "../chunk-UXVT7FWW.js";
+import "../chunk-BGD7U3AE.js";
 import "../chunk-GGZEC22A.js";
-import "../chunk-RSXDHQBA.js";
+import "../chunk-62ROBG4P.js";
 import "../chunk-YXNDOQXN.js";
 
 // src/mcp/thorbit-restricted-tool-surface.ts

package/dist/bin/mcp-scraper-install.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import {
   renderInstallTerminal
-} from "../chunk-M2A7YSJV.js";
+} from "../chunk-UXVT7FWW.js";
 import {
   PACKAGE_VERSION
-} from "../chunk-RSXDHQBA.js";
+} from "../chunk-62ROBG4P.js";
 
 // bin/mcp-scraper-install.ts
 var noColor = process.argv.includes("--no-color") || process.env.NO_COLOR !== void 0 || process.env.FORCE_COLOR === "0" || !process.stdout.isTTY;

package/dist/bin/mcp-stdio-server.js

@@ -1,19 +1,19 @@
 #!/usr/bin/env node
 import {
   runMcpScraperStdio
-} from "../chunk-Z63DQAO7.js";
-import "../chunk-XWXCLKXF.js";
+} from "../chunk-J2CRSYL3.js";
+import "../chunk-W54QRM7I.js";
 import "../chunk-PGJQDMC2.js";
 import "../chunk-DNM65UCK.js";
 import "../chunk-T3MZISOF.js";
 import "../chunk-6HAV7LCE.js";
-import "../chunk-PMONKQGJ.js";
+import "../chunk-4NZ6JFK5.js";
 import "../chunk-OM7HVEJ3.js";
 import "../chunk-OPQIGAFB.js";
-import "../chunk-M2A7YSJV.js";
-import "../chunk-VXLU74YZ.js";
+import "../chunk-UXVT7FWW.js";
+import "../chunk-BGD7U3AE.js";
 import "../chunk-GGZEC22A.js";
-import "../chunk-RSXDHQBA.js";
+import "../chunk-62ROBG4P.js";
 import "../chunk-YXNDOQXN.js";
 
 // bin/mcp-stdio-server.ts

package/dist/{chunk-PMONKQGJ.js → chunk-4NZ6JFK5.js}

@@ -213,8 +213,8 @@ var PUBLIC_PRODUCT_CONTRACT = {
     "freeSignupCredits": 0
   },
   "inventory": {
-    "totalTools": 356,
-    "scraperTools": 255,
+    "totalTools": 363,
+    "scraperTools": 262,
     "memoryTools": 101
   },
   "concurrencyPack": {

package/dist/{chunk-RSXDHQBA.js → chunk-62ROBG4P.js}

@@ -1,5 +1,5 @@
 // src/version.ts
-var PACKAGE_VERSION = "0.81.0";
+var PACKAGE_VERSION = "0.83.1";
 
 export {
   PACKAGE_VERSION

package/dist/{chunk-VEQPA65D.js → chunk-ACDNW7TG.js}

@@ -11,7 +11,7 @@ import {
   extractContactEvidence,
   extractSerpEmailEvidence,
   selectPrimaryEmail
-} from "./chunk-VXLU74YZ.js";
+} from "./chunk-BGD7U3AE.js";
 
 // src/lib/slugify.ts
 function slugify(s) {

package/dist/{chunk-VXLU74YZ.js → chunk-BGD7U3AE.js}

@@ -145,6 +145,204 @@ function extractContactEvidence(html, pageUrl) {
   };
 }
 
+// src/mcp/xray-install-contract.ts
+import { createHash } from "crypto";
+var XRAY_INSTALL_PROTOCOL_VERSION = "2.0.0";
+var XRAY_SETUP_TOOL = "analytics_setup_site";
+var XRAY_TRIGGER_PHRASE = "Install X-Ray";
+var XRAY_CANONICAL_GOAL = "Install X-Ray and tell me what drives customers";
+var CONTINUATION = `Call ${XRAY_SETUP_TOOL} with { "startUrl": "<site URL>", "goal": "${XRAY_CANONICAL_GOAL}" }; on every later call, reuse the returned setupId and revision.`;
+var LOCAL_JSON = JSON.stringify({
+  mcpServers: {
+    "mcp-scraper": {
+      command: "npx",
+      args: ["-y", "--package", "mcp-scraper@latest", "mcp-scraper"],
+      env: { MCP_SCRAPER_API_KEY: "${env:MCP_SCRAPER_API_KEY}" }
+    }
+  }
+}, null, 2);
+var HOSTED_JSON = JSON.stringify({
+  mcpServers: {
+    "mcp-scraper": { url: "https://mcpscraper.dev/mcp" }
+  }
+}, null, 2);
+var XRAY_INSTALL_CONTRACT_PAYLOAD = {
+  schema: "https://mcpscraper.dev/schemas/xray-install-contract-v1.json",
+  protocolVersion: XRAY_INSTALL_PROTOCOL_VERSION,
+  product: "Thorbit X-Ray",
+  triggerPhrases: [XRAY_TRIGGER_PHRASE, "Install X-Ray on this site and tell me what drives customers"],
+  canonicalUrls: {
+    markdown: "https://mcpscraper.dev/agent-install.md",
+    json: "https://mcpscraper.dev/.well-known/xray-install.json",
+    hostedMcp: "https://mcpscraper.dev/mcp"
+  },
+  facade: {
+    tool: XRAY_SETUP_TOOL,
+    initialCall: { startUrl: "<site URL>", goal: XRAY_CANONICAL_GOAL },
+    continuationRule: "Treat setupId plus revision as the durable continuation handle. Reuse both after approval, runtime publication, verification, retry, or return."
+  },
+  topologies: {
+    local_stdio: {
+      label: "Local npm MCP process",
+      authority: "The client starts MCP Scraper locally. After the one-time Pixel insertion, X-Ray setup publishes only owner-confirmed runtime configuration.",
+      secretHandling: "Set MCP_SCRAPER_API_KEY in the local environment or client secret field. Never paste it into chat or commit it."
+    },
+    hosted_remote: {
+      label: "Hosted authenticated MCP",
+      authority: "The hosted MCP inspects approved public pages and publishes owner-confirmed X-Ray runtime configuration. It cannot read or write a caller-local path.",
+      secretHandling: "Use the MCP OAuth/connection flow. Never put a credential in a URL, prompt, or config shown in chat."
+    }
+  },
+  hosts: [
+    {
+      id: "codex",
+      label: "Codex",
+      supportedTopologies: ["local_stdio", "hosted_remote"],
+      mcpConfigMode: "toml",
+      workspaceRead: true,
+      workspaceWrite: true,
+      restartRequired: true,
+      exactConfig: '[mcp_servers.mcp-scraper]\ncommand = "npx"\nargs = ["-y", "--package", "mcp-scraper@latest", "mcp-scraper"]\nenv_vars = ["MCP_SCRAPER_API_KEY"]',
+      continuation: CONTINUATION,
+      rollback: "Remove the mcp_servers.mcp-scraper table, then restart Codex. Pixel removal is a separate owner-controlled site action."
+    },
+    {
+      id: "claude-code",
+      label: "Claude Code",
+      supportedTopologies: ["local_stdio", "hosted_remote"],
+      mcpConfigMode: "command",
+      workspaceRead: true,
+      workspaceWrite: true,
+      restartRequired: true,
+      exactConfig: 'claude mcp add mcp-scraper --scope user --env MCP_SCRAPER_API_KEY="$MCP_SCRAPER_API_KEY" -- npx -y --package mcp-scraper@latest mcp-scraper',
+      continuation: CONTINUATION,
+      rollback: "Run: claude mcp remove mcp-scraper -s user. Pixel removal is a separate owner-controlled site action."
+    },
+    {
+      id: "claude-desktop",
+      label: "Claude Desktop",
+      supportedTopologies: ["local_stdio"],
+      mcpConfigMode: "desktop_extension",
+      workspaceRead: false,
+      workspaceWrite: false,
+      restartRequired: true,
+      exactConfig: "Install https://mcpscraper.dev/downloads/mcp-scraper.mcpb and enter the API key only in Claude Desktop's protected configuration field.",
+      continuation: CONTINUATION,
+      rollback: "Remove the MCP Scraper extension in Claude Desktop. Pixel removal is a separate owner-controlled site action."
+    },
+    {
+      id: "cursor",
+      label: "Cursor",
+      supportedTopologies: ["local_stdio", "hosted_remote"],
+      mcpConfigMode: "json",
+      workspaceRead: true,
+      workspaceWrite: true,
+      restartRequired: true,
+      exactConfig: LOCAL_JSON,
+      continuation: CONTINUATION,
+      rollback: "Remove mcp-scraper from .cursor/mcp.json (or the user MCP settings), then restart Cursor."
+    },
+    {
+      id: "windsurf",
+      label: "Windsurf",
+      supportedTopologies: ["local_stdio"],
+      mcpConfigMode: "json",
+      workspaceRead: true,
+      workspaceWrite: true,
+      restartRequired: true,
+      exactConfig: LOCAL_JSON,
+      continuation: CONTINUATION,
+      rollback: "Remove mcp-scraper from the Windsurf MCP configuration, then restart Windsurf."
+    },
+    {
+      id: "cline",
+      label: "Cline",
+      supportedTopologies: ["local_stdio"],
+      mcpConfigMode: "json",
+      workspaceRead: true,
+      workspaceWrite: true,
+      restartRequired: true,
+      exactConfig: LOCAL_JSON,
+      continuation: CONTINUATION,
+      rollback: "Remove mcp-scraper from Cline MCP Servers, then restart the extension host."
+    },
+    {
+      id: "user-action-only",
+      label: "User-action-only MCP host",
+      supportedTopologies: ["hosted_remote"],
+      mcpConfigMode: "handoff_only",
+      workspaceRead: false,
+      workspaceWrite: false,
+      restartRequired: false,
+      exactConfig: HOSTED_JSON,
+      continuation: CONTINUATION,
+      rollback: "Disconnect MCP Scraper from the host. Pixel removal remains an owner-controlled site action."
+    }
+  ],
+  tagBootstrap: {
+    requirement: "one_global_pixel_once",
+    ongoingConfiguration: "xray_runtime_manifest",
+    sourceAccessRequiredAfterInstall: false,
+    supportedInsertionPaths: ["manual", "tag_manager", "cms_plugin", "coding_host"]
+  },
+  workflow: [
+    "Resolve Thorbit X-Ray entitlement and the target site without consuming MCP Scraper Credits.",
+    "Inspect the whole approved public site; enumerate distinct renderers, routes, and Pixel coverage.",
+    "Infer the business model and customer outcome, then propose one privacy-safe measurement plan.",
+    "If the Pixel is absent, return the canonical one-time tag and exact uncovered surfaces; do not claim ongoing control there.",
+    "Publish an approved measurement revision as a digest-bound runtime manifest; source or repository access is not required.",
+    "Verify route coverage, consent, PageViews, manifest convergence, bounded rule matches, and persisted definition/version evidence.",
+    "Require a separate exact-revision approval before any canary or real-visitor experiment activation.",
+    "Return first customer-journey answers when sufficient, or exact evidence-readiness thresholds when not.",
+    "On \u201Cimprove\u201D, propose one highest-value uncovered outcome, require approval when needed, and reverify."
+  ],
+  safetyRules: [
+    "Never invent or hand-author tracking code; use the canonical product-authored Pixel snippet returned by analytics_setup_site.",
+    "Never ask for or print API keys, OAuth tokens, signed URLs, cookies, or other credentials.",
+    "Never call ad platforms directly or silently activate events, definitions, funnels, or delivery destinations.",
+    "Never treat a CTA click as a customer, sale, or revenue event without verified outcome evidence.",
+    "Never claim full-domain installation while an in-scope route or renderer is missing, excluded without approval, or unverifiable.",
+    "Never treat event-name presence as verification; require persisted definition ID and version evidence."
+  ],
+  terminalStates: ["complete", "tag_required", "input_required", "approval_required", "runtime_convergence_required", "outcome_connection_required", "not_ready", "error"]
+};
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+function xrayInstallDigestPayload() {
+  return canonicalJson(XRAY_INSTALL_CONTRACT_PAYLOAD);
+}
+var XRAY_INSTALL_PROTOCOL_DIGEST = `sha256:${createHash("sha256").update(xrayInstallDigestPayload(), "utf8").digest("hex")}`;
+var XRAY_INSTALL_CONTRACT = {
+  ...XRAY_INSTALL_CONTRACT_PAYLOAD,
+  protocolDigest: XRAY_INSTALL_PROTOCOL_DIGEST
+};
+function xrayHostRecipe(host) {
+  const recipe = XRAY_INSTALL_CONTRACT.hosts.find((candidate) => candidate.id === host);
+  if (!recipe) throw new Error(`Unknown X-Ray host: ${host}`);
+  return recipe;
+}
+function renderXraySetupPrompt() {
+  return [
+    "# Install X-Ray",
+    "",
+    `Protocol: ${XRAY_INSTALL_PROTOCOL_VERSION} (${XRAY_INSTALL_PROTOCOL_DIGEST})`,
+    "",
+    `Use ${XRAY_SETUP_TOOL} as the single conversational setup facade. Ask for the target site URL if it is missing, then call it with the goal \u201C${XRAY_CANONICAL_GOAL}\u201D.`,
+    "",
+    "Continue the same setup with its setupId and revision. Confirm one global Pixel across all public rendering surfaces; present one measurement plan; publish it as a digest-bound runtime manifest after exact-revision approval; verify manifest and rule versions; then return first customer-journey answers or explicit readiness thresholds. GitHub or repository access is not required after the tag is installed.",
+    "",
+    "Do not request pasted credentials, invent tracking code, silently activate measurement, call ad platforms directly, or claim customers/revenue from CTA clicks."
+  ].join("\n");
+}
+function xrayInstallJson(contract = XRAY_INSTALL_CONTRACT) {
+  return JSON.parse(JSON.stringify(contract));
+}
+
 // src/leads/contact-enrichment.ts
 var GENERIC_EMAIL_PREFIXES = /* @__PURE__ */ new Set([
   "admin",
@@ -289,5 +487,13 @@ export {
   selectPrimaryEmail,
   contactAttemptUrls,
   buildSerpEmailQuery,
-  extractSerpEmailEvidence
+  extractSerpEmailEvidence,
+  XRAY_INSTALL_PROTOCOL_VERSION,
+  XRAY_SETUP_TOOL,
+  XRAY_CANONICAL_GOAL,
+  XRAY_INSTALL_PROTOCOL_DIGEST,
+  XRAY_INSTALL_CONTRACT,
+  xrayHostRecipe,
+  renderXraySetupPrompt,
+  xrayInstallJson
 };