splera-mcp 0.0.1 → 0.1.0

package/README.md

@@ -1,15 +1,206 @@
 # splera-mcp
 
-Model Context Protocol (MCP) server for [Splera](https://splera.app) — A/B testing for vibe 
-  coders.
+A/B testing for vibe coders, exposed as a Model Context Protocol (MCP) server. Your AI agent creates experiments, reads results, and ships winners without you leaving chat.
 
-**Status:** Reserved. Full release coming soon.
+<!-- TODO: add demo GIF at docs/demo.gif before v0.2.0 -->
 
-Once live:
-- `create_experiment` — spin up an A/B test from
-   your AI coding agent
-- `get_results` — check live stats + ship-readiness
-- `ship_winner` — roll out the winning variant
-   to 100% of traffic
+Three native tools your agent gets once installed: `create_experiment`, `get_results`, `ship_winner`. The agent calls them, edits your code to wire the SDK and variant, and reports stats back in plain English. No dashboard tab, no copy-paste, no test infrastructure to learn.
 
-Follow along at [splera.app](https://splera.app).
+- npm: [`splera-mcp`](https://www.npmjs.com/package/splera-mcp)
+- Web docs: [splera.app/docs/mcp](https://splera.app/docs/mcp)
+- Issues: [github.com/sohaibt/splera/issues](https://github.com/sohaibt/splera/issues)
+
+---
+
+## What you can do
+
+Once installed, paste any of these into your agent:
+
+> *Create a Splera A/B test for my homepage headline: 'Ship faster.' vs 'Ship with confidence.'*
+
+> *How's my checkout experiment doing?*
+
+> *Ship the winning variant.*
+
+The agent picks the right tool, makes the call, and either edits your code to install the SDK, reports Bayesian stats in human terms, or flips the winning variant server-side (takes effect in ~30 seconds worldwide, no redeploy).
+
+---
+
+## Install
+
+### 1. Generate an API key
+
+Go to [splera.app/settings](https://splera.app/settings), click **Generate new key**, name it something like `claude-code-macbook`. Copy the key from the one-time modal. It starts with `splera_live_`. You will not see the full key again. If you close the modal without copying, revoke and regenerate.
+
+### 2. Add the config to your agent
+
+| Agent | Config file | Method |
+|---|---|---|
+| **Claude Code** | `~/.config/claude-code/mcp.json` | One-liner (below) or edit JSON |
+| **Cursor** | `~/.cursor/mcp.json` | Edit JSON (or Settings → MCP) |
+| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | Edit JSON |
+| **Zed** | `~/.config/zed/settings.json` (`context_servers` block) | Edit JSON |
+| **Replit Agent** | Not supported in v1 (cloud-hosted, can't load local stdio MCP) | — |
+
+#### Claude Code
+
+```bash
+claude mcp add splera npx -y splera-mcp --env SPLERA_API_KEY=splera_live_your_key_here
+```
+
+Then restart Claude Code.
+
+#### Cursor / Windsurf
+
+Same JSON shape for both, just different file paths.
+
+```json
+{
+  "mcpServers": {
+    "splera": {
+      "command": "npx",
+      "args": ["-y", "splera-mcp"],
+      "env": {
+        "SPLERA_API_KEY": "splera_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+Restart the agent.
+
+#### Zed
+
+Add to `~/.config/zed/settings.json`:
+
+```json
+{
+  "context_servers": {
+    "splera": {
+      "command": {
+        "path": "npx",
+        "args": ["-y", "splera-mcp"],
+        "env": { "SPLERA_API_KEY": "splera_live_your_key_here" }
+      }
+    }
+  }
+}
+```
+
+Restart Zed.
+
+---
+
+## Verify your install
+
+### Option A: check the key from any terminal
+
+```bash
+curl -H "Authorization: Bearer splera_live_your_key_here" https://splera.app/api/me
+```
+
+`200 OK` with a JSON body means the key works. `401` means the key is bad or revoked, regenerate at [splera.app/settings](https://splera.app/settings).
+
+### Option B: check the agent's MCP panel after restart
+
+Open your agent's **Server logs** or **MCP** panel. You should see:
+
+```
+splera-mcp: connecting to https://splera.app
+splera-mcp: ready. 3 tools loaded. User: you@example.com
+```
+
+If those lines are missing, the MCP isn't loading. Check your config file path and JSON syntax.
+
+---
+
+## Troubleshooting
+
+### "splera is not available" / "tool not found"
+
+The MCP config isn't being read. Check that (1) you edited the right file for your agent (see install table above), (2) the JSON is valid, no trailing commas, (3) you restarted the agent after editing.
+
+### `SPLERA_API_KEY not set`
+
+The `env` block in your MCP config is missing or malformed. The key must start with `splera_live_`. Re-check the examples above.
+
+### 401 / `SPLERA_INVALID_API_KEY` on every call
+
+The key is wrong, revoked, or truncated during copy. Go to [splera.app/settings](https://splera.app/settings), revoke the existing key, generate a new one, update the config, restart the agent.
+
+### `SPLERA_PLAN_LIMIT_EXCEEDED` on create_experiment
+
+You've hit your plan's monthly experiment cap. Options: [upgrade](https://splera.app/pricing) or ship / stop an existing experiment to free a slot. The error `hint` field tells you which plan and how many slots are used.
+
+### `get_results` says NOT_READY forever
+
+The SDK isn't reaching the page being tested. Verify the script tag is in place:
+
+```html
+<script src="https://splera.app/sdk/splera.js" data-experiment-id="YOUR-EXPERIMENT-UUID" async></script>
+```
+
+Also confirm the page is receiving real traffic. The dashboard shows live exposure counts at [splera.app/experiments/:id](https://splera.app).
+
+### Agent doesn't use the Splera tool even when I ask
+
+Most agents need explicit mentions of the tool until it's familiar. Try prompts like *"use the splera MCP to create an experiment"* instead of generic *"set up an A/B test"*. Once the agent calls it once, it remembers.
+
+---
+
+## Tool reference
+
+### `create_experiment`
+
+Create a new A/B test. Returns the experiment ID, variant IDs, and an SDK install snippet the agent can paste into your codebase.
+
+**Required:** `name` (3-80 chars), `hypothesis` (10-500 chars), `variants` (2-5 items, control first), `metrics` (1-5 items, each with `name` + `event_name`).
+
+**Optional:** `decision_mode` (`quick_decision` / `rigorous` / `bandit`, default `quick_decision`), `platform` (`replit` / `lovable` / `bolt` / `claude_design` / `other`, default `other`).
+
+**Example prompt:**
+
+> *Create a Splera experiment on my pricing page — test "Start free" vs "Get started" on the primary CTA. Primary metric is signup_completed.*
+
+### `get_results`
+
+Fetch current results for an experiment. Returns variant stats, Bayesian leader probability, ship-readiness verdict, and (post-ship) guard-window status. Safe to call once per minute during active experiments. For long-horizon monitoring, use the dashboard.
+
+**Required:** `experiment_id` (UUID from `create_experiment`).
+
+The response includes a `next_check_recommended_at` timestamp so the agent knows when it's worth checking again, instead of spamming the endpoint.
+
+**Example prompt:**
+
+> *How's my hero CTA experiment doing? Ready to ship?*
+
+### `ship_winner`
+
+Ship the winning variant to 100% of traffic. The SDK flips server-side within 30 seconds worldwide. No redeploy, no code change on your end. After shipping, a guard window monitors the live rate against a frozen pre-ship baseline and emails you if performance degrades.
+
+**Required:** `experiment_id`, `winning_variant_id` (the slug-style ID like `variant_b` or `control`, not the variant's display name — use `leading_variant_id` from `get_results`).
+
+**Example prompt:**
+
+> *Ship variant_b on experiment 7f3e9a2b.*
+
+---
+
+## Privacy
+
+- `splera-mcp` makes HTTPS calls to `splera.app` only. No local telemetry, no third-party analytics from this package.
+- Your API key stays on your machine in your agent's MCP config. It's never logged server-side.
+- Keys are stored as `sha256` hashes in our database. Even if our DB were compromised, the raw keys are not recoverable.
+- Revoke any key instantly at [splera.app/settings](https://splera.app/settings). Revocation takes effect within 60 seconds.
+
+---
+
+## Links
+
+- [Settings / API keys](https://splera.app/settings) — generate, name, revoke
+- [Pricing](https://splera.app/pricing) — plan limits and upgrade
+- [Web docs](https://splera.app/docs/mcp) — longer-form setup guide with screenshots
+- [GitHub issues](https://github.com/sohaibt/splera/issues) — bug reports and feature requests
+
+Built by [Splera](https://splera.app). A/B testing for vibe coders.

package/dist/apiClient.d.ts

@@ -0,0 +1,14 @@
+declare const apiUrl: string;
+/**
+ * HTTPS fetch wrapper.
+ *
+ * Responsibilities:
+ *   1. Adds Authorization: Bearer <key> header automatically.
+ *   2. Honors X-Splera-MCP-Min-Version header — if the server tells us
+ *      we're below the minimum supported client, we throw a clean
+ *      SpleraError with the upgrade hint instead of a confusing schema error.
+ *   3. Converts non-2xx responses into SpleraError with a SPLERA_* code
+ *      so tool handlers never see raw HTTP failures.
+ */
+export declare function apiFetch<T>(path: string, init?: RequestInit): Promise<T>;
+export { apiUrl };

package/dist/apiClient.js

@@ -0,0 +1,44 @@
+import { loadConfig, isBelow, CURRENT_MCP_VERSION } from './config.js';
+import { SpleraError, httpStatusToSpleraCode, HINTS } from './errors.js';
+const { apiKey, apiUrl } = loadConfig();
+/**
+ * HTTPS fetch wrapper.
+ *
+ * Responsibilities:
+ *   1. Adds Authorization: Bearer <key> header automatically.
+ *   2. Honors X-Splera-MCP-Min-Version header — if the server tells us
+ *      we're below the minimum supported client, we throw a clean
+ *      SpleraError with the upgrade hint instead of a confusing schema error.
+ *   3. Converts non-2xx responses into SpleraError with a SPLERA_* code
+ *      so tool handlers never see raw HTTP failures.
+ */
+export async function apiFetch(path, init = {}) {
+    const res = await fetch(`${apiUrl}${path}`, {
+        ...init,
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${apiKey}`,
+            'X-Splera-MCP-Version': CURRENT_MCP_VERSION,
+            ...init.headers,
+        },
+    });
+    // Version-skew guard. Runs BEFORE the ok check — server might still
+    // return 2xx with the header as a soft warning ("you'll break on next
+    // breaking change"), and the agent should surface that anyway.
+    const minVersion = res.headers.get('X-Splera-MCP-Min-Version');
+    if (minVersion && isBelow(CURRENT_MCP_VERSION, minVersion)) {
+        throw new SpleraError('SPLERA_MCP_VERSION_TOO_OLD', `splera-mcp ${CURRENT_MCP_VERSION} is below minimum supported version ${minVersion}.`, HINTS.SPLERA_MCP_VERSION_TOO_OLD, 426);
+    }
+    if (!res.ok) {
+        const body = (await res
+            .json()
+            .catch(() => ({})));
+        const { code, hint } = httpStatusToSpleraCode(res.status, body.code);
+        throw new SpleraError(code, body.error ?? res.statusText, body.hint ?? hint, res.status);
+    }
+    return (await res.json());
+}
+// Re-export config values so index.ts + tools can reference them for
+// startup logging and URL construction (e.g. results_url) without
+// re-reading the env.
+export { apiUrl };

package/dist/config.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Env var parsing + validation. Loaded once at startup.
+ *
+ * Fails fast (process.exit(1)) on missing or malformed env vars so the
+ * user learns the problem in the MCP host's server-logs panel instead of
+ * getting a 30-second stuck agent or silent auth failures downstream.
+ */
+export interface Config {
+    apiKey: string;
+    apiUrl: string;
+}
+export declare function loadConfig(): Config;
+/**
+ * Semver comparison used by the X-Splera-MCP-Min-Version guard in apiClient.
+ * Returns true if `current` is strictly less than `minimum`.
+ * Both args are expected to be plain dotted triples (e.g. "0.1.0", "1.2.3").
+ * Pre-release / build metadata is NOT supported — we don't ship those for MCP.
+ */
+export declare function isBelow(current: string, minimum: string): boolean;
+export declare const CURRENT_MCP_VERSION = "0.1.0";

package/dist/config.js

@@ -0,0 +1,54 @@
+/**
+ * Env var parsing + validation. Loaded once at startup.
+ *
+ * Fails fast (process.exit(1)) on missing or malformed env vars so the
+ * user learns the problem in the MCP host's server-logs panel instead of
+ * getting a 30-second stuck agent or silent auth failures downstream.
+ */
+export function loadConfig() {
+    const apiKey = process.env.SPLERA_API_KEY;
+    if (!apiKey) {
+        console.error('splera-mcp: SPLERA_API_KEY not set.\n' +
+            'Generate a key at https://splera.app/settings.\n' +
+            'Your MCP config env block should look like:\n' +
+            '  { "splera": { "command": "npx", "args": ["-y", "splera-mcp"], ' +
+            '"env": { "SPLERA_API_KEY": "splera_live_..." } } }');
+        process.exit(1);
+    }
+    const rawUrl = process.env.SPLERA_API_URL ?? 'https://splera.app';
+    let parsed;
+    try {
+        parsed = new URL(rawUrl);
+    }
+    catch {
+        console.error(`splera-mcp: SPLERA_API_URL is not a valid URL: "${rawUrl}"`);
+        process.exit(1);
+    }
+    const isLocalhost = ['localhost', '127.0.0.1', '0.0.0.0'].includes(parsed.hostname);
+    if (parsed.protocol !== 'https:' && !isLocalhost) {
+        console.error(`splera-mcp: SPLERA_API_URL must use https:// (got "${parsed.protocol}").\n` +
+            'Plain http is only allowed for localhost/127.0.0.1 (local dev).');
+        process.exit(1);
+    }
+    return { apiKey, apiUrl: parsed.origin };
+}
+/**
+ * Semver comparison used by the X-Splera-MCP-Min-Version guard in apiClient.
+ * Returns true if `current` is strictly less than `minimum`.
+ * Both args are expected to be plain dotted triples (e.g. "0.1.0", "1.2.3").
+ * Pre-release / build metadata is NOT supported — we don't ship those for MCP.
+ */
+export function isBelow(current, minimum) {
+    const a = current.split('.').map((n) => parseInt(n, 10));
+    const b = minimum.split('.').map((n) => parseInt(n, 10));
+    for (let i = 0; i < 3; i++) {
+        const ai = a[i] ?? 0;
+        const bi = b[i] ?? 0;
+        if (ai < bi)
+            return true;
+        if (ai > bi)
+            return false;
+    }
+    return false;
+}
+export const CURRENT_MCP_VERSION = '0.1.0';

package/dist/errors.d.ts

@@ -0,0 +1,28 @@
+/**
+ * SPLERA_* error taxonomy + HTTP-status-to-code mapping.
+ *
+ * All agent-facing errors MUST go through here so they land on the agent
+ * with a consistent, namespaced prefix. No raw HTTP codes, no generic
+ * "internal server error" strings. The agent will surface `hint` to the
+ * end user verbatim.
+ */
+export declare class SpleraError extends Error {
+    code: string;
+    hint: string;
+    httpStatus?: number;
+    constructor(code: string, message: string, hint: string, httpStatus?: number);
+}
+/**
+ * User-facing hints per SPLERA_* code. Agents relay these verbatim.
+ * Keep them actionable — every hint ends in a thing the user can DO.
+ */
+export declare const HINTS: Record<string, string>;
+/**
+ * Maps an HTTP status (+ optional server-returned code) to a SPLERA_* code
+ * and its hint. If the server already returned a SPLERA_* code we trust it;
+ * otherwise we fall back to the status-based mapping.
+ */
+export declare function httpStatusToSpleraCode(status: number, serverCode?: string): {
+    code: string;
+    hint: string;
+};

package/dist/errors.js

@@ -0,0 +1,61 @@
+/**
+ * SPLERA_* error taxonomy + HTTP-status-to-code mapping.
+ *
+ * All agent-facing errors MUST go through here so they land on the agent
+ * with a consistent, namespaced prefix. No raw HTTP codes, no generic
+ * "internal server error" strings. The agent will surface `hint` to the
+ * end user verbatim.
+ */
+export class SpleraError extends Error {
+    code;
+    hint;
+    httpStatus;
+    constructor(code, message, hint, httpStatus) {
+        super(message);
+        this.name = 'SpleraError';
+        this.code = code;
+        this.hint = hint;
+        this.httpStatus = httpStatus;
+    }
+}
+/**
+ * User-facing hints per SPLERA_* code. Agents relay these verbatim.
+ * Keep them actionable — every hint ends in a thing the user can DO.
+ */
+export const HINTS = {
+    SPLERA_INVALID_API_KEY: 'Check SPLERA_API_KEY or regenerate at https://splera.app/settings.',
+    SPLERA_PLAN_LIMIT_EXCEEDED: 'Upgrade at https://splera.app/pricing, or ship/stop an existing experiment to free a slot.',
+    SPLERA_DOMAIN_NOT_ALLOWED: 'This experiment is locked to specific domains. Add the requesting origin at the experiment\'s /settings.',
+    SPLERA_EXPERIMENT_NOT_FOUND: 'Experiment ID not found. Confirm the UUID from create_experiment.',
+    SPLERA_VALIDATION_ERROR: 'Check the tool input — see server message for details.',
+    SPLERA_MCP_VERSION_TOO_OLD: 'splera-mcp client is below the minimum supported version. Run: npm update -g splera-mcp',
+    SPLERA_HTTP_ERROR: 'Transient Splera API error. Retry in a moment, or check https://splera.app for status.',
+    SPLERA_UNKNOWN_TOOL: 'Unknown tool name. Expected one of: create_experiment, get_results, ship_winner.',
+    SPLERA_JWT_REQUIRED: 'This action requires a browser session, not an API key. Sign in at https://splera.app/settings.',
+};
+/**
+ * Maps an HTTP status (+ optional server-returned code) to a SPLERA_* code
+ * and its hint. If the server already returned a SPLERA_* code we trust it;
+ * otherwise we fall back to the status-based mapping.
+ */
+export function httpStatusToSpleraCode(status, serverCode) {
+    if (serverCode && serverCode.startsWith('SPLERA_') && HINTS[serverCode]) {
+        return { code: serverCode, hint: HINTS[serverCode] };
+    }
+    switch (status) {
+        case 401:
+            return { code: 'SPLERA_INVALID_API_KEY', hint: HINTS.SPLERA_INVALID_API_KEY };
+        case 402:
+            return { code: 'SPLERA_PLAN_LIMIT_EXCEEDED', hint: HINTS.SPLERA_PLAN_LIMIT_EXCEEDED };
+        case 403:
+            return { code: 'SPLERA_DOMAIN_NOT_ALLOWED', hint: HINTS.SPLERA_DOMAIN_NOT_ALLOWED };
+        case 404:
+            return { code: 'SPLERA_EXPERIMENT_NOT_FOUND', hint: HINTS.SPLERA_EXPERIMENT_NOT_FOUND };
+        case 422:
+            return { code: 'SPLERA_VALIDATION_ERROR', hint: HINTS.SPLERA_VALIDATION_ERROR };
+        case 426:
+            return { code: 'SPLERA_MCP_VERSION_TOO_OLD', hint: HINTS.SPLERA_MCP_VERSION_TOO_OLD };
+        default:
+            return { code: 'SPLERA_HTTP_ERROR', hint: HINTS.SPLERA_HTTP_ERROR };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { apiFetch, apiUrl } from './apiClient.js';
+import { wrapToolHandler } from './toolRunner.js';
+import { CURRENT_MCP_VERSION } from './config.js';
+import { createExperimentTool } from './tools/createExperiment.js';
+import { getResultsTool } from './tools/getResults.js';
+import { shipWinnerTool } from './tools/shipWinner.js';
+// Startup log — appears in the MCP host's "Server logs" panel. Users who
+// mistype config see this line appear (or not) and know the MCP is wired
+// up correctly before the first tool call.
+console.error(`splera-mcp: connecting to ${apiUrl}`);
+// Install verification with a 5s timeout. Slow networks should not hang
+// the MCP host — hosts typically kill a server that doesn't respond in ~10s.
+// On timeout or network error: soft-fail (warn + continue). The first real
+// tool call will re-surface the error with full context. On 401: hard-fail
+// with regenerate guidance.
+const VERIFY_TIMEOUT_MS = 5_000;
+try {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), VERIFY_TIMEOUT_MS);
+    const me = await apiFetch('/api/me', {
+        signal: ctrl.signal,
+    });
+    clearTimeout(t);
+    console.error(`splera-mcp: ready. 3 tools loaded. User: ${me.user.email}`);
+}
+catch (err) {
+    const msg = err.message ?? String(err);
+    const code = err.code ?? '';
+    if (code === 'SPLERA_INVALID_API_KEY') {
+        console.error('splera-mcp: API key rejected (401).\n' +
+            'Regenerate at https://splera.app/settings or verify with:\n' +
+            '  curl -H "Authorization: Bearer $SPLERA_API_KEY" https://splera.app/api/me');
+        process.exit(1);
+    }
+    console.error(`splera-mcp: startup verification skipped (${msg}). Will retry on first tool call.`);
+}
+const tools = [createExperimentTool, getResultsTool, shipWinnerTool];
+const server = new Server({ name: 'splera-mcp', version: CURRENT_MCP_VERSION }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema,
+    })),
+}));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const tool = tools.find((t) => t.name === req.params.name);
+    if (!tool) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: 'text',
+                    text: `SPLERA_UNKNOWN_TOOL: ${req.params.name}\n\nHint: Expected one of: create_experiment, get_results, ship_winner.`,
+                },
+            ],
+        };
+    }
+    return wrapToolHandler(tool, req.params.arguments ?? {});
+});
+await server.connect(new StdioServerTransport());

