@easyfunnel/mcp 0.1.10 → 0.2.0

package/dist/index.js

@@ -241,6 +241,58 @@ var frameworkConfigs = {
     layoutPaths: ["src/routes/+layout.svelte"]
   }
 };
+var helperPaths = {
+  nextjs: {
+    helperFile: "lib/easyfunnel.ts",
+    bridgeFile: "components/ef-bridge.tsx",
+    helperImport: "@/lib/easyfunnel",
+    bridgeImport: "@/components/ef-bridge"
+  },
+  vite: {
+    helperFile: "src/lib/easyfunnel.ts",
+    bridgeFile: "src/components/ef-bridge.tsx",
+    helperImport: "@/lib/easyfunnel",
+    bridgeImport: "@/components/ef-bridge"
+  },
+  cra: {
+    helperFile: "src/lib/easyfunnel.ts",
+    bridgeFile: "src/components/ef-bridge.tsx",
+    helperImport: "@/lib/easyfunnel",
+    bridgeImport: "@/components/ef-bridge"
+  }
+};
+var HELPER_FILE_CONTENT = `import type { Tracker } from '@easyfunnel/sdk'
+
+let tracker: Tracker | null = null
+
+export function setTracker(t: Tracker | null) { tracker = t }
+export function getTracker(): Tracker | null { return tracker }
+
+export function track(event: string, properties?: Record<string, any>) {
+  tracker?.track(event, properties)
+}
+
+export function identify(userId: string) {
+  tracker?.identify(userId)
+}
+`;
+function getBridgeFileContent(helperImport) {
+  return `'use client'
+
+import { useEffect } from 'react'
+import { useEasyFunnel } from '@easyfunnel/react'
+import { setTracker } from '${helperImport}'
+
+export function EfBridge() {
+  const tracker = useEasyFunnel()
+  useEffect(() => {
+    setTracker(tracker)
+    return () => setTracker(null)
+  }, [tracker])
+  return null
+}
+`;
+}
 function detectPackageManager(projectRoot) {
   if ((0, import_fs.existsSync)((0, import_path.join)(projectRoot, "bun.lockb"))) return "bun";
   if ((0, import_fs.existsSync)((0, import_path.join)(projectRoot, "pnpm-lock.yaml"))) return "pnpm";
@@ -398,6 +450,62 @@ Next: After adding the script, I'll verify everything works with a test event.`
   if (!providerWrapped) {
     steps.push(`[skip] Could not find layout file to add provider. Searched: ${config.layoutPaths.join(", ")}`);
   }
+  const paths = framework !== "html" && framework !== "sveltekit" ? helperPaths[framework] : null;
+  if (paths) {
+    const helperFullPath = (0, import_path.join)(project_root, paths.helperFile);
+    const helperDir = (0, import_path.dirname)(helperFullPath);
+    if ((0, import_fs.existsSync)(helperFullPath)) {
+      const existing = (0, import_fs.readFileSync)(helperFullPath, "utf-8");
+      if (existing.includes("setTracker")) {
+        steps.push(`[skip] ${paths.helperFile} already exists`);
+      } else {
+        steps.push(`[skip] ${paths.helperFile} exists but may need manual update \u2014 expected setTracker export`);
+      }
+    } else {
+      if (!(0, import_fs.existsSync)(helperDir)) {
+        (0, import_fs.mkdirSync)(helperDir, { recursive: true });
+      }
+      (0, import_fs.writeFileSync)(helperFullPath, HELPER_FILE_CONTENT);
+      steps.push(`[done] Generated ${paths.helperFile} (tracking helper for non-React files)`);
+      filesModified.push({ file: paths.helperFile, action: "Generated tracking helper" });
+    }
+    const bridgeFullPath = (0, import_path.join)(project_root, paths.bridgeFile);
+    const bridgeDir = (0, import_path.dirname)(bridgeFullPath);
+    if ((0, import_fs.existsSync)(bridgeFullPath)) {
+      steps.push(`[skip] ${paths.bridgeFile} already exists`);
+    } else {
+      if (!(0, import_fs.existsSync)(bridgeDir)) {
+        (0, import_fs.mkdirSync)(bridgeDir, { recursive: true });
+      }
+      (0, import_fs.writeFileSync)(bridgeFullPath, getBridgeFileContent(paths.helperImport));
+      steps.push(`[done] Generated ${paths.bridgeFile} (syncs React context to helper)`);
+      filesModified.push({ file: paths.bridgeFile, action: "Generated bridge component" });
+    }
+    if (providerWrapped) {
+      for (const relPath of config.layoutPaths) {
+        const fullPath = (0, import_path.join)(project_root, relPath);
+        if (!(0, import_fs.existsSync)(fullPath)) continue;
+        let content = (0, import_fs.readFileSync)(fullPath, "utf-8");
+        if (!content.includes("EasyFunnelProvider")) continue;
+        if (content.includes("EfBridge")) {
+          steps.push(`[skip] EfBridge already present in ${relPath}`);
+          break;
+        }
+        const bridgeImportLine = `import { EfBridge } from '${paths.bridgeImport}'
+`;
+        content = bridgeImportLine + content;
+        content = content.replace(
+          /(<EasyFunnelProvider[^>]*>)([\s\S]*?)(\{children\})/,
+          `$1$2<EfBridge />
+          $3`
+        );
+        (0, import_fs.writeFileSync)(fullPath, content);
+        steps.push(`[done] Added <EfBridge /> to ${relPath}`);
+        filesModified.push({ file: relPath, action: "Added bridge component" });
+        break;
+      }
+    }
+  }
   let output = `SDK SETUP COMPLETE
 
 `;
@@ -428,6 +536,23 @@ The API key is hardcoded in your layout file \u2014 no env var configuration nee
 `;
   output += `If you prefer, you can override it via ${config.envVarName} in ${config.envFile}.
 `;
+  if (paths) {
+    output += `
+Tracking helper: ${paths.helperFile}
+`;
+    output += `  - React components: use useTrack() from @easyfunnel/react
+`;
+    output += `  - Non-React files:  import { track } from '${paths.helperImport}'
+`;
+  } else if (framework === "html") {
+    output += `
+Tracking: use window.EasyFunnel.track() \u2014 the SDK global is available after page load.
+`;
+  } else if (framework === "sveltekit") {
+    output += `
+Note: Tracking outside Svelte components requires a manual singleton pattern.
+`;
+  }
   output += `
 Next: I'll verify everything works with a test event.`;
   return {
@@ -565,9 +690,22 @@ async function scanForActions(args) {
 
 // src/tools/instrument-code.ts
 var import_fs3 = require("fs");
+
+// src/lib/react-detect.ts
+function isReactComponent(filePath, content) {
+  const ext = filePath.split(".").pop()?.toLowerCase();
+  if (ext !== "tsx" && ext !== "jsx") return false;
+  return content.includes("'use client'") || content.includes('"use client"') || /import\s+React/m.test(content) || /from\s+['"]react['"]/m.test(content) || /return\s*\(/m.test(content);
+}
+function isReactAware(filePath, content) {
+  if (isReactComponent(filePath, content)) return true;
+  return /from\s+['"]react['"]/m.test(content) || /from\s+['"]@easyfunnel\/react['"]/m.test(content);
+}
+
+// src/tools/instrument-code.ts
 var instrumentCodeDefinition = {
   name: "instrument_code",
-  description: "Add easyfunnel tracking to a specific interactive element in the codebase. Returns a diff preview \u2014 does NOT auto-save.",
+  description: "Add easyfunnel tracking to a specific interactive element. attribute method returns a diff preview. track_call method returns context-aware suggestions (useTrack for React components, helper import for other files). Does NOT auto-save.",
   inputSchema: {
     type: "object",
     properties: {
@@ -586,7 +724,7 @@ var instrumentCodeDefinition = {
       method: {
         type: "string",
         enum: ["attribute", "track_call"],
-        description: "attribute: add data-ef-track attribute. track_call: add ef.track() call inside handler."
+        description: "attribute: add data-ef-track attribute. track_call: add track() call \u2014 automatically suggests useTrack() for React components or import from lib/easyfunnel for other files."
       }
     },
     required: ["file", "line", "event_name", "method"]
@@ -607,8 +745,6 @@ async function instrumentCode(args) {
       ]
     };
   }
-  let newLine;
-  let changeDescription;
   if (method === "attribute") {
     if (targetLine.includes("data-ef-track")) {
       return {
@@ -620,54 +756,98 @@ async function instrumentCode(args) {
         ]
       };
     }
-    newLine = targetLine.replace(
+    let newLine = targetLine.replace(
       /(<\w+)(\s)/,
       `$1 data-ef-track="${event_name}"$2`
     );
     if (newLine === targetLine) {
       newLine = targetLine.replace(/>/, ` data-ef-track="${event_name}">`);
     }
-    changeDescription = `Added data-ef-track="${event_name}" attribute`;
-  } else {
-    newLine = targetLine;
-    if (targetLine.includes("onClick") || targetLine.includes("onSubmit")) {
-      changeDescription = `Add track('${event_name}') call. Suggested modification:
+    const changeDescription2 = `Added data-ef-track="${event_name}" attribute`;
+    const diff = `--- ${file}
++++ ${file}
+@@ -${line},1 +${line},1 @@
+-${targetLine}
++${newLine}`;
+    return {
+      content: [
+        {
+          type: "text",
+          text: `${changeDescription2}
+
+Diff preview:
+\`\`\`diff
+${diff}
+\`\`\`
+
+Apply this change to ${file} at line ${line}.`
+        }
+      ]
+    };
+  }
+  const isReact = isReactComponent(file, content);
+  const hasHandler = targetLine.includes("onClick") || targetLine.includes("onSubmit");
+  const handlerHint = hasHandler ? `
+
+The target line contains an event handler \u2014 add the track call at the start of that handler function.` : "";
+  if (!isReact && isReactAware(file, content)) {
+    const changeDescription2 = `Add track('${event_name}') call (React-aware file detected \u2014 could be a hook or utility).
+
+Option A (if this is a React hook/component):
+  1. import { useTrack } from '@easyfunnel/react'
+  2. const track = useTrack()
+  3. track('${event_name}')
+
+Option B (if this is a utility/helper):
+  1. import { track } from '@/lib/easyfunnel'
+  2. track('${event_name}')` + handlerHint;
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Instrumentation suggestion for ${file}:${line}
+
+${changeDescription2}
+
+Please apply the appropriate option using your code editing capabilities.`
+        }
+      ]
+    };
+  }
+  if (isReact) {
+    const changeDescription2 = `Add track('${event_name}') call (React component detected).
 
 1. Add import: import { useTrack } from '@easyfunnel/react'
-2. Add hook: const track = useTrack()
-3. Add track call: track('${event_name}') at the start of the handler function`;
-      return {
-        content: [
-          {
-            type: "text",
-            text: `Instrumentation suggestion for ${file}:${line}
+2. Add hook:   const track = useTrack()
+3. Add call:   track('${event_name}') at the start of the handler` + handlerHint;
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Instrumentation suggestion for ${file}:${line}
 
-${changeDescription}
+${changeDescription2}
 
 This requires modifying the component. Please apply these changes using your code editing capabilities.`
-          }
-        ]
-      };
-    }
-    changeDescription = `Suggested: add track('${event_name}') call in the handler near line ${line}`;
+        }
+      ]
+    };
   }
