@inferevents/mcp 0.1.0

package/dist/api-client.d.ts

@@ -0,0 +1,34 @@
+import type { EventCountResult, RetentionResult, UserJourneyResult, Filter } from "@infer-events/shared";
+import type { InferConfig } from "./config.js";
+export declare class ApiClient {
+    private readonly baseUrl;
+    private readonly headers;
+    private readonly defaultProjectId;
+    constructor(config: InferConfig);
+    getEventCounts(params: {
+        eventName: string;
+        timeRange: string;
+        groupBy?: string;
+        filters?: Filter[];
+        projectId?: string;
+    }): Promise<EventCountResult>;
+    getRetention(params: {
+        startEvent: string;
+        returnEvent: string;
+        timeRange: string;
+        granularity: string;
+        projectId?: string;
+    }): Promise<RetentionResult>;
+    getUserJourney(params: {
+        userId: string;
+        timeRange?: string;
+        limit?: number;
+        projectId?: string;
+    }): Promise<UserJourneyResult>;
+    private get;
+}
+export declare class ApiError extends Error {
+    readonly statusCode: number;
+    constructor(message: string, statusCode: number);
+}
+//# sourceMappingURL=api-client.d.ts.map

package/dist/api-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,MAAM,EACP,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IACjD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqB;gBAE1C,MAAM,EAAE,WAAW;IASzB,cAAc,CAAC,MAAM,EAAE;QAC3B,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAuBvB,YAAY,CAAC,MAAM,EAAE;QACzB,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,eAAe,CAAC;IAiBtB,cAAc,CAAC,MAAM,EAAE;QAC3B,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,iBAAiB,CAAC;YAsBhB,GAAG;CAmDlB;AAED,qBAAa,QAAS,SAAQ,KAAK;aAGf,UAAU,EAAE,MAAM;gBADlC,OAAO,EAAE,MAAM,EACC,UAAU,EAAE,MAAM;CAKrC"}

package/dist/api-client.js