package/dist/toolRunner.d.ts

@@ -0,0 +1,12 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { Tool } from './types.js';
+/**
+ * Wraps a tool handler so any thrown error — SpleraError or otherwise —
+ * converts to a proper MCP content array with isError: true + SPLERA_*
+ * code in the text block + structured JSON in the resource block.
+ *
+ * This is the ONLY path by which tool-handler errors reach the agent.
+ * The guarantee: every agent-facing error has a SPLERA_* code. No leaked
+ * generic JSON-RPC errors, no leaked stack traces.
+ */
+export declare function wrapToolHandler(tool: Tool, args: unknown): Promise<CallToolResult>;

package/dist/toolRunner.js

@@ -0,0 +1,48 @@
+import { SpleraError } from './errors.js';
+/**
+ * Wraps a tool handler so any thrown error — SpleraError or otherwise —
+ * converts to a proper MCP content array with isError: true + SPLERA_*
+ * code in the text block + structured JSON in the resource block.
+ *
+ * This is the ONLY path by which tool-handler errors reach the agent.
+ * The guarantee: every agent-facing error has a SPLERA_* code. No leaked
+ * generic JSON-RPC errors, no leaked stack traces.
+ */
+export async function wrapToolHandler(tool, args) {
+    try {
+        return await tool.handler(args);
+    }
+    catch (err) {
+        const sp = toSpleraError(err);
+        return {
+            isError: true,
+            content: [
+                {
+                    type: 'text',
+                    text: `${sp.code}: ${sp.message}\n\nHint: ${sp.hint}`,
+                },
+                {
+                    type: 'resource',
+                    resource: {
+                        uri: `splera-error://${sp.code}`,
+                        mimeType: 'application/json',
+                        text: JSON.stringify({
+                            code: sp.code,
+                            message: sp.message,
+                            hint: sp.hint,
+                            status: sp.httpStatus ?? null,
+                        }),
+                    },
+                },
+            ],
+        };
+    }
+}
+function toSpleraError(err) {
+    if (err instanceof SpleraError)
+        return err;
+    if (err instanceof Error) {
+        return new SpleraError('SPLERA_HTTP_ERROR', err.message, 'Unexpected error. Check Splera API status or retry in a moment.');
+    }
+    return new SpleraError('SPLERA_HTTP_ERROR', String(err), 'Unexpected error. Check Splera API status or retry in a moment.');
+}