-  const diff = `--- ${file}
-+++ ${file}
-@@ -${line},1 +${line},1 @@
--${targetLine}
-+${newLine}`;
+  const changeDescription = `Add track('${event_name}') call (non-React file detected).
+
+1. Add import: import { track } from '@/lib/easyfunnel'
+2. Add call:   track('${event_name}') at the relevant point` + handlerHint + `
+
+Note: lib/easyfunnel.ts is generated by setup_sdk. If it doesn't exist, run setup_sdk first.`;
   return {
     content: [
       {
         type: "text",
-        text: `${changeDescription}
+        text: `Instrumentation suggestion for ${file}:${line}
 
-Diff preview:
-\`\`\`diff
-${diff}
-\`\`\`
+${changeDescription}
 
-Apply this change to ${file} at line ${line}.`
+Please apply these changes using your code editing capabilities.`
       }
     ]
   };
@@ -832,8 +1012,8 @@ var queryEventsDefinition = {
       project_id: { type: "string", description: "Project ID" },
       query_type: {
         type: "string",
-        enum: ["count", "recent", "breakdown", "section_engagement", "traffic_sources"],
-        description: "Type of query"
+        enum: ["count", "recent", "breakdown", "section_engagement", "traffic_sources", "engagement"],
+        description: 'Type of query. Use "engagement" to get scroll depth and engaged time metrics.'
       },
       event_name: {
         type: "string",
@@ -871,7 +1051,9 @@ async function queryEvents(client2, args) {
 `;
     output += `  Unique sessions: ${data.unique_sessions}
 `;
-    output += `  Unique users: ${data.unique_users}
+    output += `  Unique visitors: ${data.unique_visitors}
+`;
+    output += `  Identified users: ${data.identified_users}
 `;
   } else if (args.query_type === "recent") {
     output = `Recent events:
@@ -881,8 +1063,43 @@ async function queryEvents(client2, args) {
       output += `  [${event.created_at}] ${event.event_name}`;
       if (event.properties?.url) output += ` \u2014 ${event.properties.url}`;
       output += "\n";
+      if (event.properties) {
+        const props = { ...event.properties };
+        delete props.url;
+        const keys = Object.keys(props);
+        if (keys.length > 0) {
+          output += `    properties: ${JSON.stringify(props)}
+`;
+        }
+      }
     }
     if (!data.events?.length) output += "  No events found.\n";
+  } else if (args.query_type === "engagement") {
+    output = `Engagement metrics (${args.time_range || "7d"}):
+
+`;
+    output += `  Avg scroll depth: ${data.avg_scroll_depth}%
+`;
+    output += `  Avg engaged time: ${data.avg_engaged_time}s
+`;
+    output += `  Total engagement events: ${data.total_events}
+
+`;
+    output += `  Scroll depth distribution:
+`;
+    for (const bucket of data.scroll_depth_distribution || []) {
+      output += `    ${bucket.bucket}: ${bucket.count} events
+`;
+    }
+    if (data.top_pages?.length) {
+      output += `
+  Top pages by scroll depth:
+`;
+      for (const page of data.top_pages) {
+        output += `    ${page.url}: ${page.avg_scroll_depth}% avg, ${page.count} events
+`;
+      }
+    }
   } else if (args.query_type === "section_engagement") {
     output = `Section engagement (${args.time_range || "7d"}):
 
@@ -1681,6 +1898,69 @@ function findHardcodedKey(projectRoot) {
   }
   return null;
 }
+function scanAntiPatterns(projectRoot, isReactFramework) {
+  const warnings = [];
+  const files = walkDir2(projectRoot, [".ts", ".tsx", ".js", ".jsx"], [], 300);
+  const patterns = [
+    {
+      id: "window_ef",
+      regex: /window\.ef(?![\w.])/,
+      condition: () => true,
+      message: "window.ef doesn't exist. Import { track } from '@/lib/easyfunnel' instead."
+    },
+    {
+      id: "global_track",
+      regex: /window\.EasyFunnel\.track/,
+      condition: () => isReactFramework,
+      message: "Direct global access is fragile in React apps. Import { track } from '@/lib/easyfunnel' instead."
+    },
+    {
+      id: "hook_outside_component",
+      regex: /useTrack\(\)/,
+      condition: (filePath, content) => !isReactComponent(filePath, content),
+      message: "useTrack() only works inside React components. Use import { track } from '@/lib/easyfunnel' for non-component files."
+    }
+  ];
+  for (const file of files) {
+    const content = readFileSafe(file);
+    if (!content) continue;
+    const relPath = file.replace(projectRoot + "/", "");
+    const lines = content.split("\n");
+    for (const pattern of patterns) {
+      if (!pattern.condition(file, content)) continue;
+      for (let i = 0; i < lines.length; i++) {
+        if (pattern.regex.test(lines[i])) {
+          warnings.push({
+            file: relPath,
+            line: i + 1,
+            id: pattern.id,
+            message: pattern.message
+          });
+        }
+      }
+    }
+  }
+  if (isReactFramework) {
+    const helperExists = (0, import_fs6.existsSync)((0, import_path4.join)(projectRoot, "lib/easyfunnel.ts")) || (0, import_fs6.existsSync)((0, import_path4.join)(projectRoot, "src/lib/easyfunnel.ts"));
+    if (!helperExists) {
+      const hasTrackingOutsideReact = files.some((f) => {
+        const content = readFileSafe(f);
+        if (!content) return false;
+        if (isReactComponent(f, content)) return false;
+        return content.includes(".track(") || content.includes("window.ef") || content.includes("window.EasyFunnel");
+      });
+      if (hasTrackingOutsideReact) {
+        warnings.push({
+          file: "",
+          line: 0,
+          id: "missing_helper",
+          message: "No tracking helper found. Run setup_sdk to generate lib/easyfunnel.ts."
+        });
+      }
+    }
+  }
+  return warnings;
+}
 async function validateSetup(client2, args) {
   const { project_root, project_id } = args;
   const checks = [];
@@ -1780,6 +2060,13 @@ async function validateSetup(client2, args) {
       });
     }
   }
+  const isReactFramework = (() => {
+    const pkgPath = (0, import_path4.join)(project_root, "package.json");
+    if (!(0, import_fs6.existsSync)(pkgPath)) return false;
+    const pkg = (0, import_fs6.readFileSync)(pkgPath, "utf-8");
+    return pkg.includes('"react"') || pkg.includes("'react'");
+  })();
+  const antiPatterns = scanAntiPatterns(project_root, isReactFramework);
   const allPassed = checks.every((c) => c.passed);
   const failedChecks = checks.filter((c) => !c.passed);
   let output = "";
@@ -1829,6 +2116,22 @@ Next: Let me suggest conversion funnels based on what I found in your codebase.`
       }
     }
   }
