@easyfunnel/mcp 0.1.0

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,718 @@
+#!/usr/bin/env node
+"use strict";
+
+// src/index.ts
+var import_server = require("@modelcontextprotocol/sdk/server/index.js");
+var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
+var import_types = require("@modelcontextprotocol/sdk/types.js");
+
+// src/api-client.ts
+var DEFAULT_BASE_URL = "https://easyfunnel.so";
+var ApiClient = class {
+  constructor(apiKey2, baseUrl2) {
+    this.apiKey = apiKey2;
+    this.baseUrl = baseUrl2 || DEFAULT_BASE_URL;
+  }
+  async request(path, options = {}) {
+    const url = `${this.baseUrl}/api/mcp${path}`;
+    const res = await fetch(url, {
+      ...options,
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`,
+        ...options.headers
+      }
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`API error ${res.status}: ${text}`);
+    }
+    return res.json();
+  }
+  async listProjects() {
+    return this.request("/projects");
+  }
+  async createProject(name, domainWhitelist) {
+    return this.request("/projects", {
+      method: "POST",
+      body: JSON.stringify({ name, domain_whitelist: domainWhitelist })
+    });
+  }
+  async createFunnel(projectId, name, steps) {
+    return this.request(`/projects/${projectId}/funnels`, {
+      method: "POST",
+      body: JSON.stringify({ name, steps })
+    });
+  }
+  async getFunnelHealth(projectId, funnelId, timeRange) {
+    const params = new URLSearchParams();
+    if (funnelId) params.set("funnel_id", funnelId);
+    if (timeRange) params.set("time_range", timeRange);
+    return this.request(
+      `/projects/${projectId}/funnels/${funnelId}?${params.toString()}`
+    );
+  }
+  async queryEvents(projectId, params) {
+    const searchParams = new URLSearchParams();
+    searchParams.set("query_type", params.query_type);
+    if (params.event_name) searchParams.set("event_name", params.event_name);
+    if (params.time_range) searchParams.set("time_range", params.time_range);
+    if (params.group_by) searchParams.set("group_by", params.group_by);
+    if (params.limit) searchParams.set("limit", params.limit.toString());
+    return this.request(
+      `/projects/${projectId}/events?${searchParams.toString()}`
+    );
+  }
+};
+
+// src/tools/list-projects.ts
+var listProjectsDefinition = {
+  name: "list_projects",
+  description: "List all easyfunnel projects for this account",
+  inputSchema: {
+    type: "object",
+    properties: {}
+  }
+};
+async function listProjects(client2) {
+  const projects = await client2.listProjects();
+  return { content: [{ type: "text", text: JSON.stringify(projects, null, 2) }] };
+}
+
+// src/tools/create-project.ts
+var createProjectDefinition = {
+  name: "create_project",
+  description: "Create a new easyfunnel project",
+  inputSchema: {
+    type: "object",
+    properties: {
+      name: { type: "string", description: "Project name" },
+      domain_whitelist: {
+        type: "array",
+        items: { type: "string" },
+        description: "Optional list of allowed domains"
+      }
+    },
+    required: ["name"]
+  }
+};
+async function createProject(client2, args) {
+  const project = await client2.createProject(args.name, args.domain_whitelist);
+  return {
+    content: [
+      {
+        type: "text",
+        text: `Project created successfully!
+
+Name: ${project.name}
+ID: ${project.id}
+API Key: ${project.api_key}
+
+Use this API key in the SDK to start tracking events.`
+      }
+    ]
+  };
+}
+
+// src/tools/setup-sdk.ts
+var import_fs = require("fs");
+var import_path = require("path");
+var import_child_process = require("child_process");
+var setupSdkDefinition = {
+  name: "setup_sdk",
+  description: "Install the easyfunnel SDK and add the provider to a Next.js/React project",
+  inputSchema: {
+    type: "object",
+    properties: {
+      project_api_key: {
+        type: "string",
+        description: "The project API key (ef_...)"
+      },
+      project_root: {
+        type: "string",
+        description: "Absolute path to the project root directory"
+      },
+      framework: {
+        type: "string",
+        enum: ["nextjs", "react", "html"],
+        description: "The framework used in the project"
+      }
+    },
+    required: ["project_api_key", "project_root", "framework"]
+  }
+};
+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";
+  if ((0, import_fs.existsSync)((0, import_path.join)(projectRoot, "yarn.lock"))) return "yarn";
+  return "npm";
+}
+async function setupSdk(args) {
+  const { project_api_key, project_root, framework } = args;
+  const filesModified = [];
+  if (framework === "html") {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `For HTML projects, add this script tag to your <head>:
+
+<script defer data-api-key="${project_api_key}" src="https://easyfunnel.so/sdk.js"></script>
+
+This will automatically track page views and clicks on elements with data-ef-track attributes.`
+        }
+      ]
+    };
+  }
+  const pm = detectPackageManager(project_root);
+  const installCmd = pm === "npm" ? "npm install @easyfunnel/sdk @easyfunnel/react" : `${pm} add @easyfunnel/sdk @easyfunnel/react`;
+  try {
+    (0, import_child_process.execSync)(installCmd, { cwd: project_root, stdio: "pipe" });
+  } catch (e) {
+  }
+  filesModified.push("package.json");
+  const envPath = (0, import_path.join)(project_root, ".env.local");
+  const envLine = `NEXT_PUBLIC_EASYFUNNEL_KEY=${project_api_key}`;
+  if ((0, import_fs.existsSync)(envPath)) {
+    const content = (0, import_fs.readFileSync)(envPath, "utf-8");
+    if (!content.includes("NEXT_PUBLIC_EASYFUNNEL_KEY")) {
+      (0, import_fs.writeFileSync)(envPath, content + "\n" + envLine + "\n");
+      filesModified.push(".env.local");
+    }
+  } else {
+    (0, import_fs.writeFileSync)(envPath, envLine + "\n");
+    filesModified.push(".env.local");
+  }
+  if (framework === "nextjs") {
+    const layoutPaths = [
+      (0, import_path.join)(project_root, "app", "layout.tsx"),
+      (0, import_path.join)(project_root, "app", "layout.jsx"),
+      (0, import_path.join)(project_root, "src", "app", "layout.tsx"),
+      (0, import_path.join)(project_root, "src", "app", "layout.jsx")
+    ];
+    for (const layoutPath of layoutPaths) {
+      if ((0, import_fs.existsSync)(layoutPath)) {
+        let content = (0, import_fs.readFileSync)(layoutPath, "utf-8");
+        if (!content.includes("EasyFunnelProvider")) {
+          const importLine = `import { EasyFunnelProvider } from '@easyfunnel/react'
+`;
+          content = importLine + content;
+          content = content.replace(
+            /(\{children\})/,
+            `<EasyFunnelProvider apiKey={process.env.NEXT_PUBLIC_EASYFUNNEL_KEY!}>
+          $1
+        </EasyFunnelProvider>`
+          );
+          (0, import_fs.writeFileSync)(layoutPath, content);
+          filesModified.push(layoutPath.replace(project_root + "/", ""));
+        }
+        break;
+      }
+    }
+  } else if (framework === "react") {
+    const appPaths = [
+      (0, import_path.join)(project_root, "src", "App.tsx"),
+      (0, import_path.join)(project_root, "src", "App.jsx"),
+      (0, import_path.join)(project_root, "App.tsx"),
+      (0, import_path.join)(project_root, "App.jsx")
+    ];
+    for (const appPath of appPaths) {
+      if ((0, import_fs.existsSync)(appPath)) {
+        let content = (0, import_fs.readFileSync)(appPath, "utf-8");
+        if (!content.includes("EasyFunnelProvider")) {
+          const importLine = `import { EasyFunnelProvider } from '@easyfunnel/react'
+`;
+          content = importLine + content;
+          (0, import_fs.writeFileSync)(appPath, content);
+          filesModified.push(appPath.replace(project_root + "/", ""));
+        }
+        break;
+      }
+    }
+  }
+  return {
+    content: [
+      {
+        type: "text",
+        text: `SDK setup complete!
+
+Files modified:
+${filesModified.map((f) => `  - ${f}`).join("\n")}
+
+The EasyFunnel provider is now wrapping your app. Page views and click tracking are automatic.
+
+Next: I can scan your codebase for interactive elements to add tracking to.`
+      }
+    ]
+  };
+}
+
+// src/tools/scan-for-actions.ts
+var import_fs2 = require("fs");
+var import_path2 = require("path");
+var scanForActionsDefinition = {
+  name: "scan_for_actions",
+  description: "Scan a codebase for interactive elements worth tracking (buttons, forms, links, CTAs)",
+  inputSchema: {
+    type: "object",
+    properties: {
+      directory: {
+        type: "string",
+        description: "Absolute path to the directory to scan"
+      },
+      file_patterns: {
+        type: "array",
+        items: { type: "string" },
+        description: "File extensions to scan (default: .tsx, .jsx, .html)"
+      }
+    },
+    required: ["directory"]
+  }
+};
+function scanFile(filePath, baseDir) {
+  const results = [];
+  const content = (0, import_fs2.readFileSync)(filePath, "utf-8");
+  const lines = content.split("\n");
+  const relativePath = (0, import_path2.relative)(baseDir, filePath);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineNum = i + 1;
+    const hasTracking = line.includes("data-ef-track");
+    const buttonMatch = line.match(/<(?:button|Button)[\s>]/);
+    if (buttonMatch) {
+      const nearby = lines.slice(i, Math.min(i + 3, lines.length)).join(" ");
+      const textMatch = nearby.match(/>([^<]+)</);
+      const text = textMatch ? textMatch[1].trim() : "button";
+      const suggested = `click_${text.toLowerCase().replace(/[^a-z0-9]+/g, "_").slice(0, 30)}`;
+      results.push({
+        file: relativePath,
+        line: lineNum,
+        element_type: "button",
+        context: `Button "${text}"`,
+        suggested_event_name: suggested,
+        already_tracked: hasTracking
+      });
+    }
+    const linkMatch = line.match(/<(?:a|Link)[\s]/);
+    if (linkMatch && !line.includes("<label")) {
+      const hrefMatch = line.match(/href=["']([^"']+)["']/);
+      const textMatch = lines.slice(i, Math.min(i + 2, lines.length)).join(" ").match(/>([^<]+)</);
+      const text = textMatch ? textMatch[1].trim() : hrefMatch?.[1] || "link";
+      const suggested = `click_${text.toLowerCase().replace(/[^a-z0-9]+/g, "_").slice(0, 30)}`;
+      results.push({
+        file: relativePath,
+        line: lineNum,
+        element_type: "link",
+        context: `Link "${text}"${hrefMatch ? ` \u2192 ${hrefMatch[1]}` : ""}`,
+        suggested_event_name: suggested,
+        already_tracked: hasTracking
+      });
+    }
+    if (line.includes("onSubmit") || line.includes("handleSubmit") || line.match(/action=["']/)) {
+      const formName = line.match(/(?:function|const)\s+(\w+)/)?.[1] || "form";
+      const suggested = `submit_${formName.toLowerCase().replace(/handle|submit/gi, "").replace(/[^a-z0-9]+/g, "_").slice(0, 30) || "form"}`;
+      results.push({
+        file: relativePath,
+        line: lineNum,
+        element_type: "form",
+        context: `Form submission handler`,
+        suggested_event_name: suggested,
+        already_tracked: line.includes("ef.track") || line.includes("useTrack")
+      });
+    }
+  }
+  return results;
+}
+function walkDir(dir, extensions, results = []) {
+  try {
+    const entries = (0, import_fs2.readdirSync)(dir);
+    for (const entry of entries) {
+      if (entry.startsWith(".") || entry === "node_modules" || entry === "dist" || entry === ".next") {
+        continue;
+      }
+      const fullPath = (0, import_path2.join)(dir, entry);
+      const stat = (0, import_fs2.statSync)(fullPath);
+      if (stat.isDirectory()) {
+        walkDir(fullPath, extensions, results);
+      } else if (extensions.some((ext) => entry.endsWith(ext))) {
+        results.push(fullPath);
+      }
+    }
+  } catch {
+  }
+  return results;
+}
+async function scanForActions(args) {
+  const extensions = args.file_patterns || [".tsx", ".jsx", ".html"];
+  const files = walkDir(args.directory, extensions);
+  const allResults = [];
+  for (const file of files) {
+    const results = scanFile(file, args.directory);
+    allResults.push(...results);
+  }
+  if (allResults.length === 0) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: "No trackable interactions found in the scanned directory."
+        }
+      ]
+    };
+  }
+  const tracked = allResults.filter((r) => r.already_tracked).length;
+  const untracked = allResults.length - tracked;
+  let output = `Found ${allResults.length} trackable interactions (${untracked} untracked, ${tracked} already tracked):
+
+`;
+  allResults.forEach((r, i) => {
+    const status = r.already_tracked ? "[TRACKED]" : "[NOT TRACKED]";
+    output += `${i + 1}. ${status} ${r.file}:${r.line} \u2014 ${r.context} \u2192 suggested: ${r.suggested_event_name}
+`;
+  });
+  return {
+    content: [{ type: "text", text: output }]
+  };
+}
+
+// src/tools/instrument-code.ts
+var import_fs3 = require("fs");
+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.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      file: {
+        type: "string",
+        description: "Absolute path to the file to instrument"
+      },
+      line: {
+        type: "number",
+        description: "Line number of the element to instrument"
+      },
+      event_name: {
+        type: "string",
+        description: "The event name to track (e.g., click_signup)"
+      },
+      method: {
+        type: "string",
+        enum: ["attribute", "track_call"],
+        description: "attribute: add data-ef-track attribute. track_call: add ef.track() call inside handler."
+      }
+    },
+    required: ["file", "line", "event_name", "method"]
+  }
+};
+async function instrumentCode(args) {
+  const { file, line, event_name, method } = args;
+  const content = (0, import_fs3.readFileSync)(file, "utf-8");
+  const lines = content.split("\n");
+  const targetLine = lines[line - 1];
+  if (!targetLine) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error: Line ${line} not found in ${file} (file has ${lines.length} lines).`
+        }
+      ]
+    };
+  }
+  let newLine;
+  let changeDescription;
+  if (method === "attribute") {
+    if (targetLine.includes("data-ef-track")) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Line ${line} already has a data-ef-track attribute.`
+          }
+        ]
+      };
+    }
+    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:
+
+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}
+
+${changeDescription}
+
+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}`;
+  return {
+    content: [
+      {
+        type: "text",
+        text: `${changeDescription}
+
+Diff preview:
+\`\`\`diff
+${diff}
+\`\`\`
+
+Apply this change to ${file} at line ${line}.`
+      }
+    ]
+  };
+}
+
+// src/tools/create-funnel.ts
+var createFunnelDefinition = {
+  name: "create_funnel",
+  description: "Create a conversion funnel from a sequence of events",
+  inputSchema: {
+    type: "object",
+    properties: {
+      project_id: { type: "string", description: "Project ID" },
+      name: { type: "string", description: "Funnel name" },
+      steps: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            event_name: { type: "string" },
+            label: { type: "string" }
+          },
+          required: ["event_name", "label"]
+        },
+        description: "Ordered funnel steps"
+      }
+    },
+    required: ["project_id", "name", "steps"]
+  }
+};
+async function createFunnel(client2, args) {
+  const funnel = await client2.createFunnel(
+    args.project_id,
+    args.name,
+    args.steps
+  );
+  const stepsDisplay = args.steps.map((s, i) => `  ${i + 1}. ${s.label} (${s.event_name})`).join("\n");
+  return {
+    content: [
+      {
+        type: "text",
+        text: `Funnel "${funnel.name}" created!
+
+ID: ${funnel.id}
+Steps:
+${stepsDisplay}
+
+You can now query this funnel's health to see conversion data.`
+      }
+    ]
+  };
+}
+
+// src/tools/get-funnel-health.ts
+var getFunnelHealthDefinition = {
+  name: "get_funnel_health",
+  description: "Get the conversion and drop-off data for a specific funnel or the worst-performing funnel",
+  inputSchema: {
+    type: "object",
+    properties: {
+      project_id: { type: "string", description: "Project ID" },
+      funnel_id: {
+        type: "string",
+        description: "Funnel ID (optional \u2014 if omitted, returns the worst-performing funnel)"
+      },
+      time_range: {
+        type: "string",
+        enum: ["24h", "7d", "30d"],
+        description: "Time range (default: 7d)"
+      }
+    },
+    required: ["project_id"]
+  }
+};
+async function getFunnelHealth(client2, args) {
+  const data = await client2.getFunnelHealth(
+    args.project_id,
+    args.funnel_id || "",
+    args.time_range || "7d"
+  );
+  let output = `Funnel: ${data.funnel_name}
+Time range: ${data.time_range}
+
+`;
+  for (const step of data.steps) {
+    const bar = "\u2588".repeat(Math.max(1, Math.round(step.count / (data.steps[0]?.count || 1) * 20)));
+    output += `${step.label}: ${step.count} ${bar}`;
+    if (step.drop_off_pct !== null) {
+      output += ` (\u2193 ${step.drop_off_pct}% drop-off)`;
+    }
+    output += "\n";
+  }
+  output += `
+Overall conversion: ${data.overall_conversion}%`;
+  if (data.median_time_to_convert) {
+    output += `
+Median time to convert: ${data.median_time_to_convert}`;
+  }
+  if (data.suggestion) {
+    output += `
+
+\u{1F4A1} ${data.suggestion}`;
+  }
+  return {
+    content: [{ type: "text", text: output }]
+  };
+}
+
+// src/tools/query-events.ts
+var queryEventsDefinition = {
+  name: "query_events",
+  description: "Query raw event data for a project \u2014 counts, recent events, or filtered lists",
+  inputSchema: {
+    type: "object",
+    properties: {
+      project_id: { type: "string", description: "Project ID" },
+      query_type: {
+        type: "string",
+        enum: ["count", "recent", "breakdown"],
+        description: "Type of query"
+      },
+      event_name: {
+        type: "string",
+        description: "Filter by event name (optional)"
+      },
+      time_range: {
+        type: "string",
+        enum: ["24h", "7d", "30d"],
+        description: "Time range (default: 7d)"
+      },
+      group_by: {
+        type: "string",
+        enum: ["event_name", "url", "browser", "os"],
+        description: "Group by field (for breakdown query)"
+      },
+      limit: {
+        type: "number",
+        description: "Max results to return (default: 50)"
+      }
+    },
+    required: ["project_id", "query_type"]
+  }
+};
+async function queryEvents(client2, args) {
+  const data = await client2.queryEvents(args.project_id, args);
+  let output;
+  if (args.query_type === "count") {
+    output = `Event count (${args.time_range || "7d"}):
+`;
+    output += `  Total events: ${data.total_events}
+`;
+    output += `  Unique sessions: ${data.unique_sessions}
+`;
+    output += `  Unique users: ${data.unique_users}
+`;
+  } else if (args.query_type === "recent") {
+    output = `Recent events:
+
+`;
+    for (const event of data.events || []) {
+      output += `  [${event.created_at}] ${event.event_name}`;
+      if (event.properties?.url) output += ` \u2014 ${event.properties.url}`;
+      output += "\n";
+    }
+    if (!data.events?.length) output += "  No events found.\n";
+  } else {
+    output = `Event breakdown (${args.time_range || "7d"}):
+
+`;
+    for (const [key, count] of Object.entries(data.breakdown || {})) {
+      output += `  ${key}: ${count}
+`;
+    }
+    if (!data.breakdown || Object.keys(data.breakdown).length === 0) {
+      output += "  No events found.\n";
+    }
+  }
+  return {
+    content: [{ type: "text", text: output }]
+  };
+}
+
+// src/index.ts
+var apiKey = process.env.EASYFUNNEL_API_KEY;
+if (!apiKey) {
+  console.error(
+    "EASYFUNNEL_API_KEY environment variable is required. Get your account API key from https://easyfunnel.so/dashboard/settings"
+  );
+  process.exit(1);
+}
+var baseUrl = process.env.EASYFUNNEL_API_URL || void 0;
+var client = new ApiClient(apiKey, baseUrl);
+var server = new import_server.Server(
+  { name: "easyfunnel", version: "0.1.0" },
+  { capabilities: { tools: {} } }
+);
+server.setRequestHandler(import_types.ListToolsRequestSchema, async () => ({
+  tools: [
+    listProjectsDefinition,
+    createProjectDefinition,
+    setupSdkDefinition,
+    scanForActionsDefinition,
+    instrumentCodeDefinition,
+    createFunnelDefinition,
+    getFunnelHealthDefinition,
+    queryEventsDefinition
+  ]
+}));
+server.setRequestHandler(import_types.CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  switch (name) {
+    case "list_projects":
+      return listProjects(client);
+    case "create_project":
+      return createProject(client, args);
+    case "setup_sdk":
+      return setupSdk(args);
+    case "scan_for_actions":
+      return scanForActions(args);
+    case "instrument_code":
+      return instrumentCode(args);
+    case "create_funnel":
+      return createFunnel(client, args);
+    case "get_funnel_health":
+      return getFunnelHealth(client, args);
+    case "query_events":
+      return queryEvents(client, args);
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+});
+async function main() {
+  const transport = new import_stdio.StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch(console.error);

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@easyfunnel/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for easyfunnel.so — AI-powered analytics tools for Claude/Cursor",
+  "main": "dist/index.js",
+  "bin": {
+    "easyfunnel-mcp": "dist/index.js"
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs --dts",
+    "dev": "tsup src/index.ts --format cjs --dts --watch"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "keywords": ["mcp", "analytics", "funnel", "claude", "cursor", "easyfunnel"],
+  "license": "MIT"
+}