package/dist/tools/createExperiment.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from '../types.js';
+export declare const createExperimentTool: Tool;

package/dist/tools/createExperiment.js

@@ -0,0 +1,172 @@
+import { apiFetch, apiUrl } from '../apiClient.js';
+/**
+ * Mirror of `packages/web/src/pages/experiments/lib/createExperiment.ts#variantId`.
+ * Duplicated rather than imported because @splera/shared doesn't export it and
+ * the MCP package is meant to be independently publishable — we'd rather eat
+ * the 4 lines of drift risk than add a cross-package dep just for this.
+ */
+function variantIdForIndex(index) {
+    if (index === 0)
+        return 'control';
+    // 97 = 'a'; index 1 → 'b', 2 → 'c', ... maxItems=5 so 'e' is the ceiling.
+    return `variant_${String.fromCharCode(97 + index)}`;
+}
+export const createExperimentTool = {
+    name: 'create_experiment',
+    description: 'Create a new A/B test. Returns the experiment ID, variant IDs, and SDK installation instructions. ' +
+        'The installation snippet in the text block is what the agent should paste into the user\'s codebase. ' +
+        'Variant IDs are server-assigned slugs (control, variant_b, variant_c, ...) — use those (not the variant names) ' +
+        'when calling ship_winner later.',
+    inputSchema: {
+        type: 'object',
+        required: ['name', 'hypothesis', 'variants', 'metrics'],
+        properties: {
+            name: {
+                type: 'string',
+                minLength: 3,
+                maxLength: 80,
+                description: 'Short human-readable name.',
+            },
+            hypothesis: {
+                type: 'string',
+                minLength: 10,
+                maxLength: 500,
+                description: 'What you expect will happen and why.',
+            },
+            variants: {
+                type: 'array',
+                minItems: 2,
+                maxItems: 5,
+                items: {
+                    type: 'object',
+                    required: ['name'],
+                    properties: { name: { type: 'string' } },
+                },
+                description: 'Control first, then 1-4 test variants. IDs are server-generated (control, variant_b, variant_c, ...).',
+            },
+            // NOTE: spec uses `metrics` (plural, minItems: 1) — NOT singular `metric`.
+            // DX review change from design pass.
+            metrics: {
+                type: 'array',
+                minItems: 1,
+                maxItems: 5,
+                items: {
+                    type: 'object',
+                    required: ['name', 'event_name'],
+                    properties: {
+                        name: { type: 'string', description: 'Human-readable metric name.' },
+                        event_name: {
+                            type: 'string',
+                            description: "Event name the SDK will track, e.g. 'signup_completed'.",
+                        },
+                        type: { type: 'string', enum: ['conversion'], default: 'conversion' },
+                        goal: { type: 'string', enum: ['increase', 'decrease'], default: 'increase' },
+                        is_primary: {
+                            type: 'boolean',
+                            default: false,
+                            description: 'First metric is implicitly primary if unset.',
+                        },
+                    },
+                },
+                description: 'Primary metric first. Secondary metrics track side-effects (e.g. pageviews alongside signups).',
+            },
+            decision_mode: {
+                type: 'string',
+                enum: ['quick_decision', 'rigorous', 'bandit'],
+                default: 'quick_decision',
+            },
+            platform: {
+                type: 'string',
+                enum: ['replit', 'lovable', 'bolt', 'claude_design', 'other'],
+                default: 'other',
+            },
+        },
+    },
+    handler: async (rawArgs) => {
+        const args = rawArgs;
+        // Build the payload the API expects. The API route reads `variants[i].id`
+        // directly (no server-side slug generation) and stores the array verbatim
+        // in JSONB, so we assign IDs here. First variant is implicitly control.
+        const variants = args.variants.map((v, i) => ({
+            id: variantIdForIndex(i),
+            name: v.name,
+            is_control: i === 0,
+        }));
+        // First metric becomes primary if none explicitly marked. Matches the web
+        // path's convention — keeps /results working without extra branching.
+        const hasExplicitPrimary = (args.metrics ?? []).some((m) => m.is_primary === true);
+        const metrics = (args.metrics ?? []).map((m, i) => ({
+            name: m.name,
+            event_name: m.event_name,
+            type: m.type ?? 'conversion',
+            goal: m.goal ?? 'increase',
+            is_primary: hasExplicitPrimary ? m.is_primary === true : i === 0,
+        }));
+        const body = {
+            name: args.name,
+            hypothesis: args.hypothesis,
+            variants,
+            metrics,
+            platform: args.platform ?? 'other',
+            decision_mode: args.decision_mode ?? 'quick_decision',
+        };
+        const res = await apiFetch('/api/experiments/create', {
+            method: 'POST',
+            body: JSON.stringify(body),
+        });
+        const exp = res.experiment;
+        const primaryMetric = metrics.find((m) => m.is_primary) ?? metrics[0];
+        const resultsUrl = `https://splera.app/experiments/${exp.id}`;
+        // Human-readable text block. The install snippet is the "aha moment" —
+        // agents paste it verbatim, so keep the formatting stable.
+        const variantLines = variants
+            .map((v) => `  ${v.id.padEnd(9)} -> "${v.name}"`)
+            .join('\n');
+        const text = `Experiment created: "${exp.name}"\n` +
+            `ID: ${exp.id}\n` +
+            `Variants:\n${variantLines}\n` +
+            `Primary metric: ${primaryMetric.event_name} (goal: ${primaryMetric.goal})\n\n` +
+            `To activate, add this to your site's <head>:\n` +
+            `<script src="https://splera.app/sdk/splera.js" data-experiment-id="${exp.id}" async></script>\n\n` +
+            `Then wrap the element you want to vary:\n` +
+            `Splera.getVariant('${exp.id}', (variant) => {\n` +
+            `  if (variant === 'variant_b') document.querySelector('#cta').textContent = '${variants[1]?.name ?? 'Variant B'}';\n` +
+            `});\n\n` +
+            `Track conversions:\n` +
+            `Splera.track('${primaryMetric.event_name}');\n\n` +
+            `View live results: ${resultsUrl}`;
+        // Structured JSON block. CRITICAL: agents parse this, not the prose.
+        // `apiUrl` from config isn't substituted into results_url because the
+        // customer-facing dashboard is always splera.app — apiUrl may be an
+        // internal/api subdomain.
+        const jsonBlock = {
+            experiment_id: exp.id,
+            variants: variants.map((v) => ({
+                id: v.id,
+                name: v.name,
+                is_control: v.is_control,
+            })),
+            primary_metric: {
+                name: primaryMetric.name,
+                event_name: primaryMetric.event_name,
+                goal: primaryMetric.goal,
+            },
+            sdk_script_url: 'https://splera.app/sdk/splera.js',
+            results_url: resultsUrl,
+            api_url: apiUrl,
+        };
+        return {
+            content: [
+                { type: 'text', text },
+                {
+                    type: 'resource',
+                    resource: {
+                        uri: `splera://experiment/${exp.id}`,
+                        mimeType: 'application/json',
+                        text: JSON.stringify(jsonBlock),
+                    },
+                },
+            ],
+        };
+    },
+};

