fingerprint-platform-mcp 0.0.1

package/dist/cli.js

@@ -0,0 +1,1094 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/tools/analyze.ts
+import { resolve as resolve3 } from "path";
+
+// ../../packages/sdk-snippets/dist/snippet-for-framework.js
+var FRAMEWORKS = [
+  { id: "javascript", label: "JavaScript" },
+  { id: "javascript-spa", label: "JavaScript SPA" },
+  { id: "nextjs", label: "Next.js" },
+  { id: "react", label: "React" },
+  { id: "angular", label: "Angular" },
+  { id: "vue", label: "Vue.js" },
+  { id: "preact", label: "Preact" },
+  { id: "svelte", label: "Svelte" }
+];
+function frameworkLabel(id) {
+  return FRAMEWORKS.find((f) => f.id === id)?.label ?? id;
+}
+function initSnippet(input) {
+  const { framework, source, apiKey, collectorUrl } = input;
+  const config = `  collectorUrl: '${collectorUrl}',
+  projectKey:   '${apiKey}',`;
+  if (source === "cdn") {
+    return `${cdnPlacementComment(framework)}
+<script>
+  // Initialize the agent at application startup.
+  const fp = window.FP.init({
+${config}
+  });
+
+  // Get the visitor and event identifier when you need it.
+  fp.identify({ event: 'pageview' }).then((r) => {
+    if (r.visitorId) console.log(r.eventId, r.visitorId, r.suspectScore);
+    else             console.log('event queued:', r.eventId);
+  });
+</script>`;
+  }
+  switch (framework) {
+    case "nextjs":
+      return `// app/_components/FpClient.tsx  \u2014 client component
+'use client';
+import { useEffect } from 'react';
+
+export function FpClient() {
+  useEffect(() => {
+    let cancelled = false;
+    // Dynamic import keeps the SDK out of the server bundle \u2014 Next.js
+    // SSR has no Window, the SDK throws on the canvas calls there.
+    import('fingerprint-platform-sdk').then(({ init }) => {
+      if (cancelled) return;
+      const fp = init({
+${config.replace(/^/gm, "  ")}
+      });
+      void fp.identify({ event: 'pageview' });
+    });
+    return () => { cancelled = true; };
+  }, []);
+  return null;
+}
+
+// Then mount <FpClient /> in your root layout.`;
+    case "react":
+      return `import { useEffect } from 'react';
+import { init } from 'fingerprint-platform-sdk';
+
+export function useFingerprint() {
+  useEffect(() => {
+    const fp = init({
+${config.replace(/^/gm, "    ")}
+    });
+    fp.identify({ event: 'pageview' }).then((r) => {
+      if (r.visitorId) console.log(r.eventId, r.visitorId, r.suspectScore);
+      else             console.log('event queued:', r.eventId);
+    });
+  }, []);
+}
+
+// Call useFingerprint() once in your root component.`;
+    case "vue":
+      return `// plugins/fingerprint.ts
+import { init } from 'fingerprint-platform-sdk';
+
+const fp = init({
+${config}
+});
+
+export default {
+  install(app) {
+    app.config.globalProperties.$fp = fp;
+  },
+};
+
+// Then in main.ts:
+//   app.use(fpPlugin);
+// And from any component:
+//   this.$fp.identify({ event: 'pageview' });`;
+    case "angular":
+      return `// fingerprint.service.ts
+import { Injectable } from '@angular/core';
+import { init, type FpSdk } from 'fingerprint-platform-sdk';
+
+@Injectable({ providedIn: 'root' })
+export class FingerprintService {
+  readonly fp: FpSdk = init({
+${config.replace(/^/gm, "    ")}
+  });
+}
+
+// Inject in components and call: this.fp.fp.identify({ event: 'pageview' });`;
+    case "svelte":
+      return `// src/lib/fingerprint.ts
+import { init } from 'fingerprint-platform-sdk';
+
+export const fp = init({
+${config}
+});
+
+// In any +page.svelte:
+//   <script lang="ts">
+//     import { onMount } from 'svelte';
+//     import { fp } from '$lib/fingerprint';
+//     onMount(() => { void fp.identify({ event: 'pageview' }); });
+//   </script>`;
+    case "preact":
+      return `import { useEffect } from 'preact/hooks';
+import { init } from 'fingerprint-platform-sdk';
+
+export function useFingerprint() {
+  useEffect(() => {
+    const fp = init({
+${config.replace(/^/gm, "    ")}
+    });
+    void fp.identify({ event: 'pageview' });
+  }, []);
+}
+
+// Call useFingerprint() once in your root component.`;
+    case "javascript-spa":
+      return `// src/fingerprint.js
+// Single-page app pattern: init once, identify() on each route change.
+import { init } from 'fingerprint-platform-sdk';
+
+export const fp = init({
+${config}
+});
+
+// In your router's onNavigate hook:
+//   fp.identify({ event: 'route:' + path });`;
+    case "javascript":
+    default:
+      return `import { init } from 'fingerprint-platform-sdk';
+
+const fp = init({
+${config}
+});
+
+fp.identify({ event: 'pageview' }).then((r) => {
+  if (r.visitorId) console.log(r.eventId, r.visitorId, r.suspectScore);
+  else             console.log('event queued:', r.eventId);
+});`;
+  }
+}
+function cdnPlacementComment(framework) {
+  switch (framework) {
+    case "nextjs":
+      return `<!-- Next.js: prefer next/script with strategy="afterInteractive" in app/layout.tsx
+     rather than a raw <script>. The agent attaches to window.FP on first paint. -->`;
+    case "react":
+      return `<!-- React: drop <script> in public/index.html (CRA / Vite-React).
+     Access window.FP from any component after first paint. -->`;
+    case "vue":
+      return `<!-- Vue.js: place <script> in public/index.html.
+     Read window.FP inside onMounted / mounted hooks. -->`;
+    case "angular":
+      return `<!-- Angular: add <script> to src/index.html.
+     Wrap window.FP in an Injectable service for DI ergonomics. -->`;
+    case "svelte":
+      return `<!-- Svelte / SvelteKit: add <script> to app.html (SvelteKit) or
+     public/index.html. Use onMount() to read window.FP. -->`;
+    case "preact":
+      return `<!-- Preact: drop <script> in your root index.html.
+     Read window.FP from any component after mount. -->`;
+    case "javascript-spa":
+      return `<!-- SPA: include once in your shell HTML. Call fp.identify()
+     from your router's per-route hook to track navigation. -->`;
+    case "javascript":
+    default:
+      return `<!-- Vanilla JS: paste anywhere in <body>. The SDK fires
+     identify() on its own once init() resolves. -->`;
+  }
+}
+
+// src/tools/analyze.ts
+import { z } from "zod";
+
+// src/util/detect-framework.ts
+import { existsSync, readFileSync } from "fs";
+import { resolve } from "path";
+function detectFramework(cwd) {
+  const pkgJson = readPackageJson(cwd);
+  const deps = collectDeps(pkgJson);
+  const sdkInstalled = "fingerprint-platform-sdk" in deps;
+  if ("next" in deps) {
+    return scan("nextjs", cwd, sdkInstalled, "Detected `next` dependency in package.json.");
+  }
+  if ("nuxt" in deps) {
+    return scan("vue", cwd, sdkInstalled, "Detected `nuxt` \u2014 using the Vue.js plugin pattern.");
+  }
+  if ("@angular/core" in deps) {
+    return scan("angular", cwd, sdkInstalled, "Detected `@angular/core` dependency.");
+  }
+  if ("@sveltejs/kit" in deps || "svelte" in deps) {
+    return scan("svelte", cwd, sdkInstalled, "Detected Svelte (or SvelteKit).");
+  }
+  if ("preact" in deps) {
+    return scan("preact", cwd, sdkInstalled, "Detected `preact` dependency.");
+  }
+  if ("vue" in deps) {
+    return scan("vue", cwd, sdkInstalled, "Detected `vue` dependency.");
+  }
+  if ("react" in deps || "react-dom" in deps) {
+    return scan("react", cwd, sdkInstalled, "Detected `react` dependency.");
+  }
+  if (existsSync(resolve(cwd, "next.config.js")) || existsSync(resolve(cwd, "next.config.ts"))) {
+    return scan("nextjs", cwd, sdkInstalled, "Detected `next.config.*` without explicit dep.");
+  }
+  if (existsSync(resolve(cwd, "angular.json"))) {
+    return scan("angular", cwd, sdkInstalled, "Detected `angular.json`.");
+  }
+  if (existsSync(resolve(cwd, "svelte.config.js")) || existsSync(resolve(cwd, "svelte.config.ts"))) {
+    return scan("svelte", cwd, sdkInstalled, "Detected `svelte.config.*`.");
+  }
+  if ("react-router" in deps || "vue-router" in deps || "svelte-routing" in deps) {
+    return scan(
+      "javascript-spa",
+      cwd,
+      sdkInstalled,
+      "Detected a router library without a framework lib."
+    );
+  }
+  return scan("javascript", cwd, sdkInstalled, "No framework signal \u2014 falling back to vanilla JS.");
+}
+function readPackageJson(cwd) {
+  const p = resolve(cwd, "package.json");
+  if (!existsSync(p)) return {};
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function collectDeps(pkg) {
+  return {
+    ...pkg.dependencies,
+    ...pkg.devDependencies,
+    ...pkg.peerDependencies
+  };
+}
+function scan(framework, cwd, hasSDK, rationale) {
+  return {
+    framework,
+    entryFile: locateEntryFile(framework, cwd),
+    hasSDK,
+    rationale
+  };
+}
+function locateEntryFile(framework, cwd) {
+  const candidates = {
+    nextjs: ["app/layout.tsx", "app/layout.jsx", "src/app/layout.tsx", "pages/_app.tsx"],
+    react: ["src/main.tsx", "src/main.jsx", "src/index.tsx", "src/index.jsx", "src/App.tsx"],
+    vue: ["src/main.ts", "src/main.js"],
+    angular: ["src/main.ts", "src/app/app.module.ts"],
+    svelte: ["src/routes/+layout.svelte", "src/main.ts", "src/main.js"],
+    preact: ["src/main.tsx", "src/index.tsx", "src/index.jsx"],
+    "javascript-spa": ["src/main.js", "src/main.ts", "src/index.js"],
+    javascript: ["index.html", "src/index.html", "public/index.html"]
+  };
+  for (const rel of candidates[framework]) {
+    const abs = resolve(cwd, rel);
+    if (existsSync(abs)) return abs;
+  }
+  return void 0;
+}
+
+// src/util/detect-pm.ts
+import { existsSync as existsSync2 } from "fs";
+import { resolve as resolve2 } from "path";
+function detectPackageManager(cwd) {
+  if (existsSync2(resolve2(cwd, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync2(resolve2(cwd, "yarn.lock"))) return "yarn";
+  if (existsSync2(resolve2(cwd, "bun.lockb")) || existsSync2(resolve2(cwd, "bun.lock"))) return "bun";
+  return "npm";
+}
+function renderInstallCommand(pm, pkg) {
+  switch (pm) {
+    case "pnpm":
+      return `pnpm add ${pkg}`;
+    case "yarn":
+      return `yarn add ${pkg}`;
+    case "bun":
+      return `bun add ${pkg}`;
+    case "npm":
+    default:
+      return `npm install ${pkg}`;
+  }
+}
+
+// src/tools/analyze.ts
+var analyzeInputSchema = {
+  cwd: z.string().describe(
+    "Absolute path to the user project root. The AI assistant should pass its own current working directory or the project root it has been browsing."
+  )
+};
+function analyzeProject(input) {
+  const cwd = resolve3(input.cwd);
+  const scan2 = detectFramework(cwd);
+  const pm = detectPackageManager(cwd);
+  const nextSteps = [];
+  if (!scan2.hasSDK) {
+    nextSteps.push(`Call \`install_sdk\` with cwd="${cwd}" to install fingerprint-platform-sdk.`);
+  }
+  if (scan2.entryFile) {
+    nextSteps.push(
+      `Call \`wire_init\` with cwd="${cwd}", framework="${scan2.framework}", entryFile="${scan2.entryFile}" to insert the init snippet.`
+    );
+  } else {
+    nextSteps.push(
+      `Couldn't auto-locate an entry file for ${scan2.framework}. Ask the user where they want \`fp.identify()\` to fire on app boot, then pass that path to \`wire_init\`.`
+    );
+  }
+  nextSteps.push(
+    `Call \`set_collector_url\` once you know the user's collector URL \u2014 typically https://<their-domain>/fpjs proxied through a Cloudflare Worker.`
+  );
+  const details = `**Project scan**
+
+- Framework: \`${scan2.framework}\` (${frameworkLabel(scan2.framework)})
+- Package manager: \`${pm}\` (detected from lockfile)
+- SDK already installed: ${scan2.hasSDK ? "yes" : "no"}
+- Entry file: ${scan2.entryFile ? `\`${scan2.entryFile}\`` : "_not auto-detected_"}
+
+_${scan2.rationale}_`;
+  return {
+    summary: `Detected ${frameworkLabel(scan2.framework)} project (${pm}, SDK ${scan2.hasSDK ? "installed" : "missing"}).`,
+    details,
+    nextSteps,
+    meta: {
+      cwd,
+      framework: scan2.framework,
+      packageManager: pm,
+      entryFile: scan2.entryFile ?? null,
+      hasSDK: scan2.hasSDK
+    }
+  };
+}
+
+// src/tools/configure.ts
+import { resolve as resolve4 } from "path";
+import { z as z2 } from "zod";
+
+// src/util/diff.ts
+import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
+import { relative } from "path";
+import { createPatch } from "diff";
+function makeUnifiedDiff(opts) {
+  const oldContent = existsSync3(opts.filePath) ? readFileSync2(opts.filePath, "utf8") : "";
+  const rel = relative(opts.cwd, opts.filePath).split("\\").join("/");
+  return createPatch(rel, oldContent, opts.newContent, "", "", { context: 3 });
+}
+function makeNewFileDiff(opts) {
+  const rel = relative(opts.cwd, opts.filePath).split("\\").join("/");
+  return createPatch(rel, "", opts.content, "", "", { context: 3 });
+}
+
+// src/tools/configure.ts
+var setCollectorUrlInputSchema = {
+  projectKey: z2.string().describe("Project's public API key."),
+  collectorUrl: z2.string().url().describe(
+    "Same-origin collector URL \u2014 typically https://<their-domain>/fpjs (proxied by a Cloudflare Worker)."
+  )
+};
+function setCollectorUrl(input) {
+  let parsed;
+  try {
+    parsed = new URL(input.collectorUrl);
+  } catch {
+    return {
+      summary: "Invalid collector URL.",
+      details: `\`${input.collectorUrl}\` is not a valid URL. Pass a full https URL like \`https://yoursite.com/fpjs\`.`,
+      meta: { error: "invalid_url" }
+    };
+  }
+  if (parsed.protocol !== "https:" && parsed.hostname !== "localhost") {
+    return {
+      summary: "Collector URL must be HTTPS.",
+      details: `The browser SDK uses X25519 sealing which requires a secure context (HTTPS or localhost). \`${parsed.protocol}//${parsed.hostname}\` would fail at runtime \u2014 please serve via HTTPS in production.`,
+      meta: { error: "http_in_production" }
+    };
+  }
+  const originForAllowedHosts = `${parsed.protocol}//${parsed.hostname}${parsed.port ? `:${parsed.port}` : ""}`;
+  return {
+    summary: `Use \`${input.collectorUrl}\` as the collector URL.`,
+    details: `**1) Add to your environment** (e.g. \`.env.local\`):
+
+\`\`\`bash
+FP_PROJECT_KEY=${input.projectKey}
+FP_COLLECTOR_URL=${input.collectorUrl}
+\`\`\`
+
+**2) Add origin to dashboard allowedHosts.** Open the Fingerprint dashboard \u2192 Security \u2192 Allowed hosts and add:
+
+\`${originForAllowedHosts}\`
+
+Without this entry the collector rejects requests from your site with a 401 \`origin_not_allowed\`. (We can't mutate the dashboard from the MCP server in v1; this step is manual.)`,
+    nextSteps: [
+      `Add the two env vars above to \`.env.local\` (or your secret manager).`,
+      `Open the dashboard's Security page and add \`${originForAllowedHosts}\` to allowedHosts.`,
+      `Call \`generate_cloudflare_worker\` if you want a same-origin proxy on /fpjs/*.`
+    ],
+    artifact: {
+      kind: "env",
+      content: {
+        FP_PROJECT_KEY: input.projectKey,
+        FP_COLLECTOR_URL: input.collectorUrl
+      }
+    },
+    meta: { origin: originForAllowedHosts, collectorUrl: input.collectorUrl }
+  };
+}
+var generateCloudflareWorkerInputSchema = {
+  cwd: z2.string().describe("Absolute path to the user project root \u2014 for the diff header."),
+  collectorHost: z2.string().describe(
+    "Hostname of the Fingerprint collector to proxy to, without scheme. E.g. `collector.yoursite.com` or `89.124.91.162`."
+  ),
+  customDomain: z2.string().describe(
+    "Your site's domain, e.g. `yoursite.com`. The Worker routes `<customDomain>/fpjs/*`."
+  )
+};
+function generateCloudflareWorker(input) {
+  const cwd = resolve4(input.cwd);
+  const workerPath = resolve4(cwd, "cloudflare/worker.ts");
+  const wranglerPath = resolve4(cwd, "cloudflare/wrangler.toml");
+  const host = input.collectorHost.replace(/^https?:\/\//, "").replace(/\/+$/, "");
+  const domain = input.customDomain.replace(/^https?:\/\//, "").replace(/\/+$/, "");
+  const workerScript = cloudflareWorkerTemplate(host);
+  const wranglerToml = wranglerTomlTemplate(domain);
+  const workerDiff = makeNewFileDiff({ cwd, filePath: workerPath, content: workerScript });
+  const wranglerDiff = makeNewFileDiff({ cwd, filePath: wranglerPath, content: wranglerToml });
+  return {
+    summary: `Cloudflare Worker template for \`${domain}/fpjs/*\` \u2192 \`${host}\`.`,
+    details: `Two files to write into the user's repo:
+
+**\`cloudflare/worker.ts\`** \u2014 the Worker script body.
+**\`cloudflare/wrangler.toml\`** \u2014 Wrangler deploy config (route + zone).
+
+Both diffs are pasted below. Apply with your edit tool, then run
+
+\`\`\`bash
+cd cloudflare && wrangler deploy
+\`\`\`
+
+from the project root. After deploy, the Worker is live on the route
+pattern \`${domain}/fpjs/*\`. The SDK then loads same-origin: cookies
+stay first-party, ad-blockers can't pattern-match a cross-origin path.
+
+--- ${workerPath} ---
+
+\`\`\`diff
+${workerDiff}
+\`\`\`
+
+--- ${wranglerPath} ---
+
+\`\`\`diff
+${wranglerDiff}
+\`\`\``,
+    nextSteps: [
+      `Apply both diffs to create the cloudflare/ directory.`,
+      `Install Wrangler: \`npm i -g wrangler\` (or use \`npx wrangler\`).`,
+      `Authenticate: \`wrangler login\`.`,
+      `Deploy: \`cd cloudflare && wrangler deploy\`.`,
+      `Update \`FP_COLLECTOR_URL\` env var to \`https://${domain}/fpjs\`.`,
+      `Add \`https://${domain}\` to dashboard allowedHosts via the Security page.`
+    ],
+    // Single diff payload that concatenates both files — git apply
+    // accepts multi-file unified diffs.
+    artifact: { kind: "diff", content: `${workerDiff}
+${wranglerDiff}` },
+    meta: {
+      workerPath,
+      wranglerPath,
+      route: `${domain}/fpjs/*`,
+      collectorHost: host
+    }
+  };
+}
+var generateDnsFallbackInputSchema = {
+  subdomain: z2.string().describe("Subdomain to point at the collector, e.g. `fp.yoursite.com`. Must be a FQDN."),
+  collectorHost: z2.string().describe("Hostname (or IP) of the Fingerprint collector.")
+};
+function generateDnsFallback(input) {
+  const host = input.collectorHost.replace(/^https?:\/\//, "").replace(/\/+$/, "");
+  const apex = input.subdomain.split(".").slice(1).join(".");
+  return {
+    summary: `DNS CNAME \`${input.subdomain}\` \u2192 \`${host}\`.`,
+    details: `Add the following DNS record in your registrar's zone editor for \`${apex}\`:
+
+\`\`\`text
+Type:  CNAME
+Name:  ${input.subdomain.replace(`.${apex}`, "")}
+Value: ${host}
+TTL:   300 (5 min \u2014 bump after verification)
+\`\`\`
+
+Once propagated, set:
+
+\`\`\`bash
+FP_COLLECTOR_URL=https://${input.subdomain}
+\`\`\`
+
+Then add \`https://${input.subdomain}\` to the dashboard's allowedHosts on the Security page.
+
+_Trade-off vs the Cloudflare Worker route: a dedicated subdomain is **easier for ad-block filter rules to catch** than a same-origin path like \`yoursite.com/fpjs/*\`. Use the Worker if you can; this is the fallback when Cloudflare isn't on the table._`,
+    nextSteps: [
+      `Create the CNAME record in your DNS provider.`,
+      `Wait for propagation (\`dig ${input.subdomain}\` should return the CNAME).`,
+      `Update \`FP_COLLECTOR_URL\` and dashboard allowedHosts.`
+    ],
+    meta: { subdomain: input.subdomain, collectorHost: host, apex }
+  };
+}
+function cloudflareWorkerTemplate(collectorHost) {
+  return `/**
+ * Fingerprint Platform same-origin proxy.
+ *
+ * Generated by fingerprint-platform-mcp.
+ *
+ * Route pattern: <yoursite>/fpjs/*
+ *
+ * Proxies BOTH the SDK bundle (served on /fpjs/agent.js) AND every
+ * collector endpoint (/fpjs/v1/ingest, /fpjs/v1/result/<id>,
+ * /fpjs/v1/pk, /fpjs/v1/comparison). Cookies stay first-party,
+ * ad-blockers cannot pattern-match a same-origin path.
+ *
+ * The integrator's app backend is NEVER in the fingerprint request
+ * path \u2014 that would couple uptime and add latency. The Worker
+ * fans out directly to ${collectorHost}.
+ */
+
+const COLLECTOR_ORIGIN = "https://${collectorHost}";
+
+export default {
+  async fetch(req: Request): Promise<Response> {
+    const url = new URL(req.url);
+
+    // SDK bundle.
+    if (url.pathname === "/fpjs/agent.js") {
+      const upstream = new URL("/v1/agent.js", COLLECTOR_ORIGIN);
+      return forward(req, upstream);
+    }
+
+    // Collector API surface under /fpjs/v1/*.
+    if (url.pathname.startsWith("/fpjs/v1/")) {
+      const upstream = new URL(url.pathname.replace(/^\\/fpjs/, ""), COLLECTOR_ORIGIN);
+      upstream.search = url.search;
+      return forward(req, upstream);
+    }
+
+    // Unknown path under /fpjs/ \u2014 404 cleanly so misconfigured route
+    // patterns don't accidentally proxy the user's whole site.
+    return new Response("not found", { status: 404 });
+  },
+};
+
+async function forward(req: Request, upstream: URL): Promise<Response> {
+  const headers = new Headers(req.headers);
+  // Preserve the original client IP for the collector's IP-class
+  // enrichment \u2014 Cloudflare exposes it via cf-connecting-ip.
+  const clientIp = headers.get("cf-connecting-ip") ?? headers.get("x-forwarded-for");
+  if (clientIp) headers.set("x-forwarded-for", clientIp);
+  // Strip the Host header so the upstream sees its own hostname.
+  headers.delete("host");
+
+  const init: RequestInit = {
+    method: req.method,
+    headers,
+    body: req.method === "GET" || req.method === "HEAD" ? undefined : req.body,
+    redirect: "manual",
+  };
+  return fetch(upstream.toString(), init);
+}
+`;
+}
+function wranglerTomlTemplate(customDomain) {
+  return `name = "fingerprint-proxy"
+main = "worker.ts"
+compatibility_date = "2025-01-01"
+
+# Attach the Worker to your domain. Replace the zone_name if it
+# differs from the domain. Wrangler will prompt for the zone on
+# first deploy if you remove the zone_name line.
+routes = [
+  { pattern = "${customDomain}/fpjs/*", zone_name = "${customDomain}" },
+]
+`;
+}
+
+// src/tools/explain.ts
+import { readFileSync as readFileSync3 } from "fs";
+import { dirname, resolve as resolve5 } from "path";
+import { fileURLToPath } from "url";
+import { z as z3 } from "zod";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+var TOPIC_FILES = {
+  "origin-allowlist": "origin-allowlist.md",
+  "cloudflare-proxy": "cloudflare-proxy.md",
+  "dns-cname": "dns-cname.md",
+  "api-keys": "api-keys.md",
+  "events-vs-identify": "events-vs-identify.md",
+  "sync-vs-async": "sync-vs-async.md"
+};
+var explainInputSchema = {
+  topic: z3.enum([
+    "origin-allowlist",
+    "cloudflare-proxy",
+    "dns-cname",
+    "api-keys",
+    "events-vs-identify",
+    "sync-vs-async"
+  ]).describe(
+    "Topic id. The AI assistant picks one based on the user question. Each topic returns a focused markdown brief \u2014 pasting raw docs into the conversation tends to drown out the actionable bits."
+  )
+};
+function explainTopic(input) {
+  const filename = TOPIC_FILES[input.topic];
+  if (!filename) {
+    return {
+      summary: `Unknown topic "${input.topic}".`,
+      details: `Known topics: ${Object.keys(TOPIC_FILES).join(", ")}.`,
+      meta: { error: "unknown_topic" }
+    };
+  }
+  const candidates = [
+    resolve5(__dirname, "..", "docs", filename),
+    resolve5(__dirname, "docs", filename),
+    resolve5(__dirname, "..", "..", "src", "docs", filename)
+  ];
+  for (const path of candidates) {
+    try {
+      const content = readFileSync3(path, "utf8");
+      return {
+        summary: `Returned docs/${filename} (${content.length} chars).`,
+        details: content,
+        artifact: { kind: "markdown", content },
+        meta: { topic: input.topic, path }
+      };
+    } catch {
+    }
+  }
+  return {
+    summary: `docs/${filename} not found at runtime.`,
+    details: `Looked at: ${candidates.join(", ")}. This is a build issue \u2014 the tsup config should be copying src/docs/ into dist/docs/. Re-run \`pnpm build\` and try again.`,
+    meta: { error: "doc_missing", topic: input.topic }
+  };
+}
+
+// src/tools/install.ts
+import { resolve as resolve6 } from "path";
+import { z as z4 } from "zod";
+var installInputSchema = {
+  cwd: z4.string().describe("Absolute path to the user project root."),
+  packageManager: z4.enum(["pnpm", "yarn", "bun", "npm"]).optional().describe(
+    "Override the auto-detected package manager. Most callers should let analyze_project decide."
+  ),
+  source: z4.enum(["npm", "cdn"]).default("npm").describe(
+    "Install source. `npm` is the default (recommended). `cdn` returns the <script> tag snippet instead \u2014 useful when the user explicitly doesn't want to add an npm dep."
+  )
+};
+function installSdk(input) {
+  const cwd = resolve6(input.cwd);
+  const source = input.source ?? "npm";
+  if (source === "cdn") {
+    return {
+      summary: "CDN install \u2014 no package manager command needed.",
+      details: 'Add the following `<script>` tag to your HTML shell (e.g. `public/index.html`, `app.html`, or the framework-specific entry document). Once it loads, `window.FP.init({...})` is available.\n\n```html\n<script src="/fpjs/agent.js" async></script>\n```\n\n_The recommended `/fpjs/agent.js` path is served by your Cloudflare Worker proxy (see `generate_cloudflare_worker`). The unpkg URL works for local dev but is on every ad-block list \u2014 do not ship it to production._',
+      nextSteps: [`Call \`wire_init\` to insert the init() call into the right entry file.`],
+      artifact: {
+        kind: "markdown",
+        content: '<script src="/fpjs/agent.js" async></script>'
+      },
+      meta: { source: "cdn", cwd }
+    };
+  }
+  const pm = input.packageManager ?? detectPackageManager(cwd);
+  const cmd = renderInstallCommand(pm, "fingerprint-platform-sdk");
+  return {
+    summary: `Install via ${pm}: \`${cmd}\``,
+    details: `Run the following command in the project root (\`${cwd}\`):
+
+\`\`\`bash
+` + cmd + `
+\`\`\`
+
+_Detected package manager: ${pm}. If this is wrong, pass \`packageManager\` explicitly._`,
+    nextSteps: [
+      `Execute the command above via your bash tool.`,
+      `Then call \`wire_init\` to insert the SDK init() call into the right entry file.`
+    ],
+    artifact: { kind: "command", content: cmd, cwd },
+    meta: { source: "npm", packageManager: pm, cwd, command: cmd }
+  };
+}
+
+// src/tools/verify.ts
+import { existsSync as existsSync4, readdirSync, readFileSync as readFileSync4, statSync } from "fs";
+import { resolve as resolve7 } from "path";
+import { z as z5 } from "zod";
+var verifyInstallInputSchema = {
+  cwd: z5.string().describe("Absolute path to the user project root.")
+};
+function verifyInstall(input) {
+  const cwd = resolve7(input.cwd);
+  const scan2 = detectFramework(cwd);
+  const checks = [];
+  checks.push({
+    name: "fingerprint-platform-sdk in dependencies",
+    status: scan2.hasSDK ? "ok" : "fail",
+    hint: scan2.hasSDK ? `Detected via package.json.` : `Run \`install_sdk\` and apply its install command.`
+  });
+  const initCallFound = grepForInitCall(cwd);
+  checks.push({
+    name: "SDK `init(...)` call present in source tree",
+    status: initCallFound ? "ok" : "warn",
+    hint: initCallFound ? `Found a reference to \`init({...})\` or \`window.FP.init\` in the source.` : `Couldn't find an \`init({...})\` call. Either re-run \`wire_init\` to place the snippet, or confirm the user mounted the generated module.`
+  });
+  const envCheck = envVarStatus(cwd);
+  checks.push({
+    name: "FP_PROJECT_KEY + FP_COLLECTOR_URL configured",
+    status: envCheck.both ? "ok" : envCheck.either ? "warn" : "fail",
+    hint: envCheck.hint
+  });
+  const failCount = checks.filter((c) => c.status === "fail").length;
+  const warnCount = checks.filter((c) => c.status === "warn").length;
+  const summary = failCount > 0 ? `${failCount} check failed, ${warnCount} warning. See checklist.` : warnCount > 0 ? `Mostly good \u2014 ${warnCount} thing(s) to confirm manually.` : "All checks green. Send a test event and look for it on the dashboard.";
+  return {
+    summary,
+    details: `**Verification checklist**
+
+` + checks.map((c) => `- ${badge(c.status)} **${c.name}** \u2014 ${c.hint}`).join("\n"),
+    nextSteps: failCount === 0 && warnCount === 0 ? [
+      `Trigger an event by reloading the page where the SDK is mounted.`,
+      `Open the dashboard \u2192 Identification view; the event should appear within ~2s.`
+    ] : [`Resolve the failed / warned checks above and call \`verify_install\` again.`],
+    meta: { checks, framework: scan2.framework }
+  };
+}
+function badge(status) {
+  return status === "ok" ? "\u2713" : status === "warn" ? "\u26A0" : "\u2717";
+}
+function grepForInitCall(cwd) {
+  let count = 0;
+  const stack = [cwd];
+  const seen = /* @__PURE__ */ new Set();
+  while (stack.length > 0 && count < 5e3) {
+    const dir = stack.pop();
+    if (!dir || seen.has(dir)) continue;
+    seen.add(dir);
+    if (/[\\/](node_modules|dist|\.next|build|coverage|\.turbo)$/.test(dir)) continue;
+    let entries;
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      continue;
+    }
+    for (const name of entries) {
+      count++;
+      if (count >= 5e3) break;
+      const abs = resolve7(dir, name);
+      let stat;
+      try {
+        stat = statSync(abs);
+      } catch {
+        continue;
+      }
+      if (stat.isDirectory()) {
+        stack.push(abs);
+        continue;
+      }
+      if (!/\.(t|j)sx?$|\.svelte$|\.vue$|\.html$/.test(name)) continue;
+      try {
+        const raw = readFileSync4(abs, "utf8");
+        if (/\bFP\.init\(|\binit\(\s*\{\s*(collectorUrl|projectKey)/m.test(raw)) {
+          return true;
+        }
+      } catch {
+      }
+    }
+  }
+  return false;
+}
+function envVarStatus(cwd) {
+  const fromProcess = {
+    key: Boolean(process.env["FP_PROJECT_KEY"]),
+    url: Boolean(process.env["FP_COLLECTOR_URL"])
+  };
+  const dotenvFiles = [".env", ".env.local", ".env.development", ".env.production"];
+  const seenInDotenv = { key: false, url: false };
+  for (const name of dotenvFiles) {
+    const p = resolve7(cwd, name);
+    if (!existsSync4(p)) continue;
+    try {
+      const raw = readFileSync4(p, "utf8");
+      if (/^\s*FP_PROJECT_KEY\s*=/m.test(raw)) seenInDotenv.key = true;
+      if (/^\s*FP_COLLECTOR_URL\s*=/m.test(raw)) seenInDotenv.url = true;
+    } catch {
+    }
+  }
+  const keyOk = fromProcess.key || seenInDotenv.key;
+  const urlOk = fromProcess.url || seenInDotenv.url;
+  const both = keyOk && urlOk;
+  const either = keyOk || urlOk;
+  const missing = [];
+  if (!keyOk) missing.push("FP_PROJECT_KEY");
+  if (!urlOk) missing.push("FP_COLLECTOR_URL");
+  return {
+    both,
+    either,
+    hint: both ? `Found both vars (in process.env or a .env file).` : `Missing: ${missing.join(", ")}. Add to \`.env.local\` via \`set_collector_url\`.`
+  };
+}
+
+// src/tools/wire-init.ts
+import { existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
+import { dirname as dirname2, resolve as resolve8 } from "path";
+import { z as z6 } from "zod";
+var wireInitInputSchema = {
+  cwd: z6.string().describe("Absolute path to the user project root."),
+  framework: z6.enum(["javascript", "javascript-spa", "nextjs", "react", "vue", "angular", "svelte", "preact"]).describe("Framework id from `analyze_project`."),
+  entryFile: z6.string().describe(
+    "Absolute path to the file that should host the SDK init call (from `analyze_project.meta.entryFile`)."
+  ),
+  apiKey: z6.string().describe(
+    "Project's public API key. Substitute the value from the dashboard's API keys page or env.FP_PROJECT_KEY."
+  ),
+  collectorUrl: z6.string().url().describe(
+    "Same-origin collector URL \u2014 typically https://<their-domain>/fpjs (proxied by a Cloudflare Worker)."
+  ),
+  source: z6.enum(["npm", "cdn"]).default("npm").describe("Match whatever `install_sdk` ran with. Defaults to `npm`.")
+};
+function wireInit(input) {
+  const cwd = resolve8(input.cwd);
+  const entryFile = resolve8(input.entryFile);
+  const source = input.source ?? "npm";
+  const snippet = initSnippet({
+    framework: input.framework,
+    source,
+    apiKey: input.apiKey,
+    collectorUrl: input.collectorUrl
+  });
+  if (source === "cdn") {
+    if (!existsSync5(entryFile)) {
+      return missingEntryFile(entryFile, input.framework);
+    }
+    const current = readFileSync5(entryFile, "utf8");
+    const next = appendBeforeBodyClose(current, snippet);
+    const diff2 = makeUnifiedDiff({ cwd, filePath: entryFile, newContent: next });
+    return successDiff(diff2, entryFile, input.framework, source, [
+      `Apply the diff to \`${entryFile}\` via your edit tool.`,
+      `Reload the page and confirm \`window.FP.init\` is defined in DevTools.`
+    ]);
+  }
+  const targetFile = perFrameworkTargetFile(input.framework, cwd);
+  const diff = makeNewFileDiff({ cwd, filePath: targetFile, content: snippet });
+  const mountHint = perFrameworkMountHint(input.framework);
+  return successDiff(diff, targetFile, input.framework, source, [
+    `Apply the diff to create \`${targetFile}\` via your edit tool.`,
+    mountHint,
+    `Run the app and confirm the SDK boots \u2014 open DevTools, you should see the eventId / visitorId logged.`
+  ]);
+}
+function successDiff(diff, filePath, framework, source, nextSteps) {
+  return {
+    summary: `Wrote ${source} init for ${frameworkLabel(framework)} into \`${filePath}\`.`,
+    details: `Apply the unified diff below with \`git apply\` (or your AI assistant's edit tool). The patch is against \`${filePath}\` and is generated from the same \`initSnippet()\` helper the dashboard's Get Started page uses \u2014 so what you see here matches the install snippet shown there byte-for-byte.
+
+\`\`\`diff
+` + diff + "\n```",
+    nextSteps,
+    artifact: { kind: "diff", content: diff },
+    meta: { framework, source, filePath }
+  };
+}
+function missingEntryFile(entryFile, framework) {
+  return {
+    summary: `Entry file \`${entryFile}\` not found.`,
+    details: `The path we were given doesn't exist. Re-run \`analyze_project\` to refresh the detection, or ask the user where their ${frameworkLabel(framework)} entry document lives (typically \`public/index.html\`, \`app.html\`, or the framework's root template).`,
+    nextSteps: [`Call \`analyze_project\` again to re-detect, or accept the user's manual path.`],
+    meta: { error: "entry_not_found", entryFile }
+  };
+}
+function perFrameworkTargetFile(framework, cwd) {
+  const map = {
+    nextjs: "app/_components/FpClient.tsx",
+    react: "src/hooks/useFingerprint.ts",
+    vue: "src/plugins/fingerprint.ts",
+    angular: "src/app/fingerprint.service.ts",
+    svelte: "src/lib/fingerprint.ts",
+    preact: "src/hooks/useFingerprint.ts",
+    "javascript-spa": "src/fingerprint.ts",
+    javascript: "src/fingerprint.ts"
+  };
+  return resolve8(cwd, map[framework]);
+}
+function perFrameworkMountHint(framework) {
+  switch (framework) {
+    case "nextjs":
+      return "Mount `<FpClient />` once in `app/layout.tsx` so it boots on every route.";
+    case "react":
+    case "preact":
+      return "Call `useFingerprint()` once in your root `App` component.";
+    case "vue":
+      return 'In `main.ts`: `import fpPlugin from "./plugins/fingerprint"; app.use(fpPlugin);`. Then from any component call `this.$fp.identify({ event: "pageview" })`.';
+    case "angular":
+      return 'Inject `FingerprintService` in any component and call `this.fp.fp.identify({ event: "pageview" })`.';
+    case "svelte":
+      return 'In a `+page.svelte`: `import { fp } from "$lib/fingerprint"; onMount(() => fp.identify({ event: "pageview" }));`.';
+    case "javascript-spa":
+      return "Hook your router's `onNavigate` to call `fp.identify({ event: 'route:' + path })`.";
+    case "javascript":
+    default:
+      return "Import the module from your entry point so the `fp.identify()` call fires on load.";
+  }
+}
+function appendBeforeBodyClose(html, snippet) {
+  const lower = html.toLowerCase();
+  const idx = lower.lastIndexOf("</body>");
+  if (idx === -1) {
+    const trailingNewline = html.endsWith("\n") ? "" : "\n";
+    return `${html}${trailingNewline}${snippet}
+`;
+  }
+  const before = html.slice(0, idx);
+  const after = html.slice(idx);
+  return `${before}${snippet}
+${after}`;
+}
+
+// src/server.ts
+function buildServer() {
+  const server = new McpServer(
+    {
+      name: "fingerprint-platform-mcp",
+      version: "0.0.1"
+    },
+    {
+      capabilities: {
+        // We advertise tools only — no resources/prompts in v1. The
+        // SDK auto-fills the capability object from the registrations
+        // below, so we just declare an empty placeholder to be
+        // explicit about the shape.
+        tools: {}
+      },
+      instructions: "Use these tools to install and configure the Fingerprint Platform SDK (`fingerprint-platform-sdk`) in a user project. Standard flow: `analyze_project` \u2192 `install_sdk` \u2192 `wire_init` \u2192 `set_collector_url` \u2192 `generate_cloudflare_worker` (recommended) or `generate_dns_fallback` \u2192 `verify_install`. Every tool is read-only on the filesystem and returns a diff/command/env spec for the assistant to apply with its own tools. Use `explain_topic` to fetch a focused brief on origin-allowlist, cloudflare-proxy, dns-cname, api-keys, events-vs-identify, sync-vs-async."
+    }
+  );
+  function render(envelope) {
+    const parts = [envelope.summary];
+    if (envelope.details) parts.push(envelope.details);
+    if (envelope.nextSteps && envelope.nextSteps.length > 0) {
+      parts.push(
+        "## Next steps\n\n" + envelope.nextSteps.map((s, i) => `${i + 1}. ${s}`).join("\n")
+      );
+    }
+    if (envelope.artifact) {
+      switch (envelope.artifact.kind) {
+        case "diff":
+          parts.push("## Diff\n\n```diff\n" + envelope.artifact.content + "\n```");
+          break;
+        case "command":
+          parts.push(
+            "## Command\n\n```bash\n" + envelope.artifact.content + "\n```" + (envelope.artifact.cwd ? `
+_(run in \`${envelope.artifact.cwd}\`)_` : "")
+          );
+          break;
+        case "env":
+          parts.push(
+            "## Env vars\n\n```bash\n" + Object.entries(envelope.artifact.content).map(([k, v]) => `${k}=${v}`).join("\n") + "\n```"
+          );
+          break;
+        case "markdown":
+          break;
+      }
+    }
+    return { content: [{ type: "text", text: parts.join("\n\n") }] };
+  }
+  server.registerTool(
+    "analyze_project",
+    {
+      description: "Scan the user project at `cwd` \u2014 read package.json + lockfile + framework config \u2014 to determine framework / package manager / entry file / whether the SDK is already installed. Read-only. Always call this first.",
+      inputSchema: analyzeInputSchema
+    },
+    async (args) => render(analyzeProject(args))
+  );
+  server.registerTool(
+    "install_sdk",
+    {
+      description: "Emit the install command for `fingerprint-platform-sdk` using the detected (or passed) package manager. Does NOT execute \u2014 the AI runs it via its own bash tool.",
+      inputSchema: installInputSchema
+    },
+    async (args) => render(
+      installSdk({
+        cwd: args.cwd,
+        source: args.source ?? "npm",
+        ...args.packageManager ? { packageManager: args.packageManager } : {}
+      })
+    )
+  );
+  server.registerTool(
+    "wire_init",
+    {
+      description: "Generate a unified diff that places the framework-idiomatic SDK init() call into the right entry file. Reuses `initSnippet()` from `@fingerprint79/sdk-snippets` so the code matches what the dashboard shows.",
+      inputSchema: wireInitInputSchema
+    },
+    async (args) => render(
+      wireInit({
+        cwd: args.cwd,
+        framework: args.framework,
+        entryFile: args.entryFile,
+        apiKey: args.apiKey,
+        collectorUrl: args.collectorUrl,
+        source: args.source ?? "npm"
+      })
+    )
+  );
+  server.registerTool(
+    "set_collector_url",
+    {
+      description: "Validate a collector URL and return (a) env-var spec to add to `.env.local` and (b) the dashboard `allowedHosts` change the operator must make manually. The MCP server cannot mutate the dashboard in v1.",
+      inputSchema: setCollectorUrlInputSchema
+    },
+    async (args) => render(setCollectorUrl(args))
+  );
+  server.registerTool(
+    "generate_cloudflare_worker",
+    {
+      description: "Emit a `cloudflare/worker.ts` + `cloudflare/wrangler.toml` as diffs to drop into the user repo. Worker proxies SDK bundle + collector API under `<customDomain>/fpjs/*` for same-origin, ad-block-resistant delivery.",
+      inputSchema: generateCloudflareWorkerInputSchema
+    },
+    async (args) => render(generateCloudflareWorker(args))
+  );
+  server.registerTool(
+    "generate_dns_fallback",
+    {
+      description: "When Cloudflare is not an option, emit DNS CNAME instructions pointing a subdomain at the collector. Keeps cookies first-party but is more ad-block-prone than the Worker route.",
+      inputSchema: generateDnsFallbackInputSchema
+    },
+    async (args) => render(generateDnsFallback(args))
+  );
+  server.registerTool(
+    "verify_install",
+    {
+      description: "Run a post-install sanity checklist on the user project \u2014 SDK in deps, init() call grep-able in source, env vars set. Returns a `{ check, status, hint }[]` triple for each item.",
+      inputSchema: verifyInstallInputSchema
+    },
+    async (args) => render(verifyInstall(args))
+  );
+  server.registerTool(
+    "explain_topic",
+    {
+      description: 'Return a focused markdown brief on one of: origin-allowlist, cloudflare-proxy, dns-cname, api-keys, events-vs-identify, sync-vs-async. Use when the user asks a "why" / "how" question about an advanced setup.',
+      inputSchema: explainInputSchema
+    },
+    async (args) => render(explainTopic(args))
+  );
+  return server;
+}
+
+// src/cli.ts
+async function main() {
+  const server = buildServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((err) => {
+  console.error("[fingerprint-platform-mcp] fatal:", err);
+  process.exit(1);
+});
+//# sourceMappingURL=cli.js.map