@apex-inc/mcp-server 0.1.0

package/dist/tools.js

@@ -0,0 +1,893 @@
+import { z } from "zod";
+import { apiGet, apiPost, apiPatch } from "./api-client.js";
+const APEX = "∧ Apex";
+export const toolDefinitions = {
+    plan_experiment: {
+        description: `${APEX} — PLANNING ONLY, does not create anything. Analyzes a goal against existing beliefs and experiments, then returns structured options for the user to choose from. After calling, you MUST present the returned options as a numbered list or poll and wait for the user to pick before calling any other Apex tools.`,
+        schema: z.object({
+            goal: z.string().describe("What the user wants to improve or test (e.g. 'improve signup conversion on landing page')"),
+            targetUrl: z.string().optional().describe("URL of the page to test, if known"),
+        }),
+        handler: async ({ goal, targetUrl }) => {
+            const [beliefs, experiments] = await Promise.all([
+                apiGet("/api/beliefs"),
+                apiGet("/api/experiments"),
+            ]);
+            const keywords = goal
+                .toLowerCase()
+                .replace(/[^a-z0-9\s]/g, "")
+                .split(/\s+/)
+                .filter((w) => w.length > 3);
+            const relatedBeliefs = beliefs.filter((b) => {
+                const words = b.statement.toLowerCase();
+                return keywords.some((kw) => words.includes(kw));
+            });
+            const relatedExperiments = experiments.filter((e) => {
+                const words = e.name.toLowerCase();
+                return keywords.some((kw) => words.includes(kw));
+            });
+            const plan = {
+                _apex: true,
+                goal,
+                targetUrl: targetUrl || null,
+                relatedBeliefs: relatedBeliefs.slice(0, 5).map((b) => ({
+                    id: b.id,
+                    statement: b.statement,
+                    confidence: Math.round(b.confidence * 100),
+                    tested: experiments.some((e) => e.beliefId === b.id),
+                })),
+                relatedExperiments: relatedExperiments.slice(0, 3).map((e) => ({
+                    id: e.id,
+                    name: e.name,
+                    status: e.status,
+                })),
+                suggestedBeliefs: [
+                    `Users who see [specific change] will convert at a higher rate`,
+                    `The current [element] is the primary friction point for [goal]`,
+                    `A clearer value proposition will reduce bounce rate`,
+                ],
+                suggestedMetrics: [
+                    "signup_conversion_rate",
+                    "bounce_rate",
+                    "click_through_rate",
+                    "time_on_page",
+                ],
+                suggestedConfidenceLevels: [
+                    { label: "Low (30%) — Gut feeling, no supporting data yet", value: 30 },
+                    { label: "Medium (55%) — Some signals, but hasn't been tested", value: 55 },
+                    { label: "High (75%) — Strong evidence from past experiments or data", value: 75 },
+                    { label: "Very High (90%) — Near-certain, well-established pattern", value: 90 },
+                ],
+                suggestedTrafficAllocations: [
+                    { label: "Adaptive (recommended) — Automatically shifts traffic toward the winning variant", control: 50, variant: 50, adaptive: true },
+                    { label: "Balanced 50/50 — Equal split, fastest to reach significance", control: 50, variant: 50, adaptive: false },
+                    { label: "Conservative 80/20 — Minimal exposure to variant, lower risk", control: 80, variant: 20, adaptive: false },
+                ],
+                _instructions: "IMPORTANT: Present each section as a numbered selection the user can pick from. Use a poll or numbered list for beliefs, confidence, metrics, and traffic split. Do NOT auto-fill any values.",
+            };
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(plan, null, 2),
+                    },
+                ],
+            };
+        },
+    },
+    start_reasoning: {
+        description: `${APEX} — Record a belief and hypothesis chain. Only call AFTER the user has picked a belief statement and confidence level from the options you presented.`,
+        schema: z.object({
+            decision: z.string().describe("What you want to improve or change"),
+            belief: z.string().describe("The assumption — must be confirmed by the user"),
+            confidence: z
+                .number()
+                .min(0)
+                .max(100)
+                .describe("How sure the user is about this assumption (0-100%) — must be chosen by the user"),
+        }),
+        handler: async ({ decision, belief, confidence }) => {
+            const b = await apiPost("/api/beliefs", {
+                statement: belief,
+                confidence: confidence / 100,
+            });
+            const hypothesis = `If we act on "${belief.slice(0, 80)}", then we should see a measurable improvement in our target metric.`;
+            const h = await apiPost("/api/hypotheses", {
+                beliefId: b.id,
+                statement: hypothesis,
+                predictedEffect: `Impact related to: ${decision.slice(0, 60)}`,
+                confidence: confidence / 100,
+                status: "active",
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `${APEX} Belief recorded`,
+                            ``,
+                            `  ID: ${b.id}`,
+                            `  Statement: "${b.statement}"`,
+                            `  Confidence: ${Math.round(b.confidence * 100)}%`,
+                            `  Hypothesis: ${h.id}`,
+                            ``,
+                            `Present the user with these next steps as selections:`,
+                            `  1. Log a prediction — how much impact do you expect?`,
+                            `  2. Design the experiment — what should we change?`,
+                            `  3. Adjust the belief — refine the assumption first`,
+                        ].join("\n"),
+                    },
+                ],
+            };
+        },
+    },
+    create_belief: {
+        description: `${APEX} — Record an assumption your team is making. Confirm the belief statement and confidence with the user before calling.`,
+        schema: z.object({
+            statement: z.string().describe("The assumption statement"),
+            confidence: z.number().min(0).max(100).describe("How sure you are (0-100%)"),
+            parentBeliefId: z.string().optional().describe("ID of a parent assumption, if this is a sub-assumption"),
+        }),
+        handler: async ({ statement, confidence, parentBeliefId }) => {
+            const b = await apiPost("/api/beliefs", {
+                statement,
+                confidence: confidence / 100,
+                parentBeliefId,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `${APEX} Assumption tracked [${b.id}]: "${b.statement}" at ${Math.round(b.confidence * 100)}% certainty.`,
+                    },
+                ],
+            };
+        },
+    },
+    create_experiment: {
+        description: `${APEX} — Create an experiment record. Returns a structured recipe for the AI agent to implement. The agent makes the actual code changes using useApexVariant hook — Apex never generates code. Always call with preview=true first so the user sees a summary.`,
+        schema: z.object({
+            name: z.string().describe("Experiment name"),
+            targetUrl: z.string().describe("URL of the page to test (include #anchor for section targeting)"),
+            controlContent: z.string().describe("The current content that the control shows"),
+            variantContent: z.string().describe("The new content for the variant"),
+            targetComponent: z.string().optional().describe("Component or file path where the change should be made"),
+            targetAnchor: z.string().optional().describe("Section anchor/ID on the page (e.g. 'pricing', 'hero')"),
+            trafficSplit: z.number().min(1).max(99).optional().describe("Percentage of traffic to control (default 50)"),
+            beliefId: z.string().optional().describe("ID of the assumption this tests"),
+            hypothesisId: z.string().optional().describe("ID of the expected outcome"),
+            predictionId: z.string().optional().describe("ID of the expected impact"),
+            mode: z.enum(["sdk", "snippet"]).optional().describe("Experiment mode: 'sdk' for code-level (default via MCP), 'snippet' for runtime DOM"),
+            preview: z.boolean().optional().describe("If true, returns a preview without creating. Default: true."),
+        }),
+        handler: async (args) => {
+            const split = args.trafficSplit ?? 50;
+            const mode = args.mode ?? "sdk";
+            const isPreview = args.preview !== false;
+            if (isPreview) {
+                const recipe = {
+                    _apex: true,
+                    _type: "experiment_preview",
+                    name: args.name,
+                    targetUrl: args.targetUrl,
+                    targetAnchor: args.targetAnchor || null,
+                    targetComponent: args.targetComponent || null,
+                    mode,
+                    trafficSplit: { control: split, variant: 100 - split },
+                    control: args.controlContent,
+                    variant: args.variantContent,
+                    beliefId: args.beliefId || null,
+                    predictionId: args.predictionId || null,
+                    _instructions: "Present this as a summary and ask the user to confirm (1), adjust (2), or cancel (3). Do NOT create the experiment until confirmed.",
+                };
+                return { content: [{ type: "text", text: JSON.stringify(recipe, null, 2) }] };
+            }
+            const exp = await apiPost("/api/experiments", {
+                name: args.name,
+                targetUrl: args.targetUrl,
+                trafficSplit: split,
+                beliefId: args.beliefId,
+                hypothesisId: args.hypothesisId,
+                predictionId: args.predictionId,
+                mode,
+                targetAnchor: args.targetAnchor,
+                variants: {
+                    control: { name: "Control", description: "Original content", changes: [] },
+                    variant_b: {
+                        name: "Variant B",
+                        description: "Modified content",
+                        changes: [
+                            {
+                                selector: "*",
+                                type: "text",
+                                value: args.variantContent,
+                                originalValue: args.controlContent,
+                            },
+                        ],
+                    },
+                },
+            });
+            let previewUrl = "";
+            try {
+                const vu = new URL(exp.targetUrl || args.targetUrl);
+                vu.searchParams.set("_apex_preview", "variant_b");
+                vu.searchParams.set("_apex_exp", exp.id);
+                if (args.targetAnchor)
+                    vu.hash = args.targetAnchor;
+                previewUrl = vu.toString();
+            }
+            catch { /* non-critical */ }
+            const recipe = {
+                _apex: true,
+                _type: "experiment_created",
+                experimentId: exp.id,
+                name: exp.name,
+                status: exp.status,
+                mode,
+                sdk: mode === "sdk" ? {
+                    hook: "useApexVariant",
+                    import: "@/lib/apex-sdk",
+                    experimentId: exp.id,
+                    targetComponent: args.targetComponent || null,
+                    targetAnchor: args.targetAnchor || null,
+                    control: args.controlContent,
+                    variant: args.variantContent,
+                } : null,
+                previewUrl,
+                trafficSplit: { control: split, variant: 100 - split },
+                _instructions: mode === "sdk"
+                    ? [
+                        "IMPLEMENT THE EXPERIMENT IN CODE:",
+                        `1. Open the target file${args.targetComponent ? ` (${args.targetComponent})` : ""}`,
+                        `2. Add: import { useApexVariant } from "@/lib/apex-sdk"`,
+                        `3. In the component, add: const variant = useApexVariant("${exp.id}")`,
+                        `4. Wrap the target content in a conditional:`,
+                        `   {variant === "variant_b" ? <VARIANT_CONTENT> : <CONTROL_CONTENT>}`,
+                        `5. Show the user the diff and ask them to preview at: ${previewUrl}`,
+                        `6. After preview approval, commit and push`,
+                        `7. Call track_deployment with the experiment ID and commit SHA`,
+                        `8. Call activate_experiment after deployment confirms`,
+                    ].join("\n")
+                    : [
+                        "SNIPPET MODE — no code changes needed.",
+                        "The experiment will be applied via the Apex snippet at runtime.",
+                        `Preview: ${previewUrl}`,
+                        "Ask the user to activate when ready.",
+                    ].join("\n"),
+            };
+            return { content: [{ type: "text", text: JSON.stringify(recipe, null, 2) }] };
+        },
+    },
+    activate_experiment: {
+        description: `${APEX} — Launch an experiment. Changes its status from draft to running. Traffic will be split immediately. Ask the user to confirm before calling.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID to activate"),
+        }),
+        handler: async ({ experimentId }) => {
+            const exp = await apiPatch("/api/experiments", {
+                id: experimentId,
+                status: "running",
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `${APEX} Experiment Launched`,
+                            `${"═".repeat(40)}`,
+                            ``,
+                            `  "${exp.name}" is now LIVE`,
+                            `  ID: ${exp.id}`,
+                            `  Traffic is being split ${exp.trafficSplit}% / ${100 - exp.trafficSplit}%`,
+                            ``,
+                            `  Visitors will now see either the control or variant.`,
+                            `  Results will appear in the dashboard and via get_results.`,
+                            ``,
+                            `${"═".repeat(40)}`,
+                        ].join("\n"),
+                    },
+                ],
+            };
+        },
+    },
+    pause_experiment: {
+        description: `${APEX} — Pause a running experiment. All visitors will see the control until resumed. Ask the user to confirm before calling.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID to pause"),
+        }),
+        handler: async ({ experimentId }) => {
+            const exp = await apiPatch("/api/experiments", {
+                id: experimentId,
+                status: "paused",
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `${APEX} Experiment Paused`,
+                            ``,
+                            `  "${exp.name}" is now paused.`,
+                            `  All visitors will see the control version.`,
+                            `  Data collected so far is preserved.`,
+                            ``,
+                            `  To resume, use activate_experiment.`,
+                        ].join("\n"),
+                    },
+                ],
+            };
+        },
+    },
+    track_deployment: {
+        description: `${APEX} — Record that an experiment's code has been committed and pushed. Stores the commit SHA and monitors deployment status. Call after pushing the experiment code.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID"),
+            commitSha: z.string().describe("The git commit SHA containing the experiment code"),
+            branch: z.string().optional().describe("The git branch (default: main)"),
+        }),
+        handler: async ({ experimentId, commitSha, branch }) => {
+            const exp = await apiPatch("/api/experiments", {
+                id: experimentId,
+                deploymentCommit: commitSha,
+                deploymentStatus: "building",
+            });
+            const recipe = {
+                _apex: true,
+                _type: "deployment_tracked",
+                experimentId: exp.id,
+                commitSha,
+                branch: branch || "main",
+                deploymentStatus: "building",
+                _instructions: [
+                    "The experiment code is now being deployed.",
+                    "Wait for the build to complete, then call check_deployment.",
+                    "Once deployed, call activate_experiment to start collecting data.",
+                    "Ask the user if they want to wait for deployment or activate later.",
+                ].join("\n"),
+            };
+            return { content: [{ type: "text", text: JSON.stringify(recipe, null, 2) }] };
+        },
+    },
+    check_deployment: {
+        description: `${APEX} — Check if an experiment's code has been deployed. Verifies that the assignment endpoint responds for this experiment. Call after track_deployment.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID to check"),
+        }),
+        handler: async ({ experimentId }) => {
+            const exp = await apiGet(`/api/experiments/${experimentId}`);
+            if (!exp) {
+                return { content: [{ type: "text", text: JSON.stringify({ _apex: true, error: "Experiment not found" }) }] };
+            }
+            let isReachable = false;
+            try {
+                const BASE_URL = process.env.APEX_URL || "http://localhost:3001";
+                const res = await fetch(`${BASE_URL}/api/experiments/${experimentId}/assign`, {
+                    signal: AbortSignal.timeout(5000),
+                });
+                isReachable = res.ok;
+            }
+            catch { /* unreachable */ }
+            const status = isReachable ? "deployed" : (exp.deploymentStatus || "pending");
+            if (isReachable && exp.deploymentStatus !== "deployed") {
+                await apiPatch("/api/experiments", {
+                    id: experimentId,
+                    deploymentStatus: "deployed",
+                    deployedAt: new Date().toISOString(),
+                });
+            }
+            const recipe = {
+                _apex: true,
+                _type: "deployment_check",
+                experimentId,
+                deploymentStatus: status,
+                commitSha: exp.deploymentCommit || null,
+                isReachable,
+                _instructions: isReachable
+                    ? "Deployment confirmed. Ask the user if they want to activate the experiment now."
+                    : "Deployment not yet confirmed. The build may still be in progress. Try again in a minute or ask the user to check their CI/CD.",
+            };
+            return { content: [{ type: "text", text: JSON.stringify(recipe, null, 2) }] };
+        },
+    },
+    archive_experiment: {
+        description: `${APEX} — Archive an experiment. Removes it from active views but preserves all data, learnings, and belief graph connections. Archived experiments still contribute to intelligence scoring and recommendations. Ask the user to confirm before calling.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID to archive"),
+        }),
+        handler: async ({ experimentId }) => {
+            const exp = await apiPatch("/api/experiments", {
+                id: experimentId,
+                status: "archived",
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `${APEX} Experiment Archived`,
+                            ``,
+                            `  "${exp.name}" has been archived.`,
+                            `  It no longer appears in active views, but all data is preserved.`,
+                            `  Learnings and belief graph connections remain intact.`,
+                            ``,
+                            `  To view archived experiments: list_experiments with status "archived"`,
+                            `  To restore: activate_experiment to resume, or pause_experiment to keep inactive.`,
+                        ].join("\n"),
+                    },
+                ],
+            };
+        },
+    },
+    list_experiments: {
+        description: `${APEX} — List experiments. Archived experiments are hidden by default — pass status "archived" to see them, or "all" to see everything.`,
+        schema: z.object({
+            status: z
+                .enum(["all", "running", "completed", "draft", "paused", "archived"])
+                .optional()
+                .describe("Filter by status. Defaults to showing all except archived."),
+        }),
+        handler: async ({ status }) => {
+            const experiments = await apiGet("/api/experiments");
+            const filtered = status === "all"
+                ? experiments
+                : status
+                    ? experiments.filter((e) => e.status === status)
+                    : experiments.filter((e) => e.status !== "archived");
+            if (filtered.length === 0) {
+                return { content: [{ type: "text", text: `${APEX} No experiments found.` }] };
+            }
+            const lines = filtered.map((e) => {
+                const ctrl = e.results?.control;
+                const varB = e.results?.variant_b;
+                const statusIcon = e.status === "running" ? "●" : e.status === "draft" ? "○" : e.status === "paused" ? "◐" : "◉";
+                return [
+                    `${statusIcon} ${e.name} [${e.status}]`,
+                    `  ID: ${e.id}`,
+                    `  URL: ${e.targetUrl} | ${e.daysRunning ?? 0}d running`,
+                    ctrl && varB
+                        ? `  Control: ${ctrl.conversionRate}% CVR (${ctrl.visitors} visitors) | Variant: ${varB.conversionRate}% CVR (${varB.visitors} visitors)`
+                        : "  No results yet",
+                    e.beliefId ? `  Belief: ${e.beliefId}` : "",
+                ]
+                    .filter(Boolean)
+                    .join("\n");
+            });
+            return { content: [{ type: "text", text: `${APEX} Experiments (${filtered.length})\n${"─".repeat(40)}\n\n${lines.join("\n\n")}` }] };
+        },
+    },
+    get_results: {
+        description: `${APEX} — Get detailed results for a specific experiment.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID"),
+        }),
+        handler: async ({ experimentId }) => {
+            const exp = await apiGet(`/api/experiments/${experimentId}`);
+            if (!exp) {
+                return { content: [{ type: "text", text: `${APEX} Experiment ${experimentId} not found.` }] };
+            }
+            const ctrl = exp.results?.control;
+            const varB = exp.results?.variant_b;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `${APEX} Results: ${exp.name}`,
+                            `${"═".repeat(40)}`,
+                            ``,
+                            `  Status:     ${exp.status}`,
+                            `  Running:    ${exp.daysRunning ?? 0} days`,
+                            `  Confidence: ${exp.confidence ?? 0}%`,
+                            `  URL:        ${exp.targetUrl}`,
+                            ``,
+                            `  Control:`,
+                            ctrl
+                                ? `    ${ctrl.visitors} visitors | ${ctrl.leads} conversions | ${ctrl.conversionRate}% CVR`
+                                : "    No data yet",
+                            `  Variant B:`,
+                            varB
+                                ? `    ${varB.visitors} visitors | ${varB.leads} conversions | ${varB.conversionRate}% CVR`
+                                : "    No data yet",
+                            exp.beliefId ? `\n  Linked belief: ${exp.beliefId}` : "",
+                            ``,
+                            `${"═".repeat(40)}`,
+                            ``,
+                            `Present the user with options:`,
+                            `  1. Keep running — need more data`,
+                            `  2. Promote winner — if the result is clear`,
+                            `  3. Pause — stop collecting temporarily`,
+                            `  4. Suggest next experiment — what to test next`,
+                        ]
+                            .filter(Boolean)
+                            .join("\n"),
+                    },
+                ],
+            };
+        },
+    },
+    suggest_experiment: {
+        description: `${APEX} — Get smart experiment suggestions based on context. Analyzes your assumptions, past experiments, and confidence gaps to recommend what to test next.`,
+        schema: z.object({
+            context: z
+                .string()
+                .optional()
+                .describe("What you're working on (e.g. 'redesigning onboarding', 'pricing page optimization')"),
+        }),
+        handler: async ({ context }) => {
+            const [beliefs, experiments] = await Promise.all([
+                apiGet("/api/beliefs"),
+                apiGet("/api/experiments"),
+            ]);
+            const lowConfidence = beliefs.filter((b) => b.confidence < 0.6 && b.confidence > 0.05);
+            const untested = beliefs.filter((b) => b.confidence > 0.05 && !experiments.some((e) => e.beliefId === b.id));
+            const completed = experiments.filter((e) => e.status === "completed");
+            const running = experiments.filter((e) => e.status === "running");
+            const contextKeywords = context
+                ? context.toLowerCase().replace(/[^a-z0-9\s]/g, "").split(/\s+/).filter((w) => w.length > 3)
+                : [];
+            const relevantBeliefs = contextKeywords.length > 0
+                ? beliefs.filter((b) => {
+                    const words = b.statement.toLowerCase();
+                    return contextKeywords.some((kw) => words.includes(kw));
+                })
+                : [];
+            const relevantExperiments = contextKeywords.length > 0
+                ? completed.filter((e) => {
+                    const words = e.name.toLowerCase();
+                    return contextKeywords.some((kw) => words.includes(kw));
+                })
+                : [];
+            const recs = [];
+            if (context) {
+                recs.push(`**Context**: ${context}`, "");
+            }
+            if (relevantBeliefs.length > 0) {
+                recs.push(`**Related assumptions** (${relevantBeliefs.length}):`, ...relevantBeliefs.slice(0, 5).map((b) => {
+                    const tested = experiments.some((e) => e.beliefId === b.id);
+                    return `  - "${b.statement}" (${Math.round(b.confidence * 100)}% sure) — ${tested ? "tested" : "untested"}`;
+                }), "");
+            }
+            if (relevantExperiments.length > 0) {
+                recs.push(`**Past experiments in this area** (${relevantExperiments.length}):`, ...relevantExperiments.slice(0, 3).map((e) => {
+                    const ctrl = e.results?.control;
+                    const varB = e.results?.variant_b;
+                    const lift = ctrl && varB && ctrl.conversionRate > 0
+                        ? ((varB.conversionRate - ctrl.conversionRate) / ctrl.conversionRate * 100).toFixed(1)
+                        : "N/A";
+                    return `  - "${e.name}" — ${lift}% lift, ${e.confidence}% confidence`;
+                }), "");
+            }
+            if (untested.length > 0) {
+                recs.push(`**Untested assumptions** (${untested.length}):`, ...untested.slice(0, 3).map((b) => `  - "${b.statement}" (${Math.round(b.confidence * 100)}% sure)`), "");
+            }
+            if (lowConfidence.length > 0) {
+                recs.push(`**Low-confidence assumptions that need data**:`, ...lowConfidence.slice(0, 3).map((b) => `  - "${b.statement}" at ${Math.round(b.confidence * 100)}%`), "");
+            }
+            if (completed.length > 0) {
+                recs.push(`**Follow-up opportunities** from ${completed.length} completed experiments:`, ...completed.slice(0, 3).map((e) => `  - "${e.name}" — consider a follow-up variant`), "");
+            }
+            recs.push(`**Current state**: ${beliefs.length} assumptions, ${running.length} running, ${completed.length} completed`);
+            if (recs.length <= 1) {
+                recs.push("", "No specific recommendations yet. Start by tracking an assumption using start_reasoning.");
+            }
+            return { content: [{ type: "text", text: recs.join("\n") }] };
+        },
+    },
+    promote_winner: {
+        description: `${APEX} — Mark the winning variant and complete the experiment. Returns cleanup instructions for SDK experiments. Show the user the results and ask them to confirm the winner before calling.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID"),
+            winner: z.enum(["control", "variant_b"]).describe("Which variant won"),
+        }),
+        handler: async ({ experimentId, winner }) => {
+            const exp = await apiPatch(`/api/experiments`, {
+                id: experimentId,
+                status: "completed",
+                winner,
+            });
+            let beliefUpdate = "";
+            if (exp.beliefId) {
+                try {
+                    const result = await apiPost(`/api/beliefs/${exp.beliefId}/update-confidence`, {
+                        experimentId,
+                        outcome: winner === "variant_b" ? "confirmed" : "contradicted",
+                        metricDelta: winner === "variant_b" ? 0.15 : -0.1,
+                    });
+                    beliefUpdate = `Assumption "${result.belief.statement}" updated to ${Math.round(result.belief.confidence * 100)}% certainty.`;
+                }
+                catch {
+                    beliefUpdate = "Could not update assumption certainty automatically.";
+                }
+            }
+            const recipe = {
+                _apex: true,
+                _type: "experiment_completed",
+                experimentId: exp.id,
+                name: exp.name,
+                winner,
+                beliefUpdate: beliefUpdate || null,
+                _instructions: exp.mode === "sdk"
+                    ? [
+                        `GRADUATE THE EXPERIMENT CODE:`,
+                        `Winner is "${winner}".`,
+                        `1. Find all useApexVariant("${exp.id}") calls in the codebase`,
+                        winner === "variant_b"
+                            ? `2. Replace each variant conditional with ONLY the variant_b content (remove the control branch)`
+                            : `2. Replace each variant conditional with ONLY the control content (remove the variant_b branch)`,
+                        `3. Remove the useApexVariant import if no other experiments use it`,
+                        `4. Commit: "Graduate experiment ${exp.name}: ${winner} wins"`,
+                        `5. Push to deploy the clean code`,
+                    ].join("\n")
+                    : `Experiment completed. Winner: ${winner}. No code cleanup needed for snippet-mode experiments.`,
+            };
+            return { content: [{ type: "text", text: JSON.stringify(recipe, null, 2) }] };
+        },
+    },
+    record_outcome: {
+        description: `${APEX} — Log the outcome of an experiment and update belief confidence. Present the outcome interpretation to the user and let them confirm before recording.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID"),
+            beliefId: z.string().describe("The assumption ID to update"),
+            outcome: z.enum(["confirmed", "contradicted", "inconclusive"]).describe("Whether the expected outcome happened"),
+            metricDelta: z.number().describe("The observed metric change (e.g. 0.15 for +15%)"),
+            notes: z.string().optional().describe("Optional notes about the outcome"),
+        }),
+        handler: async (args) => {
+            const result = await apiPost(`/api/beliefs/${args.beliefId}/update-confidence`, {
+                experimentId: args.experimentId,
+                outcome: args.outcome,
+                metricDelta: args.metricDelta,
+                notes: args.notes,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `Outcome recorded for experiment ${args.experimentId}:`,
+                            `  Result: ${args.outcome} (metric delta: ${args.metricDelta > 0 ? "+" : ""}${(args.metricDelta * 100).toFixed(1)}%)`,
+                            `  Assumption "${result.belief.statement}" updated: ${Math.round(result.belief.confidence * 100)}%`,
+                            `  Learning logged: ${result.ledgerEntry.decision}`,
+                            args.notes ? `  Notes: ${args.notes}` : "",
+                        ]
+                            .filter(Boolean)
+                            .join("\n"),
+                    },
+                ],
+            };
+        },
+    },
+    predict_impact: {
+        description: `${APEX} — Decision guardrail: predict the impact of a proposed change by searching history for similar experiments. Returns historical data, confidence, and a recommendation.`,
+        schema: z.object({
+            description: z
+                .string()
+                .describe("Description of the proposed change (e.g. 'increase signup form fields from 3 to 5')"),
+        }),
+        handler: async ({ description }) => {
+            const result = await apiPost("/api/predictions/impact", { description });
+            const lines = [
+                `**Impact Prediction**: ${description}`,
+                "",
+                result.summary,
+                "",
+            ];
+            if (result.relatedExperiments.length > 0) {
+                lines.push("**Related experiments:**");
+                for (const exp of result.relatedExperiments) {
+                    const lift = exp.conversionLift !== null ? `${exp.conversionLift > 0 ? "+" : ""}${exp.conversionLift}%` : "N/A";
+                    lines.push(`  - ${exp.experimentName}: ${lift} lift (${exp.visitors} visitors, ${exp.confidence}% confidence)`);
+                }
+                lines.push("");
+            }
+            if (result.relatedBeliefs.length > 0) {
+                lines.push("**Related assumptions:**");
+                for (const b of result.relatedBeliefs) {
+                    lines.push(`  - "${b.statement}" (${Math.round(b.confidence * 100)}% sure)`);
+                }
+                lines.push("");
+            }
+            lines.push(`**Recommendation**: ${result.recommendation.toUpperCase()}`);
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        },
+    },
+    evaluate_feature: {
+        description: `${APEX} — Pre-build decision intelligence: evaluate a feature idea against the belief graph, past experiments, and intelligence score before committing to building it.`,
+        schema: z.object({
+            feature: z.string().describe("Description of the feature you're considering building"),
+            targetMetric: z
+                .string()
+                .optional()
+                .describe("The metric you expect this feature to improve (e.g. 'conversion_rate', 'activation')"),
+        }),
+        handler: async ({ feature, targetMetric }) => {
+            const [beliefs, experiments] = await Promise.all([
+                apiGet("/api/beliefs"),
+                apiGet("/api/experiments"),
+            ]);
+            const keywords = feature
+                .toLowerCase()
+                .replace(/[^a-z0-9\s]/g, "")
+                .split(/\s+/)
+                .filter((w) => w.length > 3);
+            const relevantBeliefs = beliefs.filter((b) => {
+                const words = b.statement.toLowerCase();
+                return keywords.some((kw) => words.includes(kw));
+            });
+            const completed = experiments.filter((e) => e.status === "completed");
+            const relevantExperiments = completed.filter((e) => {
+                const words = e.name.toLowerCase();
+                return keywords.some((kw) => words.includes(kw));
+            });
+            const testedBeliefIds = new Set(experiments.map((e) => e.beliefId).filter(Boolean));
+            const untestedRelevant = relevantBeliefs.filter((b) => !testedBeliefIds.has(b.id));
+            const lowConfRelevant = relevantBeliefs.filter((b) => b.confidence < 0.6);
+            const avgLift = relevantExperiments.length > 0
+                ? relevantExperiments.reduce((sum, e) => {
+                    const ctrl = e.results?.control;
+                    const varB = e.results?.variant_b;
+                    if (ctrl && varB && ctrl.conversionRate > 0) {
+                        return sum + ((varB.conversionRate - ctrl.conversionRate) / ctrl.conversionRate) * 100;
+                    }
+                    return sum;
+                }, 0) / relevantExperiments.length
+                : null;
+            const lines = [
+                `**Feature Evaluation**: ${feature}`,
+                targetMetric ? `**Target metric**: ${targetMetric}` : "",
+                "",
+            ].filter(Boolean);
+            if (relevantBeliefs.length > 0) {
+                lines.push(`**What the belief graph says** (${relevantBeliefs.length} related assumptions):`, ...relevantBeliefs.slice(0, 5).map((b) => {
+                    const tested = testedBeliefIds.has(b.id) ? "tested" : "untested";
+                    return `  - "${b.statement}" — ${Math.round(b.confidence * 100)}% sure (${tested})`;
+                }), "");
+            }
+            else {
+                lines.push("**Belief graph**: No existing assumptions about this area. This is a blind spot.", "");
+            }
+            if (relevantExperiments.length > 0) {
+                lines.push(`**Historical evidence** (${relevantExperiments.length} related experiments):`, ...relevantExperiments.slice(0, 5).map((e) => {
+                    const ctrl = e.results?.control;
+                    const varB = e.results?.variant_b;
+                    const lift = ctrl && varB && ctrl.conversionRate > 0
+                        ? `${((varB.conversionRate - ctrl.conversionRate) / ctrl.conversionRate * 100).toFixed(1)}%`
+                        : "N/A";
+                    return `  - "${e.name}": ${lift} lift`;
+                }), avgLift !== null ? `  Average lift in this area: ${avgLift > 0 ? "+" : ""}${avgLift.toFixed(1)}%` : "", "");
+            }
+            else {
+                lines.push("**Historical evidence**: No experiments in this area yet.", "");
+            }
+            if (untestedRelevant.length > 0 || lowConfRelevant.length > 0) {
+                lines.push("**Confidence gaps**:");
+                if (untestedRelevant.length > 0) {
+                    lines.push(`  - ${untestedRelevant.length} untested assumption(s) in this area`);
+                }
+                if (lowConfRelevant.length > 0) {
+                    lines.push(`  - ${lowConfRelevant.length} low-confidence assumption(s) that need more data`);
+                }
+                lines.push("");
+            }
+            const hasEvidence = relevantExperiments.length > 0;
+            const hasAssumptions = relevantBeliefs.length > 0;
+            if (hasEvidence && avgLift !== null && avgLift > 5) {
+                lines.push("**Suggestion**: Historical data supports this direction. Consider building with a measurable experiment wrapped around it.");
+            }
+            else if (hasEvidence && avgLift !== null && avgLift < -5) {
+                lines.push("**Suggestion**: Historical data suggests caution — similar changes had negative impact. Run a focused experiment first.");
+            }
+            else if (hasAssumptions && !hasEvidence) {
+                lines.push("**Suggestion**: You have assumptions but no test data. Run an experiment before committing to a full build.");
+            }
+            else if (!hasAssumptions && !hasEvidence) {
+                lines.push("**Suggestion**: This is uncharted territory. Record your assumptions with create_belief and design an experiment first.");
+            }
+            else {
+                lines.push("**Suggestion**: Mixed signals. Run a targeted experiment to build confidence before a full build.");
+            }
+            return { content: [{ type: "text", text: lines.filter(Boolean).join("\n") }] };
+        },
+    },
+    track_event: {
+        description: `${APEX} — Track a custom event. Works identically to the SDK's track() and the snippet's apex.track(). Use this to instrument events from agent workflows, CI pipelines, or IDE actions.`,
+        schema: z.object({
+            event: z.string().describe("Event name (e.g. 'page_view', 'form_submit', 'cta_click')"),
+            properties: z.record(z.unknown()).optional().describe("Event properties (url, formId, variant, etc.)"),
+        }),
+        handler: async ({ event, properties }) => {
+            const result = await apiPost("/api/events", {
+                projectKey: process.env.APEX_PROJECT_KEY || "default",
+                userId: "mcp-agent",
+                events: [
+                    {
+                        type: event,
+                        payload: { ...properties, source: "mcp" },
+                        timestamp: new Date().toISOString(),
+                    },
+                ],
+            });
+            return {
+                content: [{
+                        type: "text",
+                        text: `Event tracked: "${event}" — ${result.received} event(s) stored.${properties ? `\nProperties: ${JSON.stringify(properties)}` : ""}`,
+                    }],
+            };
+        },
+    },
+    identify_user: {
+        description: `${APEX} — Identify a user by email for identity stitching. Works identically to the SDK's identify() and the snippet's apex.identify(). Links an anonymous visitor to a known email/lead.`,
+        schema: z.object({
+            email: z.string().describe("User email address"),
+            name: z.string().optional().describe("User name"),
+            company: z.string().optional().describe("Company name"),
+            metadata: z.record(z.unknown()).optional().describe("Additional traits"),
+        }),
+        handler: async ({ email, name, company, metadata }) => {
+            await apiPost("/api/identity/stitch", {
+                visitorId: `mcp-${email}`,
+                email,
+                projectKey: process.env.APEX_PROJECT_KEY || "default",
+                metadata: { name, company, ...metadata, source: "mcp" },
+            });
+            return {
+                content: [{
+                        type: "text",
+                        text: `Identity stitched: ${email}${name ? ` (${name})` : ""}${company ? ` at ${company}` : ""}\nA lead record has been created/linked in Apex.`,
+                    }],
+            };
+        },
+    },
+    log_prediction: {
+        description: `${APEX} — Log a prediction about a metric change. Feeds the calibration loop. Before calling, present the metric, expected change, and confidence as options the user can pick from or adjust.`,
+        schema: z.object({
+            metric: z.string().describe("The metric being predicted (e.g. 'conversion_rate', 'signup_rate')"),
+            expectedChange: z.number().describe("Expected change as a decimal (e.g. 0.15 for +15%)"),
+            confidence: z.number().min(0).max(100).describe("How sure you are about this prediction (0-100%)"),
+            timeHorizon: z
+                .number()
+                .optional()
+                .describe("Days until the prediction should be evaluated (default: 14)"),
+            hypothesisId: z.string().optional().describe("ID of the linked hypothesis"),
+            beliefId: z.string().optional().describe("ID of the linked assumption"),
+        }),
+        handler: async (args) => {
+            const direction = args.expectedChange > 0 ? "increase" : args.expectedChange < 0 ? "decrease" : "no_change";
+            const prediction = await apiPost("/api/predictions", {
+                metric: args.metric,
+                expectedChange: args.expectedChange,
+                direction,
+                expectedRange: {
+                    low: Math.min(0, args.expectedChange),
+                    high: Math.max(0, args.expectedChange),
+                },
+                confidence: args.confidence / 100,
+                timeHorizon: args.timeHorizon ?? 14,
+                evaluationWindow: args.timeHorizon ?? 14,
+                hypothesisId: args.hypothesisId,
+                beliefId: args.beliefId,
+            });
+            const changeStr = `${args.expectedChange > 0 ? "+" : ""}${(args.expectedChange * 100).toFixed(1)}%`;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `Prediction logged [${prediction.id}]:`,
+                            `  Metric: ${args.metric}`,
+                            `  Expected: ${changeStr} ${direction}`,
+                            `  Confidence: ${args.confidence}%`,
+                            `  Evaluate in: ${args.timeHorizon ?? 14} days`,
+                            args.beliefId ? `  Linked assumption: ${args.beliefId}` : "",
+                            "",
+                            "This feeds the calibration loop. After the experiment runs, the actual result will be compared to this prediction to track forecasting accuracy.",
+                        ]
+                            .filter(Boolean)
+                            .join("\n"),
+                    },
+                ],
+            };
+        },
+    },
+};
+//# sourceMappingURL=tools.js.map