package/dist/tools/getResults.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from '../types.js';
+export declare const getResultsTool: Tool;

package/dist/tools/getResults.js

@@ -0,0 +1,196 @@
+import { apiFetch } from '../apiClient.js';
+// SHIP_THRESHOLDS duplicated from @splera/shared — same reason as variantId in
+// createExperiment.ts: keep MCP independently publishable. Drift risk is low
+// (the thresholds are stable product decisions, not implementation details).
+const SHIP_THRESHOLDS = {
+    quick_decision: { minExposuresPerVariant: 50, minConfidencePct: 80 },
+    rigorous: { minExposuresPerVariant: 200, minConfidencePct: 90 },
+    bandit: { minExposuresPerVariant: 30, minConfidencePct: 85 },
+};
+function computeShipReadiness(res) {
+    // Post-ship takes precedence regardless of confidence — the decision is made.
+    if (res.status === 'concluded') {
+        return {
+            state: 'post_ship',
+            reason: 'Experiment already shipped. Monitor the guard window.',
+            sub: null,
+        };
+    }
+    const thresholds = SHIP_THRESHOLDS[res.decision_mode] ?? SHIP_THRESHOLDS.quick_decision;
+    const minExposures = res.variants.length > 0
+        ? Math.min(...res.variants.map((v) => v.exposures))
+        : 0;
+    const sampleMet = minExposures >= thresholds.minExposuresPerVariant;
+    const confidenceMet = res.confidence_percentage >= thresholds.minConfidencePct;
+    if (!sampleMet) {
+        return {
+            state: 'not_ready',
+            reason: `need ${thresholds.minExposuresPerVariant} exposures per variant, have min ${minExposures}`,
+            sub: 'below_min_exposures',
+        };
+    }
+    if (!confidenceMet) {
+        return {
+            state: 'not_ready',
+            reason: `below ${thresholds.minConfidencePct}% confidence threshold (currently ${res.confidence_percentage.toFixed(0)}%)`,
+            sub: 'below_confidence',
+        };
+    }
+    return {
+        state: 'ready',
+        reason: `threshold met: ${thresholds.minConfidencePct}% confidence, ${thresholds.minExposuresPerVariant} exposures/variant`,
+        sub: null,
+    };
+}
+/**
+ * Compute the recommended next-check timestamp. Intentionally coarse:
+ *   - ready     -> null (user should act, not wait)
+ *   - below confidence     -> ~6h  (waiting for statistical separation)
+ *   - below min exposures  -> ~4h  (waiting for more traffic)
+ *   - post_ship            -> ~24h (guard-window cadence)
+ */
+function computeNextCheckAt(state, sub) {
+    const now = Date.now();
+    const HOURS = 60 * 60 * 1000;
+    switch (state) {
+        case 'ready':
+            return null;
+        case 'post_ship':
+            return new Date(now + 24 * HOURS).toISOString();
+        case 'not_ready':
+            if (sub === 'below_confidence')
+                return new Date(now + 6 * HOURS).toISOString();
+            if (sub === 'below_min_exposures')
+                return new Date(now + 4 * HOURS).toISOString();
+            return new Date(now + 6 * HOURS).toISOString();
+        case 'locked':
+            return new Date(now + 4 * HOURS).toISOString();
+    }
+}
+function fmtPct(rate) {
+    return `${(rate * 100).toFixed(1)}%`;
+}
+function fmtInt(n) {
+    return n.toLocaleString('en-US');
+}
+export const getResultsTool = {
+    name: 'get_results',
+    description: 'Get current results for an experiment — variant stats, leader, ship-readiness, and any guard-window alerts. ' +
+        'Use this to check if an experiment is ready to ship. Safe to call once per minute during active experiments. ' +
+        'For long-horizon monitoring, direct the user to https://splera.app/experiments/:id.',
+    inputSchema: {
+        type: 'object',
+        required: ['experiment_id'],
+        properties: {
+            experiment_id: {
+                type: 'string',
+                description: 'UUID returned by create_experiment.',
+            },
+        },
+    },
+    handler: async (rawArgs) => {
+        const args = rawArgs;
+        const res = await apiFetch(`/api/experiments/${args.experiment_id}/results`);
+        const readiness = computeShipReadiness(res);
+        const nextCheckAt = computeNextCheckAt(readiness.state, readiness.sub);
+        const leader = res.variants.find((v) => v.variant_id === res.leading_variant_id);
+        const resultsUrl = `https://splera.app/experiments/${res.experiment_id}`;
+        // Short-id fallback since the API doesn't echo the experiment name back.
+        const experimentDisplayName = `Experiment ${res.experiment_id.slice(0, 8)}`;
+        // ── Build text output, shape varies by readiness state ─────────────────
+        let text;
+        if (readiness.state === 'post_ship' && res.guardWindow) {
+            const gw = res.guardWindow;
+            const dropPct = Math.abs(gw.deltaPct * 100).toFixed(1);
+            text =
+                `${experimentDisplayName}\n` +
+                    `Status: concluded (guard window active)\n` +
+                    `Winning variant: ${res.leading_variant_id}\n\n` +
+                    `Guard window: ${gw.status.toUpperCase()}  (${gw.daysRemaining} days remaining, ` +
+                    `winner at ${fmtPct(gw.livePostShipRate)} CR vs ${fmtPct(gw.preShipBaselineRate)} baseline, ` +
+                    `${dropPct}% ${gw.deltaPct < 0 ? 'drop' : 'lift'})\n\n` +
+                    `Recommendation: Continue monitoring. If the live rate drops more than ` +
+                    `${(gw.thresholdPct * 100).toFixed(0)}% below the frozen baseline, a rollback alert will fire ` +
+                    `to your email.\nRollback is available at ${resultsUrl} (dashboard only).\n\n` +
+                    `Next check recommended after: ${nextCheckAt} (~24 hours)`;
+        }
+        else {
+            const variantLines = res.variants
+                .map((v) => {
+                const badge = v.variant_id === res.leading_variant_id ? '   <- leading' : '';
+                return (`  ${v.variant_id.padEnd(10)} ("${v.variant_name}"): ` +
+                    `${fmtInt(v.exposures).padStart(6)} exposures  ` +
+                    `${fmtInt(v.conversions).padStart(4)} conv  ` +
+                    `${fmtPct(v.conversion_rate).padStart(5)} CR${badge}`);
+            })
+                .join('\n');
+            const readinessLabel = readiness.state === 'ready' ? 'READY' : 'NOT_READY';
+            const leaderProbPct = leader?.probability_of_being_best != null
+                ? (leader.probability_of_being_best * 100).toFixed(0)
+                : res.confidence_percentage.toFixed(0);
+            const recommendation = readiness.state === 'ready' && leader
+                ? `Ship ${leader.variant_id} now. Call ship_winner with winning_variant_id="${leader.variant_id}".`
+                : 'Keep running. Do not call ship_winner yet.';
+            const nextCheckLine = nextCheckAt == null
+                ? 'Next check recommended after: (N/A - ready to ship)'
+                : `Next check recommended after: ${nextCheckAt}`;
+            text =
+                `${experimentDisplayName}\n` +
+                    `Status: ${res.status}\n` +
+                    `Decision mode: ${res.decision_mode}\n\n` +
+                    `Variants:\n${variantLines}\n\n` +
+                    `Probability leader is best: ${leaderProbPct}%\n` +
+                    `Ship readiness: ${readinessLabel}  (${readiness.reason})\n` +
+                    (res.recommendation ? `Reason: ${res.recommendation}\n` : '') +
+                    `Recommendation: ${recommendation}\n\n` +
+                    nextCheckLine;
+        }
+        // ── JSON block: canonical shape per spec (adapts API's field names) ────
+        const jsonBlock = {
+            experiment_id: res.experiment_id,
+            status: res.status,
+            decision_mode: res.decision_mode,
+            variants: res.variants.map((v) => ({
+                id: v.variant_id,
+                name: v.variant_name,
+                is_control: v.is_control,
+                exposures: v.exposures,
+                conversions: v.conversions,
+                rate: v.conversion_rate,
+                probability_best: v.probability_of_being_best,
+                is_leading: v.variant_id === res.leading_variant_id,
+            })),
+            leading_variant_id: res.leading_variant_id ?? null,
+            probability_leader_is_best: leader?.probability_of_being_best ?? res.confidence_percentage / 100,
+            confidence_percentage: res.confidence_percentage,
+            ship_readiness: readiness.state,
+            ship_readiness_reason: readiness.reason,
+            next_check_recommended_at: nextCheckAt,
+            guard_window: res.guardWindow
+                ? {
+                    status: res.guardWindow.status,
+                    days_remaining: res.guardWindow.daysRemaining,
+                    baseline_rate: res.guardWindow.preShipBaselineRate,
+                    live_rate: res.guardWindow.livePostShipRate,
+                    delta_pct: res.guardWindow.deltaPct,
+                    threshold_pct: res.guardWindow.thresholdPct,
+                    ends_at: res.guardWindow.guardWindowEndsAt,
+                }
+                : null,
+            results_url: resultsUrl,
+        };
+        return {
+            content: [
+                { type: 'text', text },
+                {
+                    type: 'resource',
+                    resource: {
+                        uri: `splera://experiment/${res.experiment_id}/results`,
+                        mimeType: 'application/json',
+                        text: JSON.stringify(jsonBlock),
+                    },
+                },
+            ],
+        };
+    },
+};

