splera-mcp 0.1.3 → 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sohaib Thiab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -7,8 +7,8 @@ A/B testing for vibe coders, exposed as a Model Context Protocol (MCP) server. Y
 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.
 
 - 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)
+- Web docs: [splera.ai/docs/mcp](https://splera.ai/docs/mcp)
+- Issues: [github.com/sohaibt/splera-mcp/issues](https://github.com/sohaibt/splera-mcp/issues)
 
 ---
 
@@ -30,7 +30,7 @@ The agent picks the right tool, makes the call, and either edits your code to in
 
 ### 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.
+Go to [splera.ai/settings](https://splera.ai/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
 
@@ -100,7 +100,7 @@ Restart Zed.
 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).
+`200 OK` with a JSON body means the key works. `401` means the key is bad or revoked, regenerate at [splera.ai/settings](https://splera.ai/settings).
 
 ### Option B: check the agent's MCP panel after restart
 
@@ -121,17 +121,17 @@ If those lines are missing, the MCP isn't loading. Check your config file path a
 
 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`
+### `SPLERA_API_KEY not set` / `SPLERA_API_KEY_MISSING` on every call
 
-The `env` block in your MCP config is missing or malformed. The key must start with `splera_live_`. Re-check the examples above.
+The server starts without a key (so your agent still lists the tools), but every call fails until the key is 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.
+The key is wrong, revoked, or truncated during copy. Go to [splera.ai/settings](https://splera.ai/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.
+You've hit your plan's monthly experiment cap. Options: [upgrade](https://splera.ai/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
 
@@ -145,7 +145,7 @@ The SDK isn't reaching the page being tested. Verify the script tag is in place:
 
 `data-api-url` is required: without it the SDK tracks nothing. If your experiment was created with splera-mcp 0.1.1, its install code was missing this attribute and used a callback form of `getVariant` that never runs. Re-copy the snippet from the experiment page on the dashboard.
 
-Also confirm the page is receiving real traffic. The dashboard shows live exposure counts at [splera.app/experiments/:id](https://splera.app).
+Also confirm the page is receiving real traffic. The dashboard shows live exposure counts at [splera.ai/experiments/:id](https://splera.ai).
 
 ### Agent doesn't use the Splera tool even when I ask
 
@@ -196,15 +196,15 @@ Ship the winning variant to 100% of traffic. The SDK flips server-side within 30
 - `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.
+- Revoke any key instantly at [splera.ai/settings](https://splera.ai/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
+- [Settings / API keys](https://splera.ai/settings) — generate, name, revoke
+- [Pricing](https://splera.ai/pricing) — plan limits and upgrade
+- [Web docs](https://splera.ai/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.
+Built by [Splera](https://splera.ai). A/B testing for vibe coders.

package/dist/apiClient.js

@@ -13,6 +13,9 @@ const { apiKey, apiUrl } = loadConfig();
  *      so tool handlers never see raw HTTP failures.
  */
 export async function apiFetch(path, init = {}) {
+    if (!apiKey) {
+        throw new SpleraError('SPLERA_API_KEY_MISSING', 'SPLERA_API_KEY is not set.', HINTS.SPLERA_API_KEY_MISSING);
+    }
     const res = await fetch(`${apiUrl}${path}`, {
         ...init,
         headers: {

package/dist/config.d.ts

@@ -1,9 +1,12 @@
 /**
  * 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.
+ * A missing SPLERA_API_KEY does NOT exit: the server still starts and lists
+ * its tools (directories like Glama and MCP inspectors introspect without a
+ * key), logs the fix to the host's server-logs panel, and every tool call
+ * returns SPLERA_API_KEY_MISSING with the same fix (apiClient.ts).
+ * A malformed SPLERA_API_URL still fails fast (process.exit(1)) — that is a
+ * developer override, never set by directories.
  */
 export interface Config {
     apiKey: string;
@@ -17,4 +20,4 @@ export declare function loadConfig(): Config;
  * 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.3";
+export declare const CURRENT_MCP_VERSION = "0.1.4";

package/dist/config.js

@@ -1,19 +1,22 @@
 /**
  * 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.
+ * A missing SPLERA_API_KEY does NOT exit: the server still starts and lists
+ * its tools (directories like Glama and MCP inspectors introspect without a
+ * key), logs the fix to the host's server-logs panel, and every tool call
+ * returns SPLERA_API_KEY_MISSING with the same fix (apiClient.ts).
+ * A malformed SPLERA_API_URL still fails fast (process.exit(1)) — that is a
+ * developer override, never set by directories.
  */
 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' +
+            'Generate a key at https://splera.ai/settings.\n' +
             'Your MCP config env block should look like:\n' +
             '  { "splera": { "command": "npx", "args": ["-y", "splera-mcp@latest"], ' +
-            '"env": { "SPLERA_API_KEY": "splera_live_..." } } }');
-        process.exit(1);
+            '"env": { "SPLERA_API_KEY": "splera_live_..." } } }\n' +
+            'Starting anyway: tools will list, but every call fails until the key is set.');
     }
     const rawUrl = process.env.SPLERA_API_URL ?? 'https://splera.app';
     let parsed;
@@ -30,7 +33,7 @@ export function loadConfig() {
             'Plain http is only allowed for localhost/127.0.0.1 (local dev).');
         process.exit(1);
     }
-    return { apiKey, apiUrl: parsed.origin };
+    return { apiKey: apiKey ?? '', apiUrl: parsed.origin };
 }
 /**
  * Semver comparison used by the X-Splera-MCP-Min-Version guard in apiClient.
@@ -51,4 +54,4 @@ export function isBelow(current, minimum) {
     }
     return false;
 }
-export const CURRENT_MCP_VERSION = '0.1.3';
+export const CURRENT_MCP_VERSION = '0.1.4';

package/dist/errors.js

@@ -23,15 +23,16 @@ export class SpleraError extends Error {
  * 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_API_KEY_MISSING: 'Set SPLERA_API_KEY in the env block of your MCP config (generate a key at https://splera.ai/settings), then restart your agent.',
+    SPLERA_INVALID_API_KEY: 'Check SPLERA_API_KEY or regenerate at https://splera.ai/settings.',
+    SPLERA_PLAN_LIMIT_EXCEEDED: 'Upgrade at https://splera.ai/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_EXPERIMENT_NOT_FOUND: 'Experiment not found — it may have been deleted. 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_HTTP_ERROR: 'Transient Splera API error. Retry in a moment, or check https://splera.ai 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.',
+    SPLERA_JWT_REQUIRED: 'This action requires a browser session, not an API key. Sign in at https://splera.ai/settings.',
 };
 /**
  * Maps an HTTP status (+ optional server-returned code) to a SPLERA_* code

package/dist/index.js

@@ -15,8 +15,10 @@ 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.
+// tool call will re-surface the error with full context. A missing or
+// rejected key warns but does NOT exit, so the server still answers
+// tools/list (directories like Glama introspect without a key); every tool
+// call then returns SPLERA_API_KEY_MISSING / SPLERA_INVALID_API_KEY.
 const VERIFY_TIMEOUT_MS = 5_000;
 try {
     const ctrl = new AbortController();
@@ -30,13 +32,17 @@ try {
 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' +
+    if (code === 'SPLERA_API_KEY_MISSING') {
+        // config.ts already logged the fix.
+    }
+    else if (code === 'SPLERA_INVALID_API_KEY') {
+        console.error('splera-mcp: API key rejected (401). Tools will list, but every call fails until it is fixed.\n' +
+            'Regenerate at https://splera.ai/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.`);
+    else {
+        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: {} } });

package/dist/tools/createExperiment.js

@@ -117,7 +117,7 @@ export const createExperimentTool = {
         });
         const exp = res.experiment;
         const primaryMetric = metrics.find((m) => m.is_primary) ?? metrics[0];
-        const resultsUrl = `https://splera.app/experiments/${exp.id}`;
+        const resultsUrl = `https://splera.ai/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
@@ -134,7 +134,7 @@ export const createExperimentTool = {
             `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
+        // customer-facing dashboard is always splera.ai — apiUrl may be an
         // internal/api subdomain.
         const jsonBlock = {
             experiment_id: exp.id,

package/dist/tools/getResults.js

@@ -77,7 +77,7 @@ 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.',
+        'For long-horizon monitoring, direct the user to https://splera.ai/experiments/:id.',
     inputSchema: {
         type: 'object',
         required: ['experiment_id'],
@@ -94,7 +94,7 @@ export const getResultsTool = {
         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}`;
+        const resultsUrl = `https://splera.ai/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 ─────────────────

package/dist/tools/shipWinner.js

@@ -38,7 +38,7 @@ export const shipWinnerTool = {
         // 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 resultsUrl = `https://splera.ai/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` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "splera-mcp",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "mcpName": "io.github.sohaibt/splera",
   "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",