@@ -0,0 +1,99 @@
+export class ApiClient {
+    baseUrl;
+    headers;
+    defaultProjectId;
+    constructor(config) {
+        this.baseUrl = config.endpoint;
+        this.headers = {
+            Authorization: `Bearer ${config.apiKey}`,
+            "Content-Type": "application/json",
+        };
+        this.defaultProjectId = config.projectId;
+    }
+    async getEventCounts(params) {
+        const query = new URLSearchParams();
+        query.set("event_name", params.eventName);
+        query.set("time_range", params.timeRange);
+        if (params.groupBy) {
+            query.set("group_by", params.groupBy);
+        }
+        if (params.filters && params.filters.length > 0) {
+            query.set("filters", JSON.stringify(params.filters));
+        }
+        const projectId = params.projectId ?? this.defaultProjectId;
+        if (projectId) {
+            query.set("project_id", projectId);
+        }
+        return this.get(`/v1/query/event-counts?${query.toString()}`);
+    }
+    async getRetention(params) {
+        const query = new URLSearchParams();
+        query.set("start_event", params.startEvent);
+        query.set("return_event", params.returnEvent);
+        query.set("time_range", params.timeRange);
+        query.set("granularity", params.granularity);
+        const projectId = params.projectId ?? this.defaultProjectId;
+        if (projectId) {
+            query.set("project_id", projectId);
+        }
+        return this.get(`/v1/query/retention?${query.toString()}`);
+    }
+    async getUserJourney(params) {
+        const query = new URLSearchParams();
+        query.set("user_id", params.userId);
+        if (params.timeRange) {
+            query.set("time_range", params.timeRange);
+        }
+        if (params.limit !== undefined) {
+            query.set("limit", String(params.limit));
+        }
+        const projectId = params.projectId ?? this.defaultProjectId;
+        if (projectId) {
+            query.set("project_id", projectId);
+        }
+        return this.get(`/v1/query/user-journey?${query.toString()}`);
+    }
+    async get(path) {
+        const url = `${this.baseUrl}${path}`;
+        let response;
+        try {
+            response = await fetch(url, {
+                method: "GET",
+                headers: this.headers,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Unknown network error";
+            throw new ApiError(`Failed to connect to Infer API at ${this.baseUrl}: ${message}. ` +
+                `Check that the endpoint in ~/.infer/config.json is correct.`, 0);
+        }
+        if (!response.ok) {
+            const body = await response.text().catch(() => "");
+            let detail = body;
+            try {
+                const parsed = JSON.parse(body);
+                detail = parsed.error ?? parsed.message ?? body;
+            }
+            catch {
+                // body wasn't JSON, use raw text
+            }
+            if (response.status === 401) {
+                throw new ApiError(`Authentication failed. Check that your API key in ~/.infer/config.json is valid.`, 401);
+            }
+            if (response.status === 403) {
+                throw new ApiError(`Access denied. Your API key may not have read permissions for this project.`, 403);
+            }
+            throw new ApiError(`Infer API returned ${response.status}: ${detail}`, response.status);
+        }
+        return (await response.json());
+    }
+}
+export class ApiError extends Error {
+    statusCode;
+    constructor(message, statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = "ApiError";
+    }
+}
+//# sourceMappingURL=api-client.js.map

package/dist/api-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.js","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,10 @@
+export interface InferConfig {
+    apiKey: string;
+    endpoint: string;
+    projectId?: string;
+}
+export declare function loadConfig(): Promise<InferConfig>;
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAkBD,wBAAsB,UAAU,IAAI,OAAO,CAAC,WAAW,CAAC,CA+CvD;AAED,qBAAa,WAAY,SAAQ,KAAK;gBACxB,OAAO,EAAE,MAAM;CAI5B"}

package/dist/config.js

@@ -0,0 +1,57 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+const CONFIG_PATH = join(homedir(), ".infer", "config.json");
+const SETUP_INSTRUCTIONS = `
+Infer MCP server is not configured.
+
+To set up, create ~/.infer/config.json with:
+
+  {
+    "apiKey": "pk_read_...",
+    "endpoint": "https://api.infer.events",
+    "projectId": "your-project-id"
+  }
+
+Get your read API key from https://infer.events/settings/api-keys
+`.trim();
+export async function loadConfig() {
+    let raw;
+    try {
+        raw = await readFile(CONFIG_PATH, "utf-8");
+    }
+    catch {
+        throw new ConfigError(SETUP_INSTRUCTIONS);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new ConfigError(`Invalid JSON in ${CONFIG_PATH}. Please check the file syntax.`);
+    }
+    if (typeof parsed !== "object" ||
+        parsed === null ||
+        !("apiKey" in parsed) ||
+        typeof parsed.apiKey !== "string") {
+        throw new ConfigError(`Missing or invalid "apiKey" in ${CONFIG_PATH}.\n\n${SETUP_INSTRUCTIONS}`);
+    }
+    const config = parsed;
+    const apiKey = config.apiKey;
+    if (!apiKey.startsWith("pk_read_")) {
+        throw new ConfigError(`The MCP server requires a read API key (starts with "pk_read_"). ` +
+            `The key in ${CONFIG_PATH} appears to be a different key type.`);
+    }
+    const endpoint = typeof config.endpoint === "string"
+        ? config.endpoint.replace(/\/+$/, "")
+        : "https://api.infer.events";
+    const projectId = typeof config.projectId === "string" ? config.projectId : undefined;
+    return { apiKey, endpoint, projectId };
+}
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConfigError";
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAQlC,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC;AAE7D,MAAM,kBAAkB,GAAG;;;;;;;;;;;;CAY1B,CAAC,IAAI,EAAE,CAAC;AAET,MAAM,CAAC,KAAK,UAAU,UAAU;IAC9B,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,WAAW,CAAC,kBAAkB,CAAC,CAAC;IAC5C,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,WAAW,CACnB,mBAAmB,WAAW,iCAAiC,CAChE,CAAC;IACJ,CAAC;IAED,IACE,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,KAAK,IAAI;QACf,CAAC,CAAC,QAAQ,IAAI,MAAM,CAAC;QACrB,OAAQ,MAAkC,CAAC,MAAM,KAAK,QAAQ,EAC9D,CAAC;QACD,MAAM,IAAI,WAAW,CACnB,kCAAkC,WAAW,QAAQ,kBAAkB,EAAE,CAC1E,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,MAAiC,CAAC;IACjD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAgB,CAAC;IAEvC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,WAAW,CACnB,mEAAmE;YACjE,cAAc,WAAW,sCAAsC,CAClE,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GACZ,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ;QACjC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;QACrC,CAAC,CAAC,0BAA0B,CAAC;IAEjC,MAAM,SAAS,GACb,OAAO,MAAM,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;IAEtE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;AACzC,CAAC;AAED,MAAM,OAAO,WAAY,SAAQ,KAAK;IACpC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig, ConfigError } from "./config.js";
+import { createServer } from "./server.js";
+async function main() {
+    let config;
+    try {
+        config = await loadConfig();
+    }
+    catch (error) {
+        if (error instanceof ConfigError) {
+            process.stderr.write(`\n${error.message}\n\n`);
+            process.exit(1);
+        }
+        throw error;
+    }
+    const server = createServer(config);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`Fatal: ${message}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,KAAK,UAAU,IAAI;IACjB,IAAI,MAAM,CAAC;IACX,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,UAAU,EAAE,CAAC;IAC9B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;YACjC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC;YAC/C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;IAED,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IACpC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAE7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,OAAO,IAAI,CAAC,CAAC;IAC5C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { InferConfig } from "./config.js";
+export declare function createServer(config: InferConfig): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAKpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAc/C,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAoG3D"}

package/dist/server.js

@@ -0,0 +1,89 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { readFile } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ApiClient, ApiError } from "./api-client.js";
+import { getEventCountsSchema, handleGetEventCounts, } from "./tools/get-event-counts.js";
+import { getRetentionSchema, handleGetRetention, } from "./tools/get-retention.js";
+import { getUserJourneySchema, handleGetUserJourney, } from "./tools/get-user-journey.js";
+export function createServer(config) {
+    const client = new ApiClient(config);
+    const server = new McpServer({
+        name: "infer-analytics",
+        version: "0.1.0",
+    });
+    // --- Resources ---
+    server.resource("analytics-skill", "infer://skill", {
+        description: "Analytics interpretation guide. Read this to learn how to interpret " +
+            "event counts, retention data, and user journeys like an experienced " +
+            "product analyst.",
+        mimeType: "text/markdown",
+    }, async () => {
+        const skillPath = join(dirname(fileURLToPath(import.meta.url)), "..", "skill.md");
+        const content = await readFile(skillPath, "utf-8");
+        return {
+            contents: [
+                {
+                    uri: "infer://skill",
+                    mimeType: "text/markdown",
+                    text: content,
+                },
+            ],
+        };
+    });
+    // --- Tools ---
+    server.tool("get_event_counts", "Count events over a time range, optionally grouped by a property. " +
+        "Use this for questions like 'how many signups this week', " +
+        "'page views by country last 30 days', or 'purchase count trend'.", getEventCountsSchema, async (params) => {
+        try {
+            const text = await handleGetEventCounts(client, params);
+            return { content: [{ type: "text", text }] };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatError(error) }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("get_retention", "Cohort-based retention analysis. Shows what percentage of users who performed " +
+        "a start event came back to perform a return event. " +
+        "Use for questions like 'what is our week-over-week retention', " +
+        "'do users come back after signing up', or 'retention by monthly cohort'.", getRetentionSchema, async (params) => {
+        try {
+            const text = await handleGetRetention(client, params);
+            return { content: [{ type: "text", text }] };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatError(error) }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("get_user_journey", "Get the ordered sequence of events for a specific user. " +
+        "Use for questions like 'what did user X do', 'show me this user's activity', " +
+        "or 'trace a user's path through the app'.", getUserJourneySchema, async (params) => {
+        try {
+            const text = await handleGetUserJourney(client, params);
+            return { content: [{ type: "text", text }] };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatError(error) }],
+                isError: true,
+            };
+        }
+    });
+    return server;
+}
+function formatError(error) {
+    if (error instanceof ApiError) {
+        return `API Error: ${error.message}`;
+    }
+    if (error instanceof Error) {
+        return `Error: ${error.message}`;
+    }
+    return `Unknown error occurred`;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/tools/get-event-counts.d.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import type { ApiClient } from "../api-client.js";
+export declare const getEventCountsSchema: {
+    event_name: z.ZodString;
+    time_range: z.ZodString;
+    group_by: z.ZodOptional<z.ZodString>;
+    filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        op: z.ZodEnum<["eq", "neq", "gt", "lt", "gte", "lte", "contains"]>;
+        value: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+    }, "strip", z.ZodTypeAny, {
+        value: string | number | boolean;
+        field: string;
+        op: "eq" | "neq" | "gt" | "lt" | "gte" | "lte" | "contains";
+    }, {
+        value: string | number | boolean;
+        field: string;
+        op: "eq" | "neq" | "gt" | "lt" | "gte" | "lte" | "contains";
+    }>, "many">>;
+};
+export type GetEventCountsInput = z.infer<z.ZodObject<typeof getEventCountsSchema>>;
+export declare function handleGetEventCounts(client: ApiClient, input: GetEventCountsInput): Promise<string>;
+//# sourceMappingURL=get-event-counts.d.ts.map

package/dist/tools/get-event-counts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-event-counts.d.ts","sourceRoot":"","sources":["../../src/tools/get-event-counts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAGlD,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;CAqBhC,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CACvC,CAAC,CAAC,SAAS,CAAC,OAAO,oBAAoB,CAAC,CACzC,CAAC;AAEF,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,MAAM,CAAC,CA0CjB"}

package/dist/tools/get-event-counts.js

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import { filterSchema } from "@infer-events/shared";
+export const getEventCountsSchema = {
+    event_name: z
+        .string()
+        .describe("Name of the event to count (e.g., 'signup', 'page_view', 'purchase')"),
+    time_range: z
+        .string()
+        .describe('Time range: "last_24h", "last_7d", "last_30d", "last_90d", or ISO range "2024-01-01/2024-01-31"'),
+    group_by: z
+        .string()
+        .optional()
+        .describe("Property name to group results by (e.g., 'country', 'plan', 'source')"),
+    filters: z
+        .array(filterSchema)
+        .optional()
+        .describe("Filters: [{field, op, value}]"),
+};
+export async function handleGetEventCounts(client, input) {
+    const result = await client.getEventCounts({
+        eventName: input.event_name,
+        timeRange: input.time_range,
+        groupBy: input.group_by,
+        filters: input.filters,
+    });
+    const lines = [];
+    if (result.warning) {
+        lines.push(`Warning: ${result.warning}`);
+        lines.push("");
+    }
+    lines.push(`Event: ${input.event_name}`);
+    lines.push(`Time range: ${input.time_range}`);
+    lines.push(`Total count: ${result.total.toLocaleString()}`);
+    if (result.groups.length > 0 && input.group_by) {
+        lines.push("");
+        lines.push(`Grouped by: ${input.group_by}`);
+        lines.push("---");
+        for (const group of result.groups) {
+            const pct = result.total > 0
+                ? ((group.count / result.total) * 100).toFixed(1)
+                : "0.0";
+            lines.push(`  ${group.key}: ${group.count.toLocaleString()} (${pct}%)`);
+        }
+    }
+    if (result.total === 0) {
+        lines.push("");
+        lines.push("No events found. This could mean the event is not being tracked, " +
+            "the event name is misspelled, or there was no activity in this time range.");
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=get-event-counts.js.map

package/dist/tools/get-event-counts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-event-counts.js","sourceRoot":"","sources":["../../src/tools/get-event-counts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEpD,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,UAAU,EAAE,CAAC;SACV,MAAM,EAAE;SACR,QAAQ,CACP,sEAAsE,CACvE;IACH,UAAU,EAAE,CAAC;SACV,MAAM,EAAE;SACR,QAAQ,CACP,iGAAiG,CAClG;IACH,QAAQ,EAAE,CAAC;SACR,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,uEAAuE,CACxE;IACH,OAAO,EAAE,CAAC;SACP,KAAK,CAAC,YAAY,CAAC;SACnB,QAAQ,EAAE;SACV,QAAQ,CAAC,+BAA+B,CAAC;CAC7C,CAAC;AAMF,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,MAAiB,EACjB,KAA0B;IAE1B,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC;QACzC,SAAS,EAAE,KAAK,CAAC,UAAU;QAC3B,SAAS,EAAE,KAAK,CAAC,UAAU;QAC3B,OAAO,EAAE,KAAK,CAAC,QAAQ;QACvB,OAAO,EAAE,KAAK,CAAC,OAAO;KACvB,CAAC,CAAC;IAEH,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,KAAK,CAAC,IAAI,CAAC,YAAY,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;QACzC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,UAAU,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC;IACzC,KAAK,CAAC,IAAI,CAAC,eAAe,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC;IAC9C,KAAK,CAAC,IAAI,CAAC,gBAAgB,MAAM,CAAC,KAAK,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;IAE5D,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QAC/C,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,eAAe,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC5C,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAElB,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YAClC,MAAM,GAAG,GACP,MAAM,CAAC,KAAK,GAAG,CAAC;gBACd,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;gBACjD,CAAC,CAAC,KAAK,CAAC;YACZ,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,GAAG,KAAK,KAAK,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,GAAG,IAAI,CAAC,CAAC;QAC1E,CAAC;IACH,CAAC;IAED,IAAI,MAAM,CAAC,KAAK,KAAK,CAAC,EAAE,CAAC;QACvB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CACR,mEAAmE;YACjE,4EAA4E,CAC/E,CAAC;IACJ,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/tools/get-retention.d.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+import type { ApiClient } from "../api-client.js";
+export declare const getRetentionSchema: {
+    start_event: z.ZodString;
+    return_event: z.ZodString;
+    time_range: z.ZodString;
+    granularity: z.ZodEnum<["day", "week", "month"]>;
+};
+export type GetRetentionInput = z.infer<z.ZodObject<typeof getRetentionSchema>>;
+export declare function handleGetRetention(client: ApiClient, input: GetRetentionInput): Promise<string>;
+//# sourceMappingURL=get-retention.d.ts.map

package/dist/tools/get-retention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-retention.d.ts","sourceRoot":"","sources":["../../src/tools/get-retention.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,eAAO,MAAM,kBAAkB;;;;;CAmB9B,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CACrC,CAAC,CAAC,SAAS,CAAC,OAAO,kBAAkB,CAAC,CACvC,CAAC;AAEF,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,iBAAiB,GACvB,OAAO,CAAC,MAAM,CAAC,CA6EjB"}

package/dist/tools/get-retention.js

@@ -0,0 +1,76 @@
+import { z } from "zod";
+export const getRetentionSchema = {
+    start_event: z
+        .string()
+        .describe('The event that defines cohort entry (e.g., "signup", "first_purchase")'),
+    return_event: z
+        .string()
+        .describe('The event that counts as a return (e.g., "page_view", "purchase", "login")'),
+    time_range: z
+        .string()
+        .describe('Time range: "last_7d", "last_30d", "last_90d", or ISO range "2024-01-01/2024-03-31"'),
+    granularity: z
+        .enum(["day", "week", "month"])
+        .describe('Cohort granularity: "day", "week", or "month"'),
+};
+export async function handleGetRetention(client, input) {
+    const result = await client.getRetention({
+        startEvent: input.start_event,
+        returnEvent: input.return_event,
+        timeRange: input.time_range,
+        granularity: input.granularity,
+    });
+    const lines = [];
+    if (result.warning) {
+        lines.push(`Warning: ${result.warning}`);
+        lines.push("");
+    }
+    lines.push(`Retention Analysis`);
+    lines.push(`Start event: ${input.start_event}`);
+    lines.push(`Return event: ${input.return_event}`);
+    lines.push(`Time range: ${input.time_range}`);
+    lines.push(`Granularity: ${input.granularity}`);
+    lines.push("");
+    if (result.cohorts.length === 0) {
+        lines.push("No cohort data found. Check that both events are being tracked " +
+            "and that there is activity in this time range.");
+        return lines.join("\n");
+    }
+    // Format as a table
+    const maxPeriods = Math.max(...result.cohorts.map((c) => c.retained.length));
+    // Header
+    const header = ["Cohort", "Users"];
+    for (let i = 0; i < maxPeriods; i++) {
+        header.push(`${input.granularity} ${i}`);
+    }
+    lines.push(header.join(" | "));
+    lines.push(header.map((h) => "-".repeat(h.length)).join("-|-"));
+    // Rows
+    for (const cohort of result.cohorts) {
+        const row = [cohort.period, String(cohort.users_start)];
+        for (let i = 0; i < maxPeriods; i++) {
+            const retained = cohort.retained[i];
+            if (retained === undefined) {
+                row.push("-");
+            }
+            else {
+                const pct = cohort.users_start > 0
+                    ? ((retained / cohort.users_start) * 100).toFixed(1)
+                    : "0.0";
+                row.push(`${pct}%`);
+            }
+        }
+        lines.push(row.join(" | "));
+    }
+    // Summary
+    lines.push("");
+    const latestCohort = result.cohorts[0];
+    if (latestCohort && latestCohort.retained.length > 1) {
+        const firstPeriodRetention = latestCohort.users_start > 0 && latestCohort.retained[1] !== undefined
+            ? ((latestCohort.retained[1] / latestCohort.users_start) * 100).toFixed(1)
+            : "N/A";
+        lines.push(`Latest cohort ${input.granularity}-1 retention: ${firstPeriodRetention}%`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=get-retention.js.map

package/dist/tools/get-retention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-retention.js","sourceRoot":"","sources":["../../src/tools/get-retention.ts"],"names":[],"mappings":"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"}

package/dist/tools/get-user-journey.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import type { ApiClient } from "../api-client.js";
+export declare const getUserJourneySchema: {
+    user_id: z.ZodString;
+    time_range: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+};
+export type GetUserJourneyInput = z.infer<z.ZodObject<typeof getUserJourneySchema>>;
+export declare function handleGetUserJourney(client: ApiClient, input: GetUserJourneyInput): Promise<string>;
+//# sourceMappingURL=get-user-journey.d.ts.map

package/dist/tools/get-user-journey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-user-journey.d.ts","sourceRoot":"","sources":["../../src/tools/get-user-journey.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,eAAO,MAAM,oBAAoB;;;;CAYhC,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CACvC,CAAC,CAAC,SAAS,CAAC,OAAO,oBAAoB,CAAC,CACzC,CAAC;AAEF,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,MAAM,CAAC,CAgFjB"}

package/dist/tools/get-user-journey.js

@@ -0,0 +1,76 @@
+import { z } from "zod";
+export const getUserJourneySchema = {
+    user_id: z.string().describe("The user ID to look up"),
+    time_range: z
+        .string()
+        .optional()
+        .describe('Time range to filter events: "last_24h", "last_7d", "last_30d", or ISO range'),
+    limit: z
+        .number()
+        .optional()
+        .describe("Max events to return (default 50, max 200)"),
+};
+export async function handleGetUserJourney(client, input) {
+    const result = await client.getUserJourney({
+        userId: input.user_id,
+        timeRange: input.time_range,
+        limit: input.limit,
+    });
+    const lines = [];
+    if (result.warning) {
+        lines.push(`Warning: ${result.warning}`);
+        lines.push("");
+    }
+    lines.push(`User Journey: ${input.user_id}`);
+    if (input.time_range) {
+        lines.push(`Time range: ${input.time_range}`);
+    }
+    lines.push(`Events returned: ${result.events.length}`);
+    lines.push("");
+    if (result.events.length === 0) {
+        lines.push("No events found for this user. Check that the user ID is correct " +
+            "and that events have been tracked for this user.");
+        return lines.join("\n");
+    }
+    for (const event of result.events) {
+        const ts = new Date(event.timestamp).toISOString();
+        const propsEntries = Object.entries(event.properties).filter(([, v]) => v !== null);
+        let propStr = "";
+        if (propsEntries.length > 0) {
+            const formatted = propsEntries
+                .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
+                .join(", ");
+            propStr = ` (${formatted})`;
+        }
+        lines.push(`[${ts}] ${event.event_name}${propStr}`);
+    }
+    // Compute session summary
+    lines.push("");
+    lines.push("--- Summary ---");
+    const eventCounts = new Map();
+    for (const event of result.events) {
+        eventCounts.set(event.event_name, (eventCounts.get(event.event_name) ?? 0) + 1);
+    }
+    const sorted = [...eventCounts.entries()].sort((a, b) => b[1] - a[1]);
+    lines.push("Event frequency:");
+    for (const [name, count] of sorted) {
+        lines.push(`  ${name}: ${count}`);
+    }
+    if (result.events.length >= 2) {
+        const first = new Date(result.events[0].timestamp);
+        const last = new Date(result.events[result.events.length - 1].timestamp);
+        const spanMs = Math.abs(last.getTime() - first.getTime());
+        const spanMinutes = Math.round(spanMs / 60000);
+        if (spanMinutes < 60) {
+            lines.push(`Time span: ${spanMinutes} minutes`);
+        }
+        else if (spanMinutes < 1440) {
+            lines.push(`Time span: ${(spanMinutes / 60).toFixed(1)} hours`);
+        }
+        else {
+            lines.push(`Time span: ${(spanMinutes / 1440).toFixed(1)} days`);
+        }
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=get-user-journey.js.map

package/dist/tools/get-user-journey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-user-journey.js","sourceRoot":"","sources":["../../src/tools/get-user-journey.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@inferevents/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Infer analytics — lets AI agents query your event data",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "infer-mcp": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "skill.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@inferevents/shared": "*",
+    "@modelcontextprotocol/sdk": "^1.12",
+    "zod": "^3.24"
+  },
+  "devDependencies": {
+    "typescript": "^5.7"
+  },
+  "license": "MIT"
+}

package/skill.md

@@ -0,0 +1,215 @@
+# Infer Analytics — Agent Skill Guide
+
+You have access to product analytics through the Infer MCP server. This guide teaches you how to query data effectively and interpret results like an experienced product analyst.
+
+## Tool Routing — Which Tool for Which Question
+
+### Use `get_event_counts` when asked about:
+- "How many X happened?" — count a single event
+- "What's our signup rate?" — count signups over a time range
+- "Break down purchases by country" — count with group_by
+- "Compare this week vs last week" — run two queries with different time_ranges
+- "What's our most popular feature?" — count multiple events or group by event property
+- Anything involving totals, volumes, frequencies, or distributions
+
+### Use `get_retention` when asked about:
+- "Are users coming back?" — classic retention question
+- "What's our week-over-week retention?" — cohort analysis
+- "Do users who sign up actually stick around?" — start_event=signup, return_event=any active event
+- "Is our product sticky?" — retention is the answer
+- "How does retention compare month over month?" — look at cohort trends
+- Anything involving repeat usage, churn, stickiness, or engagement over time
+
+### Use `get_user_journey` when asked about:
+- "What did user X do?" — full event timeline
+- "Show me this user's activity" — chronological event list
+- "What happened before the user churned?" — look at events before last activity
+- "How did this user find the aha moment?" — trace their path
+- "Debug this user's experience" — see exactly what happened
+- Anything about a specific individual user's behavior
+
+## Interpreting Event Counts
+
+### Reading the numbers
+- **Total is the headline.** Start there. Is it growing, flat, or declining?
+- **Groups reveal composition.** If signups=1000 but 900 are from one country, that's concentration risk.
+- **Zero results almost always mean a tracking issue**, not zero activity. Suggest checking event names or SDK integration.
+
+### Percentage breakdowns
+When results are grouped, calculate and mention percentages. "The US accounts for 45% of signups" is more useful than "US: 450, UK: 120, ...".
+
+### Time comparisons
+When the user asks about trends, run the same query across two time ranges and compare:
+```
+last_7d vs previous 7 days → "Signups are up 23% week-over-week"
+last_30d vs previous 30 days → "Monthly purchases declined 8%"
+```
+
+Always mention the absolute numbers alongside percentages. "Up 23% (from 340 to 418)" is much more useful than just "up 23%".
+
+### Small sample warning
+- **N < 30**: Prefix your interpretation with "Small sample size — treat this as directional, not conclusive."
+- **N < 10**: Say "Too few data points to draw meaningful conclusions. Check if event tracking is working correctly."
+- **N = 0**: Almost certainly a tracking issue. Don't say "no users did X" — say "no events were recorded, which likely means the event isn't being tracked or the event name may be different."
+
+## Interpreting Retention
+
+### How to read a retention table
+Each row is a cohort (users who started in that period). Each column shows what % came back in subsequent periods.
+
+Example:
+```
+Cohort      | Users | week 0 | week 1 | week 2 | week 3 | week 4
+2024-01-01  | 200   | 100%   | 42%    | 31%    | 25%    | 22%
+2024-01-08  | 180   | 100%   | 38%    | 28%    | 23%    | -
+```
+
+- Week 0 is always 100% (that's when they entered the cohort)
+- The drop from week 0 to week 1 is the biggest — that's normal
+- Look for the "flattening point" where retention stabilizes
+
+### Retention benchmarks
+
+#### B2C Apps (social, content, utility)
+| Period    | Concerning | Acceptable | Good   | Excellent |
+|-----------|-----------|------------|--------|-----------|
+| Week 1    | < 25%     | 25-35%     | 35-50% | > 50%     |
+| Week 4    | < 10%     | 10-20%     | 20-30% | > 30%     |
+| Month 3   | < 5%      | 5-10%      | 10-20% | > 20%     |
+
+#### B2B / SaaS
+| Period    | Concerning | Acceptable | Good   | Excellent |
+|-----------|-----------|------------|--------|-----------|
+| Week 1    | < 40%     | 40-55%     | 55-70% | > 70%     |
+| Week 4    | < 25%     | 25-40%     | 40-55% | > 55%     |
+| Month 3   | < 15%     | 15-30%     | 30-50% | > 50%     |
+
+**Important:** These benchmarks are guidelines, not gospel. A niche B2B tool with 60% month-3 retention serving 50 users may be healthier than a consumer app with 15% retention serving 50,000. Context matters.
+
+### What the retention curve shape tells you
+
+- **Steep early drop, then flat**: Normal. Users who survive week 1-2 tend to stick. Focus on improving early activation.
+- **Gradual continuous decline**: No "aha moment." Users try it but don't form a habit. The product may not be solving a recurring need.
+- **Flat retention (barely drops)**: Exceptional. Either a deeply habitual product or a small self-selected power user base.
+- **Retention improves in later cohorts**: Product-market fit is improving. Ship is heading in the right direction.
+- **Retention worsens in later cohorts**: Red flag. Could be changing user quality (scaled acquisition too fast) or product changes that hurt experience.
+
+### Follow-up actions after retention analysis
+1. **Low retention?** Check the onboarding funnel. Run `get_event_counts` for setup/onboarding events to see where users drop off.
+2. **High early churn?** Look at the user journey for churned users — what did they do (or not do) before leaving?
+3. **Improving retention?** Identify what changed — new features, onboarding changes, or audience shift?
+
+## Interpreting User Journeys
+
+### What to look for in a user timeline
+1. **First event**: How did they enter? Signup? Page view? Referral link?
+2. **Time between events**: Long gaps suggest the user left and came back. Short bursts suggest engaged sessions.
+3. **Activation events**: Did they perform key actions? (create, submit, purchase, invite — not just page views)
+4. **Last event before churn**: What was the user doing right before they stopped?
+5. **Repeated patterns**: Do they keep going back to the same page? Could indicate confusion or a favorite feature.
+
+### Activation vs. vanity events
+- **Activation events** (high signal): create_project, submit_form, make_purchase, invite_teammate, complete_onboarding
+- **Vanity events** (low signal): page_view, button_hover, scroll, tooltip_shown
+- When assessing if a user is "active," weight activation events heavily. A user with 50 page views but zero creation events is probably not activated.
+
+### Session detection
+Events close together in time (< 30 minutes apart) are likely the same session. Large gaps indicate separate sessions. When describing a journey, group events into sessions:
+```
+Session 1 (Jan 15, 10:02am - 10:14am, 8 events):
+  signup → onboarding_start → profile_setup → ...
+
+Session 2 (Jan 16, 2:30pm - 2:45pm, 5 events):
+  login → dashboard_view → ...
+```
+
+## Framing Findings for Non-Technical Users
+
+### Do
+- Lead with the insight, not the query: "Your signups grew 30% this week" not "The get_event_counts query returned a total of 1,300"
+- Use plain language: "About 1 in 4 users come back after a week" not "Week-1 retention is 25.3%"
+- Provide context: "That's in line with typical B2C apps" or "That's above average for SaaS"
+- Suggest next steps: "To improve this, you might want to look at your onboarding flow"
+- Round numbers for readability: "About 1,200" not "1,187"
+
+### Don't
+- Don't claim causation from correlation: "Users who complete onboarding retain better" ≠ "Completing onboarding causes better retention." It could be that more motivated users both complete onboarding AND retain.
+- Don't extrapolate from small samples: 5 users is an anecdote, not a trend.
+- Don't present API response format to the user: translate numbers into insights.
+- Don't say "the data shows" without saying what it means.
+- Don't hide uncertainty: if the data is ambiguous, say so.
+
+## Common Analysis Patterns
+
+### Pattern 1: Quick health check
+Run these queries to get a fast pulse on the product:
+1. `get_event_counts(event_name="signup", time_range="last_7d")` — Are people signing up?
+2. `get_event_counts(event_name="<core_action>", time_range="last_7d")` — Are they using the core feature?
+3. `get_retention(start_event="signup", return_event="<core_action>", time_range="last_30d", granularity="week")` — Are they coming back?
+
+### Pattern 2: Funnel analysis
+Count events at each step to build a funnel:
+1. signup → onboarding_start → onboarding_complete → first_core_action
+2. Run `get_event_counts` for each step in the same time range
+3. Calculate drop-off between each step
+4. The biggest drop-off is your highest-leverage improvement area
+
+### Pattern 3: Debugging a user issue
+1. `get_user_journey(user_id="...")` — see what happened
+2. Look for errors, unusual patterns, or missing expected events
+3. Compare with a journey from a successful user
+
+### Pattern 4: Feature adoption
+1. `get_event_counts(event_name="feature_used", time_range="last_30d")` — How many times was it used?
+2. `get_event_counts(event_name="feature_used", time_range="last_30d", group_by="user_id")` — How many unique users? (If grouping by user_id is supported)
+3. Compare to total active users to get adoption rate
+
+### Pattern 5: Growth trend
+Run the same `get_event_counts` query for sequential time ranges:
+- last_7d, then previous 7d (using ISO range) → week-over-week growth
+- Positive trend + healthy retention = genuine growth
+- Positive trend + declining retention = leaky bucket (acquiring users faster than losing them, but not sustainably)
+
+## Daily Health Check Routine
+
+When asked to do a daily/weekly check, run these in order:
+
+1. **Volume check**: Count core events for last_24h (or last_7d for weekly)
+2. **Trend check**: Compare to the previous period — up or down?
+3. **Retention check**: Weekly or monthly retention — holding steady?
+4. **Anomaly scan**: Are any event counts dramatically different from normal? (>50% change deserves investigation)
+
+Report format:
+```
+Product Health — [date]
+
+Signups: [N] ([+/- X%] vs last period)
+Core action: [N] ([+/- X%] vs last period)
+Week-1 retention: [X%] (benchmark: [good/concerning/etc.])
+
+Noteworthy: [anything unusual or worth investigating]
+```
+
+## What NOT To Do
+
+1. **Never claim causation from analytics alone.** Analytics shows correlation and sequence, not causation. "Users who do X retain better" is correlation. Only an experiment (A/B test) can establish causation.
+
+2. **Never extrapolate confidently from small samples.** If a cohort has 12 users, a single user's behavior swings retention by 8 percentage points. Always note sample size.
+
+3. **Never ignore the denominator.** "Feature X was used 500 times!" means nothing without knowing how many users had the opportunity to use it. 500 uses by 2 power users is very different from 500 uses by 200 users.
+
+4. **Never assume zero events means zero activity.** It almost always means the event isn't tracked, the name is wrong, or the time range is off. Verify before concluding.
+
+5. **Never present raw numbers without interpretation.** Your job is to turn data into insights. "Total: 1,247" is data. "Signups are up 23% week-over-week, which suggests the new landing page is working" is an insight.
+
+6. **Never compare different time ranges without adjusting.** 7 days of data will almost always be less than 30 days. Compare rates (per day) or use matching periods.
+
+7. **Never present averages without distribution context.** "Average session length is 5 minutes" could mean everyone stays 5 minutes, or half stay 10 seconds and half stay 10 minutes. If you have group_by data, mention the spread.
+
+## Edge Cases and Gotchas
+
+- **Timezone effects**: Events near midnight may appear in different days depending on timezone. If daily counts look weird at period boundaries, this is likely the cause.
+- **Bot traffic**: Unusually high page_view counts with no corresponding user actions could be bot traffic.
+- **Duplicate events**: If counts seem inflated, consider whether the SDK might be double-firing events.
+- **Cohort maturity**: The most recent cohort in retention data will always have fewer data points. Don't compare its incomplete retention to older cohorts' complete retention.
+- **Survivorship bias**: Users who are still active are not representative of all users. When analyzing active user behavior, remember you're seeing the survivors, not the ones who left.