package/dist/tools/shipWinner.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from '../types.js';
+export declare const shipWinnerTool: Tool;

package/dist/tools/shipWinner.js

@@ -0,0 +1,72 @@
+import { apiFetch } from '../apiClient.js';
+const DAY_MS = 24 * 60 * 60 * 1000;
+export const shipWinnerTool = {
+    name: 'ship_winner',
+    description: 'Ship the winning variant to 100% of traffic. The SDK will flip server-side within 30 seconds — no code deploy needed. ' +
+        'Use after get_results confirms the experiment is ship-ready.',
+    inputSchema: {
+        type: 'object',
+        required: ['experiment_id', 'winning_variant_id'],
+        properties: {
+            experiment_id: {
+                type: 'string',
+                description: 'UUID returned by create_experiment.',
+            },
+            winning_variant_id: {
+                type: 'string',
+                // CRITICAL wording: agents confuse the variant NAME ("Get started")
+                // with the variant ID ("variant_b"). The API rejects names with a 400
+                // and the error looks like our bug — so spell it out in the schema
+                // description, which the agent sees on every tool-selection pass.
+                description: "Variant ID from get_results.leading_variant_id (or variants[i].id where is_leading=true). " +
+                    "NOT the variant name — use the slug-style ID like 'variant_b' or 'control'.",
+            },
+        },
+    },
+    handler: async (rawArgs) => {
+        const args = rawArgs;
+        const res = await apiFetch(`/api/experiments/${args.experiment_id}/ship`, {
+            method: 'POST',
+            body: JSON.stringify({ winning_variant_id: args.winning_variant_id }),
+        });
+        const exp = res.experiment;
+        const winningVariant = exp.variants.find((v) => v.id === exp.winning_variant_id);
+        const winningLabel = winningVariant
+            ? `${exp.winning_variant_id} ("${winningVariant.name}")`
+            : exp.winning_variant_id;
+        // Derive guard_window_ends_at from shipped_at + guard_window_days.
+        // The API does not return this composite directly.
+        const guardWindowEndsAt = new Date(new Date(exp.shipped_at).getTime() + exp.guard_window_days * DAY_MS).toISOString();
+        const guardWindowEndsDate = guardWindowEndsAt.slice(0, 10); // YYYY-MM-DD
+        const resultsUrl = `https://splera.app/experiments/${exp.id}`;
+        const text = `Shipped ${winningLabel} to 100% of traffic.\n` +
+            `SDK will refresh within 30 seconds worldwide — no redeploy needed.\n\n` +
+            `Guard window: ${exp.guard_window_days} days (until ${guardWindowEndsDate}).\n` +
+            `  - Use get_results to monitor for degradation.\n` +
+            `  - If the live rate drops below baseline past the alert threshold, you'll get an email alert.\n` +
+            `  - Rollback is manual only (dashboard): ${resultsUrl}\n\n` +
+            `Next step (optional): when you're confident the winner is stable, hardcode it\n` +
+            `into your codebase and remove the Splera script tag. The dashboard will walk\n` +
+            `you through it.`;
+        // Flatten to the spec's ShipResponse shape in the JSON block.
+        const shipResponse = {
+            winning_variant_id: exp.winning_variant_id,
+            shipped_at: exp.shipped_at,
+            guard_window_ends_at: guardWindowEndsAt,
+            results_url: resultsUrl,
+        };
+        return {
+            content: [
+                { type: 'text', text },
+                {
+                    type: 'resource',
+                    resource: {
+                        uri: `splera://experiment/${exp.id}/ship`,
+                        mimeType: 'application/json',
+                        text: JSON.stringify(shipResponse),
+                    },
+                },
+            ],
+        };
+    },
+};