+  if (antiPatterns.length > 0) {
+    output += `
+Recommendations:
+`;
+    for (const w of antiPatterns) {
+      if (w.file) {
+        output += `  [WARN] ${w.file}:${w.line} \u2014 ${w.message}
+`;
+      } else {
+        output += `  [WARN] ${w.message}
+`;
+      }
+    }
+    output += `
+`;
+  }
   return {
     content: [{ type: "text", text: output }]
   };
@@ -2202,6 +2505,112 @@ ${msg.content}
   };
 }
 
+// src/tools/get-best-practices.ts
+var getBestPracticesDefinition = {
+  name: "get_best_practices",
+  description: "Get framework-specific tracking best practices. Call this BEFORE writing any tracking code to avoid common integration mistakes.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      framework: {
+        type: "string",
+        enum: ["nextjs", "vite", "cra", "sveltekit", "html"],
+        description: "The framework. If omitted, returns general guidance for all frameworks."
+      }
+    },
+    required: []
+  }
+};
+var TRACKING_PATTERNS = `TRACKING PATTERNS \u2014 How to track events
+
+  React components:
+    import { useTrack } from '@easyfunnel/react'
+    const track = useTrack()
+    track('event_name', { key: 'value' })
+
+  Non-React files (utils, API handlers, state stores, callbacks):
+    import { track } from '@/lib/easyfunnel'
+    track('event_name', { key: 'value' })
+
+  HTML / script-tag sites:
+    window.EasyFunnel.track('event_name', { key: 'value' })
+
+  Declarative (zero code \u2014 just add an attribute):
+    <button data-ef-track="click_signup">Sign Up</button>`;
+var COMMON_MISTAKES = `COMMON MISTAKES \u2014 What NOT to do
+
+  1. window.ef does NOT exist.
+     The SDK never sets window.ef. If you see code polling for it, remove it.
+     Use: import { track } from '@/lib/easyfunnel'
+
+  2. useTrack() outside React components silently drops events.
+     Hooks require React context. In plain .ts files, use the helper module.
+     Use: import { track } from '@/lib/easyfunnel'
+
+  3. window.EasyFunnel.track() in React apps is fragile.
+     It bypasses the React lifecycle and may fire before SDK initializes.
+     Use: useTrack() in components, or import { track } from '@/lib/easyfunnel'
+
+  4. Custom global polling/bridging code is unnecessary.
+     setup_sdk generates lib/easyfunnel.ts and a bridge component automatically.
+     Do NOT write your own window.* bridge \u2014 use the generated helper.`;
+var CHECKLISTS = {
+  nextjs: `SETUP CHECKLIST \u2014 Next.js
+
+  [1] EasyFunnelProvider wraps {children} in app/layout.tsx
+  [2] EfBridge component rendered inside the provider (syncs context to helper)
+  [3] lib/easyfunnel.ts exists (generated by setup_sdk)
+  [4] Components using useTrack() have 'use client' directive
+  [5] API key set via NEXT_PUBLIC_EASYFUNNEL_KEY in .env.local`,
+  vite: `SETUP CHECKLIST \u2014 Vite
+
+  [1] EasyFunnelProvider wraps the app in src/App.tsx or src/main.tsx
+  [2] EfBridge component rendered inside the provider
+  [3] src/lib/easyfunnel.ts exists (generated by setup_sdk)
+  [4] API key set via VITE_EASYFUNNEL_KEY in .env`,
+  cra: `SETUP CHECKLIST \u2014 Create React App
+
+  [1] EasyFunnelProvider wraps the app in src/App.tsx
+  [2] EfBridge component rendered inside the provider
+  [3] src/lib/easyfunnel.ts exists (generated by setup_sdk)
+  [4] API key set via REACT_APP_EASYFUNNEL_KEY in .env`,
+  sveltekit: `SETUP CHECKLIST \u2014 SvelteKit
+
+  [1] SDK loaded via <script> tag in +layout.svelte (React provider does NOT work in Svelte)
+  [2] Tracking outside components requires a manual singleton pattern
+  [3] API key set via PUBLIC_EASYFUNNEL_KEY in .env`,
+  html: `SETUP CHECKLIST \u2014 HTML / Script Tag
+
+  [1] <script defer data-api-key="ef_..." src="https://easyfunnel.co/sdk.js"></script> in <head>
+  [2] Track via window.EasyFunnel.track() after page load
+  [3] No helper module needed \u2014 window.EasyFunnel IS the global`
+};
+var GENERAL_CHECKLIST = `SETUP CHECKLIST \u2014 General
+
+  React frameworks (Next.js, Vite, CRA):
+    [1] EasyFunnelProvider wraps the app
+    [2] EfBridge component rendered inside the provider
+    [3] lib/easyfunnel.ts helper exists for non-component tracking
+    [4] Next.js: 'use client' on components using hooks
+
+  HTML / Script Tag:
+    [1] SDK script tag in <head>
+    [2] Track via window.EasyFunnel.track()
+
+  Pass framework parameter for a framework-specific checklist.`;
+async function getBestPractices(args) {
+  const { framework } = args;
+  let output = TRACKING_PATTERNS + "\n\n" + COMMON_MISTAKES + "\n\n";
+  if (framework && CHECKLISTS[framework]) {
+    output += CHECKLISTS[framework];
+  } else {
+    output += GENERAL_CHECKLIST;
+  }
+  return {
+    content: [{ type: "text", text: output }]
+  };
+}
+
 // src/index.ts
 var apiKey = process.env.EASYFUNNEL_API_KEY;
 if (!apiKey) {
@@ -2233,7 +2642,8 @@ server.setRequestHandler(import_types.ListToolsRequestSchema, async () => ({
     deleteFunnelDefinition,
     updateFunnelDefinition,
     setupChatWidgetDefinition,
-    queryConversationsDefinition
+    queryConversationsDefinition,
+    getBestPracticesDefinition
   ]
 }));
 server.setRequestHandler(import_types.CallToolRequestSchema, async (request) => {
@@ -2271,6 +2681,8 @@ server.setRequestHandler(import_types.CallToolRequestSchema, async (request) =>
       return setupChatWidget(client, args);
     case "query_conversations":
       return queryConversations(client, args);
+    case "get_best_practices":
+      return getBestPractices(args);
     default:
       throw new Error(`Unknown tool: ${name}`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@easyfunnel/mcp",
-  "version": "0.1.10",
+  "version": "0.2.0",
   "description": "MCP server for easyfunnel.co — AI-powered analytics tools for Claude/Cursor",
   "main": "dist/index.js",
   "bin": {