@firstdistro/mcp 1.0.0 → 1.1.1

package/README.md

@@ -1,26 +1,33 @@
 # @firstdistro/mcp
 
-MCP server for [FirstDistro](https://firstdistro.com) — Query and manage customer health from AI assistants like Claude.
+MCP server for [FirstDistro](https://firstdistro.com) — Query customer health and set up the SDK from AI assistants like Claude.
 
 ## Quick Start
 
-### 1. Install and configure
+### 1. Create a FirstDistro Account
 
-**Interactive setup (recommended):**
+Sign up at [firstdistro.com/auth/register](https://firstdistro.com/auth/register) and get your API key from **Settings → API Keys**.
+
+### 2. Configure the MCP Server
+
+**Option A: Interactive setup (recommended)**
 ```bash
 npx @firstdistro/mcp init
 ```
 
-**Or with API key directly:**
+**Option B: With API key directly**
 ```bash
 npx @firstdistro/mcp init --api-key sk_live_xxxxx
 ```
 
-Get your API key from [Settings → API Keys](https://firstdistro.com/dashboard/settings/sdk-configuration) in your FirstDistro dashboard.
+**Option C: Claude Code CLI**
+```bash
+claude mcp add firstdistro -e FIRSTDISTRO_API_KEY=sk_live_xxx -- npx -y @firstdistro/mcp
+```
 
 > **Note:** Use an **API Key** (`sk_live_...` or `sk_test_...`), not an Installation Token (`fd_...`). Installation Tokens are for the browser SDK only.
 
-### 2. Add to Claude Code
+### 3. Add to Claude Code
 
 Add to your `~/.claude/settings.json`:
 
@@ -35,18 +42,20 @@ Add to your `~/.claude/settings.json`:
 }
 ```
 
-### 3. Restart Claude Code
+### 4. Restart Claude Code
 
 That's it! Try asking:
+- "Set up FirstDistro SDK in my Next.js app"
 - "Show me my FirstDistro experiences"
 - "Who's stuck in onboarding?"
 - "What's Acme Corp's health score?"
-- "List my at-risk customers"
 
 ## Available Tools
 
 | Tool | Description |
 |------|-------------|
+| `get_sdk_config` | Get your installation token and SDK setup snippets |
+| `setup_sdk` | Generate files to set up FirstDistro SDK in your project |
 | `list_experiences` | List all configured user journeys |
 | `get_experience_stats` | Get funnel metrics for an experience |
 | `get_stuck_customers` | Find customers stuck in a journey |
@@ -54,7 +63,50 @@ That's it! Try asking:
 | `list_at_risk_accounts` | List critical and at-risk customers |
 | `check_events_flowing` | Verify SDK is sending events |
 
-### Example Usage
+## SDK Setup with AI
+
+Ask your AI assistant to set up the FirstDistro SDK:
+
+```
+User: "Add FirstDistro to my Next.js app to track user activity"
+
+Claude: I'll set up FirstDistro in your project.
+
+[Runs npm install @firstdistro/sdk]
+[Creates app/providers.tsx with your installation token]
+[Updates app/layout.tsx to use the provider]
+
+Done! FirstDistro is now installed. Try refreshing your app
+and interacting with it, then ask me "Are events flowing?"
+to verify the setup.
+```
+
+### Supported Frameworks
+
+| Framework | Status |
+|-----------|--------|
+| Next.js (App Router) | Full support |
+| React + Vite | Full support |
+| Next.js (Pages Router) | Coming soon |
+| Create React App | Coming soon |
+
+### Auth Integrations
+
+The `setup_sdk` tool can generate user identification code for:
+
+- **NextAuth.js** — Uses `useSession` hook
+- **Clerk** — Uses `useUser` hook
+- **Supabase Auth** — Uses `onAuthStateChange`
+- **Custom** — Provides template with TODOs
+
+## Example Usage
+
+**Set up the SDK:**
+```
+User: "Set up FirstDistro in my React + Vite project with Clerk auth"
+
+Claude: [Generates provider component, main.tsx updates, and Clerk user setup]
+```
 
 **Check customer health:**
 ```
@@ -82,18 +134,20 @@ Found 3 stuck customer(s):
 - DataFlow: mike@dataflow.com (stuck 18 min)
 ```
 
-**List at-risk accounts:**
+**Verify events are flowing:**
 ```
-User: "Show me customers at risk of churning"
+User: "Are events flowing from my app?"
 
-Claude: At-Risk Accounts Summary:
-• Critical: 2
-• At-Risk: 5
-• Healthy: 43
+Claude: ✓ Events are flowing!
 
-- Acme Corp: Score 45/100 (critical) 📉
-- TechStart: Score 52/100 (at-risk) 📉
-- DataFlow: Score 58/100 (at-risk)
+Last event: 2 minutes ago
+Events (24h): 1,234
+Unique users (24h): 56
+
+Top Events (24h):
+  • page_view: 892
+  • button_click: 234
+  • form_submit: 108
 ```
 
 ## Configuration
@@ -116,12 +170,10 @@ You can also configure via environment variables (takes priority over config fil
 | `FIRSTDISTRO_API_KEY` | Your API key |
 | `FIRSTDISTRO_BASE_URL` | API base URL (default: https://firstdistro.com) |
 
-> **Important:** API keys start with `sk_live_` (production) or `sk_test_` (sandbox). Installation Tokens (`fd_...`) are for the browser SDK and won't work with the MCP server.
-
 ## Troubleshooting
 
 ### "Not configured" error
-Run `npx @firstdistro/mcp init` to set up your API key.
+Run `npx @firstdistro/mcp init` to set up your API key, or follow the setup message which includes a link to sign up.
 
 ### "Invalid API key" error
 1. Check you're using an API Key (`sk_live_...`), not an Installation Token (`fd_...`)
@@ -147,6 +199,9 @@ npm install
 # Build
 npm run build
 
+# Run tests
+npm test
+
 # Run locally
 node bin/firstdistro-mcp.js
 

package/dist/server.js

@@ -7,7 +7,8 @@ import { z } from "zod";
 import { readFileSync, existsSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
-var CONFIG_PATH = join(homedir(), ".firstdistro", "config.json");
+var CONFIG_DIR = join(homedir(), ".firstdistro");
+var CONFIG_PATH = join(CONFIG_DIR, "config.json");
 var DEFAULT_BASE_URL = "https://firstdistro.com";
 function loadConfig() {
   const envKey = process.env.FIRSTDISTRO_API_KEY;
@@ -44,7 +45,386 @@ function loadConfig() {
   }
 }
 
+// src/templates/nextjs-app.ts
+function generateProvidersFile(installationToken) {
+  return `'use client'
+
+import { FirstDistroProvider } from '@firstdistro/sdk/react'
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <FirstDistroProvider token="${installationToken}">
+      {children}
+    </FirstDistroProvider>
+  )
+}
+`;
+}
+function generateUserSetupComponent(authPattern) {
+  switch (authPattern) {
+    case "nextauth":
+      return `'use client'
+
+import { useSession } from 'next-auth/react'
+import { useFirstDistroSetup } from '@firstdistro/sdk/react'
+
+export function FirstDistroSetup() {
+  const { data: session } = useSession()
+
+  useFirstDistroSetup(session?.user ? {
+    userId: session.user.id,
+    userEmail: session.user.email || undefined,
+    userName: session.user.name || undefined,
+  } : null)
+
+  return null
+}
+`;
+    case "clerk":
+      return `'use client'
+
+import { useUser } from '@clerk/nextjs'
+import { useFirstDistroSetup } from '@firstdistro/sdk/react'
+
+export function FirstDistroSetup() {
+  const { user, isLoaded } = useUser()
+
+  useFirstDistroSetup(isLoaded && user ? {
+    userId: user.id,
+    userEmail: user.primaryEmailAddress?.emailAddress,
+    userName: user.fullName || undefined,
+  } : null)
+
+  return null
+}
+`;
+    case "supabase":
+      return `'use client'
+
+import { useEffect, useState } from 'react'
+import { createClient } from '@/lib/supabase/client'
+import { useFirstDistroSetup } from '@firstdistro/sdk/react'
+import type { User } from '@supabase/supabase-js'
+
+// Requires @supabase/ssr setup. See: https://supabase.com/docs/guides/auth/server-side/creating-a-client
+
+export function FirstDistroSetup() {
+  const [user, setUser] = useState<User | null>(null)
+  const supabase = createClient()
+
+  useEffect(() => {
+    supabase.auth.getUser().then(({ data: { user } }) => setUser(user))
+
+    const { data: { subscription } } = supabase.auth.onAuthStateChange(
+      (_event, session) => setUser(session?.user ?? null)
+    )
+
+    return () => subscription.unsubscribe()
+  }, [supabase])
+
+  useFirstDistroSetup(user ? {
+    userId: user.id,
+    userEmail: user.email,
+  } : null)
+
+  return null
+}
+`;
+    case "custom":
+      return `'use client'
+
+import { useFirstDistroSetup } from '@firstdistro/sdk/react'
+
+// CUSTOMIZE: Import your auth hook or context
+// import { useAuth } from './your-auth-provider'
+
+export function FirstDistroSetup() {
+  // CUSTOMIZE: Replace with your auth state
+  // const { user } = useAuth()
+  const user = null // Replace with your user object
+
+  useFirstDistroSetup(user ? {
+    userId: user.id,
+    userEmail: user.email,
+    userName: user.name,
+    // Optional: Add account info for B2B
+    // accountId: user.organizationId,
+    // accountName: user.organizationName,
+  } : null)
+
+  return null
+}
+`;
+    case "none":
+    default:
+      return null;
+  }
+}
+function generateNextjsAppFiles(installationToken, options = {}) {
+  const { includeUserSetup = true, authPattern = "none" } = options;
+  const files = [];
+  files.push({
+    path: "app/providers.tsx",
+    action: "create",
+    content: generateProvidersFile(installationToken),
+    description: "FirstDistro provider component that wraps your app"
+  });
+  files.push({
+    path: "app/layout.tsx",
+    action: "modify",
+    insertAfter: "import",
+    replace: {
+      old: "{children}",
+      new: "<Providers>{children}</Providers>"
+    },
+    description: 'Wrap your app with the Providers component. Add: import { Providers } from "./providers"'
+  });
+  if (includeUserSetup && authPattern !== "none") {
+    const userSetupContent = generateUserSetupComponent(authPattern);
+    if (userSetupContent) {
+      files.push({
+        path: "components/FirstDistroSetup.tsx",
+        action: "create",
+        content: userSetupContent,
+        description: `User identification component for ${authPattern}. Add <FirstDistroSetup /> inside your Providers.`
+      });
+    }
+  }
+  return files;
+}
+
+// src/templates/react-vite.ts
+function generateProviderFile(installationToken) {
+  return `import { FirstDistroProvider as FDProvider } from '@firstdistro/sdk/react'
+
+interface Props {
+  children: React.ReactNode
+}
+
+export function FirstDistroProvider({ children }: Props) {
+  return (
+    <FDProvider token="${installationToken}">
+      {children}
+    </FDProvider>
+  )
+}
+`;
+}
+function generateUserSetupComponent2(authPattern) {
+  switch (authPattern) {
+    case "supabase":
+      return `import { useEffect, useState } from 'react'
+import { supabase } from '../lib/supabase' // Adjust path as needed
+import { useFirstDistroSetup } from '@firstdistro/sdk/react'
+import type { User } from '@supabase/supabase-js'
+
+export function FirstDistroSetup() {
+  const [user, setUser] = useState<User | null>(null)
+
+  useEffect(() => {
+    supabase.auth.getUser().then(({ data: { user } }) => setUser(user))
+
+    const { data: { subscription } } = supabase.auth.onAuthStateChange(
+      (_event, session) => setUser(session?.user ?? null)
+    )
+
+    return () => subscription.unsubscribe()
+  }, [])
+
+  useFirstDistroSetup(user ? {
+    userId: user.id,
+    userEmail: user.email,
+  } : null)
+
+  return null
+}
+`;
+    case "clerk":
+      return `import { useUser } from '@clerk/clerk-react'
+import { useFirstDistroSetup } from '@firstdistro/sdk/react'
+
+export function FirstDistroSetup() {
+  const { user, isLoaded } = useUser()
+
+  useFirstDistroSetup(isLoaded && user ? {
+    userId: user.id,
+    userEmail: user.primaryEmailAddress?.emailAddress,
+    userName: user.fullName || undefined,
+  } : null)
+
+  return null
+}
+`;
+    case "custom":
+      return `import { useFirstDistroSetup } from '@firstdistro/sdk/react'
+
+// CUSTOMIZE: Import your auth hook or context
+// import { useAuth } from './your-auth-provider'
+
+export function FirstDistroSetup() {
+  // CUSTOMIZE: Replace with your auth state
+  // const { user } = useAuth()
+  const user = null // Replace with your user object
+
+  useFirstDistroSetup(user ? {
+    userId: user.id,
+    userEmail: user.email,
+    userName: user.name,
+    // Optional: Add account info for B2B
+    // accountId: user.organizationId,
+    // accountName: user.organizationName,
+  } : null)
+
+  return null
+}
+`;
+    case "nextauth":
+    case "none":
+    default:
+      return null;
+  }
+}
+function generateReactViteFiles(installationToken, options = {}) {
+  const { includeUserSetup = true, authPattern = "none" } = options;
+  const files = [];
+  files.push({
+    path: "src/providers/FirstDistroProvider.tsx",
+    action: "create",
+    content: generateProviderFile(installationToken),
+    description: "FirstDistro provider component"
+  });
+  files.push({
+    path: "src/main.tsx",
+    action: "modify",
+    insertAfter: "import",
+    replace: {
+      old: "<App />",
+      new: `<FirstDistroProvider>
+      <App />
+    </FirstDistroProvider>`
+    },
+    description: 'Wrap your App with FirstDistroProvider. Add: import { FirstDistroProvider } from "./providers/FirstDistroProvider"'
+  });
+  if (includeUserSetup && authPattern !== "none" && authPattern !== "nextauth") {
+    const userSetupContent = generateUserSetupComponent2(authPattern);
+    if (userSetupContent) {
+      files.push({
+        path: "src/components/FirstDistroSetup.tsx",
+        action: "create",
+        content: userSetupContent,
+        description: `User identification component for ${authPattern}. Add <FirstDistroSetup /> inside your FirstDistroProvider.`
+      });
+    }
+  }
+  return files;
+}
+
+// src/templates/index.ts
+function getFrameworkDisplayName(framework) {
+  const names = {
+    "nextjs-app": "Next.js (App Router)",
+    "nextjs-pages": "Next.js (Pages Router)",
+    "react-vite": "React + Vite",
+    "react-cra": "Create React App",
+    "vanilla": "Vanilla JavaScript"
+  };
+  return names[framework] || framework;
+}
+function generateSetupFiles(framework, installationToken, options = {}) {
+  switch (framework) {
+    case "nextjs-app":
+      return generateNextjsAppFiles(installationToken, options);
+    case "react-vite":
+      return generateReactViteFiles(installationToken, options);
+    case "nextjs-pages":
+    case "react-cra":
+    case "vanilla":
+      return [{
+        path: "README-FIRSTDISTRO.md",
+        action: "create",
+        content: `# FirstDistro SDK Setup
+
+Framework "${getFrameworkDisplayName(framework)}" template is coming soon.
+
+For now, please follow the manual setup instructions:
+
+1. Install the SDK:
+   npm install @firstdistro/sdk
+
+2. Add the provider to your app:
+   import { FirstDistroProvider } from '@firstdistro/sdk/react'
+
+   <FirstDistroProvider token="${installationToken}">
+     {/* your app */}
+   </FirstDistroProvider>
+
+3. Identify users after login:
+   import { useFirstDistroSetup } from '@firstdistro/sdk/react'
+
+   useFirstDistroSetup({
+     userId: user.id,
+     userEmail: user.email,
+   })
+
+4. Verify setup by asking: "Are events flowing?"
+`,
+        description: "Manual setup instructions for unsupported framework"
+      }];
+    default:
+      throw new Error(`Unsupported framework: ${framework}`);
+  }
+}
+function generateSetupResult(framework, installationToken, options = {}) {
+  const files = generateSetupFiles(framework, installationToken, options);
+  const commands = [
+    {
+      run: "npm install @firstdistro/sdk",
+      description: "Install the FirstDistro SDK"
+    }
+  ];
+  return {
+    installationToken,
+    framework,
+    commands,
+    files,
+    verification: {
+      tool: "check_events_flowing",
+      successMessage: "Events are flowing! FirstDistro is working.",
+      failureHint: "No events yet. Try refreshing your app and interacting with it."
+    },
+    nextSteps: [
+      'Create an Experience to track a user journey (e.g., "User Onboarding")',
+      'Ask: "Show my at-risk customers" to see health insights',
+      'Ask: "Who is stuck in onboarding?" to find users who need help'
+    ]
+  };
+}
+
 // src/server.ts
+var MCP_VERSION = "1.1.0";
+function detectMcpClient() {
+  if (process.env.CLAUDE_CODE || process.env.CLAUDE_PROJECT_ROOT) {
+    return "claude-code";
+  }
+  if (process.env.CURSOR_SESSION_ID || process.env.CURSOR_TRACE_ID) {
+    return "cursor";
+  }
+  if (process.env.WINDSURF_SESSION_ID || process.env.CODEIUM_API_KEY) {
+    return "windsurf";
+  }
+  if (process.env.CONTINUE_GLOBAL_DIR) {
+    return "continue";
+  }
+  return "unknown";
+}
+function getApiHeaders(apiKey) {
+  const client = detectMcpClient();
+  return {
+    "X-API-Key": apiKey,
+    "Content-Type": "application/json",
+    "User-Agent": `firstdistro-mcp/${MCP_VERSION} (${client})`
+  };
+}
 function formatHttpError(status, statusText, context) {
   switch (status) {
     case 401:
@@ -79,28 +459,46 @@ function formatNetworkError(error) {
   }
   return "Unknown network error occurred.";
 }
+function unwrapApiResponse(response) {
+  if (response && typeof response === "object" && "success" in response && "data" in response) {
+    return response.data;
+  }
+  return response;
+}
 async function startServer() {
-  const config = loadConfig();
+  let config = null;
+  let configError = null;
+  try {
+    config = loadConfig();
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    if (errorMessage.includes("not configured")) {
+      configError = null;
+    } else {
+      configError = errorMessage;
+    }
+  }
   const server = new McpServer({
     name: "firstdistro",
-    version: "1.0.0"
+    version: MCP_VERSION
   });
-  registerTools(server, config);
+  if (config) {
+    registerAuthenticatedTools(server, config);
+  } else {
+    registerUnconfiguredTools(server, configError);
+  }
   const transport = new StdioServerTransport();
   await server.connect(transport);
   console.error("[FirstDistro MCP] Server started");
 }
-function registerTools(server, config) {
+function registerAuthenticatedTools(server, config) {
   server.tool(
     "list_experiences",
-    "List all configured experiences (user journeys) for your FirstDistro account",
+    `List all user journeys/funnels you're tracking (called "experiences" in FirstDistro). Examples: onboarding flow, checkout funnel, feature adoption.`,
     async () => {
       try {
         const response = await fetch(`${config.baseUrl}/api/vendor/experiences`, {
-          headers: {
-            "X-API-Key": config.apiKey,
-            "Content-Type": "application/json"
-          }
+          headers: getApiHeaders(config.apiKey)
         });
         if (!response.ok) {
           return {
@@ -113,8 +511,9 @@ function registerTools(server, config) {
             isError: true
           };
         }
-        const data = await response.json();
-        const experiences = data.experiences || data;
+        const rawData = await response.json();
+        const data = unwrapApiResponse(rawData);
+        const experiences = data.experiences || [];
         if (!experiences || experiences.length === 0) {
           return {
             content: [
@@ -155,10 +554,7 @@ ${summary}`
     async () => {
       try {
         const response = await fetch(`${config.baseUrl}/api/mcp/events-status`, {
-          headers: {
-            "X-API-Key": config.apiKey,
-            "Content-Type": "application/json"
-          }
+          headers: getApiHeaders(config.apiKey)
         });
         if (!response.ok) {
           return {
@@ -171,7 +567,8 @@ ${summary}`
             isError: true
           };
         }
-        const data = await response.json();
+        const rawData = await response.json();
+        const data = unwrapApiResponse(rawData);
         if (data.eventsFlowing || data.hasEvents) {
           let topEventsText = "";
           if (data.topEvents && data.topEvents.length > 0) {
@@ -227,10 +624,7 @@ Unique users (24h): ${data.uniqueUsersLast24h ?? "N/A"}${topEventsText}`
         const response = await fetch(
           `${config.baseUrl}/api/vendor/customers/${accountId}`,
           {
-            headers: {
-              "X-API-Key": config.apiKey,
-              "Content-Type": "application/json"
-            }
+            headers: getApiHeaders(config.apiKey)
           }
         );
         if (!response.ok) {
@@ -244,8 +638,9 @@ Unique users (24h): ${data.uniqueUsersLast24h ?? "N/A"}${topEventsText}`
             isError: true
           };
         }
-        const data = await response.json();
-        const health = data.health || data;
+        const rawData = await response.json();
+        const data = unwrapApiResponse(rawData);
+        const health = data.health || {};
         return {
           content: [
             {
@@ -274,7 +669,7 @@ Last Seen: ${data.account?.lastSeenAt || "Unknown"}`
   );
   server.tool(
     "get_experience_stats",
-    "Get funnel statistics for a specific experience (conversion rates, drop-offs)",
+    "Get funnel statistics for a user journey: how many started, completed, conversion rate, and average time to complete.",
     {
       experienceId: z.string().describe("The experience ID or slug"),
       range: z.enum(["7d", "30d", "90d"]).optional().describe("Time range for stats (default: 7d)")
@@ -285,10 +680,7 @@ Last Seen: ${data.account?.lastSeenAt || "Unknown"}`
         if (range) params.set("range", range);
         const url = `${config.baseUrl}/api/vendor/experiences/${experienceId}/stats${params.toString() ? "?" + params.toString() : ""}`;
         const response = await fetch(url, {
-          headers: {
-            "X-API-Key": config.apiKey,
-            "Content-Type": "application/json"
-          }
+          headers: getApiHeaders(config.apiKey)
         });
         if (!response.ok) {
           return {
@@ -301,7 +693,8 @@ Last Seen: ${data.account?.lastSeenAt || "Unknown"}`
             isError: true
           };
         }
-        const data = await response.json();
+        const rawData = await response.json();
+        const data = unwrapApiResponse(rawData);
         const stats = data.stats || {};
         const exp = data.experience || {};
         let avgTimeDisplay = "N/A";
@@ -344,7 +737,7 @@ Avg Time to Complete: ${avgTimeDisplay}`
   );
   server.tool(
     "get_stuck_customers",
-    "Find customers who are stuck in a specific experience (not progressing)",
+    "Find customers who started a journey but stopped progressing. Useful for identifying users who need help completing onboarding, checkout, or other flows.",
     {
       experienceId: z.string().describe("The experience ID or slug"),
       limit: z.number().optional().describe("Maximum number of results (default: 20, max: 100)")
@@ -355,10 +748,7 @@ Avg Time to Complete: ${avgTimeDisplay}`
         if (limit) params.set("limit", String(limit));
         const url = `${config.baseUrl}/api/vendor/experiences/${experienceId}/stuck${params.toString() ? "?" + params.toString() : ""}`;
         const response = await fetch(url, {
-          headers: {
-            "X-API-Key": config.apiKey,
-            "Content-Type": "application/json"
-          }
+          headers: getApiHeaders(config.apiKey)
         });
         if (!response.ok) {
           return {
@@ -371,7 +761,8 @@ Avg Time to Complete: ${avgTimeDisplay}`
             isError: true
           };
         }
-        const data = await response.json();
+        const rawData = await response.json();
+        const data = unwrapApiResponse(rawData);
         const customers = data.stuckCustomers || [];
         const exp = data.experience || {};
         if (customers.length === 0) {
@@ -431,10 +822,7 @@ ${customerList}${customers.length > 10 ? `
         if (sortBy) params.set("sortBy", sortBy);
         const url = `${config.baseUrl}/api/vendor/customers/at-risk${params.toString() ? "?" + params.toString() : ""}`;
         const response = await fetch(url, {
-          headers: {
-            "X-API-Key": config.apiKey,
-            "Content-Type": "application/json"
-          }
+          headers: getApiHeaders(config.apiKey)
         });
         if (!response.ok) {
           return {
@@ -447,7 +835,8 @@ ${customerList}${customers.length > 10 ? `
             isError: true
           };
         }
-        const data = await response.json();
+        const rawData = await response.json();
+        const data = unwrapApiResponse(rawData);
         const accounts = data.accounts || [];
         const summary = data.summary || {};
         if (accounts.length === 0) {
@@ -493,6 +882,218 @@ ${accountList}${accounts.length > 15 ? `
       }
     }
   );
+  server.tool(
+    "get_sdk_config",
+    "Get your FirstDistro installation token and SDK configuration snippets for setting up the SDK in your project.",
+    async () => {
+      try {
+        const response = await fetch(`${config.baseUrl}/api/vendor/sdk-config`, {
+          headers: getApiHeaders(config.apiKey)
+        });
+        if (!response.ok) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: formatHttpError(response.status, response.statusText, "SDK config")
+              }
+            ],
+            isError: true
+          };
+        }
+        const rawData = await response.json();
+        const result = unwrapApiResponse(rawData);
+        const snippets = result.snippets || {};
+        return {
+          content: [
+            {
+              type: "text",
+              text: `FirstDistro SDK Configuration
+
+Installation Token: ${result.installationToken}
+Vendor: ${result.vendorName || result.vendorSlug}
+
+Quick Start:
+1. Install: ${snippets.install || "npm install @firstdistro/sdk"}
+
+2. Add the provider to your app:
+   ${snippets.providerImport || "import { FirstDistroProvider } from '@firstdistro/sdk/react'"}
+   ${snippets.providerJsx || `<FirstDistroProvider token="${result.installationToken}">{children}</FirstDistroProvider>`}
+
+3. Identify users (after login):
+   ${snippets.setupHook || "import { useFirstDistroSetup } from '@firstdistro/sdk/react'"}
+   ${snippets.setupCall || "useFirstDistroSetup({ userId: user.id, userEmail: user.email })"}
+
+4. Track custom events:
+   ${snippets.trackCall || "FirstDistro.track('event_name', { property: 'value' })"}
+
+After setup, use 'check_events_flowing' to verify events are being received.`
+            }
+          ]
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: formatNetworkError(error)
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+  server.tool(
+    "setup_sdk",
+    "Generate all files and commands needed to set up the FirstDistro SDK in your project. Returns framework-specific setup files, install commands, and verification steps.",
+    {
+      framework: z.enum(["nextjs-app", "nextjs-pages", "react-vite", "react-cra", "vanilla"]).describe(
+        'Target framework. Use "nextjs-app" for Next.js 13+ with app directory, "react-vite" for React + Vite projects.'
+      ),
+      includeUserSetup: z.boolean().optional().describe("Include user identification code for tracking logged-in users (default: true)"),
+      authPattern: z.enum(["nextauth", "clerk", "supabase", "custom", "none"]).optional().describe("Auth library in use. Generates appropriate user setup code for the auth pattern.")
+    },
+    async ({ framework, includeUserSetup, authPattern }) => {
+      try {
+        const response = await fetch(`${config.baseUrl}/api/vendor/sdk-config`, {
+          headers: getApiHeaders(config.apiKey)
+        });
+        if (!response.ok) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: formatHttpError(response.status, response.statusText, "SDK config")
+              }
+            ],
+            isError: true
+          };
+        }
+        const rawData = await response.json();
+        const data = unwrapApiResponse(rawData);
+        const installationToken = data.installationToken;
+        if (!installationToken) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Could not retrieve installation token. Please check your API key and try again."
+              }
+            ],
+            isError: true
+          };
+        }
+        const result = generateSetupResult(framework, installationToken, {
+          includeUserSetup: includeUserSetup ?? true,
+          authPattern: authPattern || "none"
+        });
+        const filesOutput = result.files.map((file) => {
+          if (file.action === "create") {
+            return `### ${file.path} (CREATE)
+${file.description}
+
+\`\`\`tsx
+${file.content}
+\`\`\``;
+          } else {
+            return `### ${file.path} (MODIFY)
+${file.description}
+${file.replace ? `
+Find this code:
+\`\`\`
+${file.replace.old}
+\`\`\`
+
+Replace with:
+\`\`\`tsx
+${file.replace.new}
+\`\`\`
+` : ""}`;
+          }
+        }).join("\n\n");
+        const commandsOutput = result.commands.map((cmd) => `- \`${cmd.run}\` \u2014 ${cmd.description}`).join("\n");
+        const nextStepsOutput = result.nextSteps.map((step) => `- ${step}`).join("\n");
+        return {
+          content: [
+            {
+              type: "text",
+              text: `# FirstDistro SDK Setup for ${getFrameworkDisplayName(framework)}
+
+## Installation Token
+\`${result.installationToken}\`
+
+## Commands to Run
+${commandsOutput}
+
+## Files to Create/Modify
+
+${filesOutput}
+
+## Verification
+After setup, use the \`${result.verification.tool}\` tool to verify:
+- Success: ${result.verification.successMessage}
+- If not working: ${result.verification.failureHint}
+
+## Next Steps
+${nextStepsOutput}`
+            }
+          ]
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: formatNetworkError(error)
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+}
+function registerUnconfiguredTools(server, configError = null) {
+  const message = configError ? `FirstDistro configuration error:
+
+${configError}
+
+To fix this, run:
+   npx @firstdistro/mcp init --api-key YOUR_KEY
+
+Then restart your IDE.` : `FirstDistro is not configured yet.
+
+To get started:
+
+1. Sign up at https://firstdistro.com/auth/register
+
+2. Get your API key from Settings \u2192 API Keys
+
+3. Configure MCP:
+   npx @firstdistro/mcp init --api-key YOUR_KEY
+
+Then restart your IDE to use FirstDistro tools.`;
+  const placeholderTools = [
+    { name: "list_experiences", description: "List all user journeys/funnels you're tracking" },
+    { name: "check_events_flowing", description: "Check if events are being received" },
+    { name: "get_customer_health", description: "Get health score for a customer" },
+    { name: "get_experience_stats", description: "Get funnel statistics for a user journey" },
+    { name: "get_stuck_customers", description: "Find customers who stopped progressing in a journey" },
+    { name: "list_at_risk_accounts", description: "List at-risk customer accounts" },
+    { name: "get_sdk_config", description: "Get your installation token and SDK setup code" },
+    { name: "setup_sdk", description: "Generate files to set up FirstDistro SDK in your project" }
+  ];
+  for (const tool of placeholderTools) {
+    server.tool(tool.name, tool.description, async () => ({
+      content: [
+        {
+          type: "text",
+          text: message
+        }
+      ]
+    }));
+  }
 }
 export {
   startServer

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@firstdistro/mcp",
-  "version": "1.0.0",
-  "description": "MCP server for FirstDistro - query and manage customer health from AI assistants",
+  "version": "1.1.1",
+  "description": "MCP server that brings customer health scores, stuck users, and funnel analytics into Claude, Cursor, and other AI tools — catch churn risks early",
   "type": "module",
   "bin": {
     "firstdistro-mcp": "./bin/firstdistro-mcp.js"