package/dist/types.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Shared types for tool handlers + core modules.
+ */
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * Input schema shape — plain JSON Schema that MCP passes to the client.
+ * We keep it loose (Record<string, unknown>) because the MCP SDK doesn't
+ * enforce a TypeScript type over it; the validation happens at call time
+ * via the input schema the tool declares.
+ */
+export type JsonSchema = Record<string, unknown>;
+export interface Tool {
+    name: string;
+    description: string;
+    inputSchema: JsonSchema;
+    /**
+     * Handler receives the arguments object (already parsed from JSON by the
+     * MCP SDK). It returns a full CallToolResult — text + structured resource
+     * content blocks — OR throws. Throws are caught by wrapToolHandler() which
+     * converts them to SPLERA_* error content blocks.
+     */
+    handler: (args: unknown) => Promise<CallToolResult>;
+}
+/**
+ * Shape returned by `POST /api/experiments/create` → `{ experiment: ExperimentRow }`
+ * and by `POST /api/experiments/:id/ship` → `{ experiment: ExperimentRow }`.
+ * Matches the DB row. Only the fields tool handlers actually read are typed;
+ * the API returns more.
+ */
+export interface ExperimentRow {
+    id: string;
+    name: string;
+    hypothesis: string;
+    variants: Array<{
+        id: string;
+        name: string;
+        is_control?: boolean;
+    }>;
+    metrics: Array<{
+        name: string;
+        event_name: string;
+        type?: string;
+        goal?: 'increase' | 'decrease';
+        is_primary?: boolean;
+    }>;
+    status: string;
+    decision_mode: string;
+    platform: string;
+    winning_variant_id?: string | null;
+    shipped_at?: string | null;
+    guard_window_days?: number | null;
+    created_at: string;
+}
+/**
+ * Adapted from ExperimentRow by shipWinner.ts — it takes the ship-route's
+ * `{ experiment: ExperimentRow }` response and derives `guard_window_ends_at`
+ * from `shipped_at + guard_window_days`, since the API returns the pieces
+ * but not the pre-computed end timestamp.
+ */
+export interface ShipResponse {
+    winning_variant_id: string;
+    shipped_at: string;
+    guard_window_ends_at: string;
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * Shared types for tool handlers + core modules.
+ */
+export {};

package/package.json

@@ -1,17 +1,47 @@
 {
   "name": "splera-mcp",
-  "version": "0.0.1",
-  "description": "Model Context Protocol (MCP) server for Splera — A/B testing for vibe coders. Full release coming soon: https://splera.app",
-  "scripts": {},
+  "version": "0.1.0",
+  "description": "Model Context Protocol (MCP) server for Splera — A/B testing for vibe coders. Create experiments, check results, and ship winners directly from your AI coding agent.",
+  "type": "module",
+  "bin": {
+    "splera-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.1"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
   "keywords": [
     "mcp",
     "model-context-protocol",
     "ab-testing",
     "experiments",
-    "splera"
+    "splera",
+    "claude-code",
+    "cursor",
+    "ai-agent"
   ],
-  "author": "",
   "license": "MIT",
-  "type": "commonjs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sohaibt/splera"
+  },
   "homepage": "https://splera.app"
 }