snowbll-mcp 0.1.0 → 0.2.0

package/README.md

@@ -1,88 +1,43 @@
-# Snowbll MCP
+# Snowbll MCP + CLI
 
-**Snowbll gives AI agents deep Gaming Behaviour Intelligence.**
+**Search the Snowbll game catalog, read your gaming persona, and follow Forge campaigns — from any MCP-capable AI agent or your terminal.**
 
-> Not another game recommender. A behaviour intelligence layer for gaming agents.
+Everything in this package talks to the **live Snowbll API** (`https://www.snowbll.com`). There is no mock data.
 
-Snowbll MCP is a [Model Context Protocol](https://modelcontextprotocol.io) server
-that exposes Snowbll's gaming-behaviour intelligence as tools any AI agent can
-call — Claude, Cursor, Windsurf, OpenAI Agents SDK, LangChain, CrewAI, AutoGen,
-the Vercel AI SDK, and custom TypeScript/Python agents.
+Status: the search and Forge tools hit live public endpoints; the MCP servers, API keys, and the keyed v1 endpoints are in **developer preview** — names, fields, auth, and quotas may change before launch.
 
-It helps agents understand how a gamer actually plays: their playstyle DNA,
-gaming persona, session patterns, completion behavior, purchase behavior,
-genre mismatches, game-fit prediction, and likely next best game.
+Two binaries ship in one package:
 
-## What this is (and is not)
+| Binary | What it is |
+| --- | --- |
+| `snowbll-mcp` | [Model Context Protocol](https://modelcontextprotocol.io) server over stdio — launched by agents (Claude, Cursor, Hermes, …) |
+| `snowbll` | CLI for humans — search, persona, Forge, key management |
 
-```
-AI Agent
-  → Snowbll MCP Server (stdio)
-    → Snowbll API or mock data
-      → Gaming Behaviour Intelligence
-```
-
-Snowbll MCP is **not** the agent. It is a **tool provider**. The agent decides
-when to call a tool; Snowbll MCP returns structured behaviour intelligence as
-JSON. The first version ships with realistic **mock data** so you can build and
-test integrations immediately, with no backend required.
+There is also a **hosted remote MCP server (developer preview)** at `https://www.snowbll.com/api/mcp` (Streamable HTTP) for clients that connect to URLs instead of launching processes — ChatGPT connectors, Claude custom connectors, Hermes remote MCP.
 
-## Install
+## Tools
 
-```bash
-npm install
-npm run build
-```
+The MCP surface is deliberately read-only: tools recommend, explain, and retrieve. Nothing here buys games, backs campaigns, or moves money.
 
-## Run locally
+| Tool | What it does | Needs API key? |
+| --- | --- | --- |
+| `search_games` | Natural-language catalog search with ranked candidates + reasons | No |
+| `get_game` | Full metadata for one game, incl. human-verification status | No |
+| `get_persona` | The key owner's gaming persona (consent-scoped) | Yes — data visible from the **Observer** rank up; free accounts get a locked marker |
+| `list_forge_campaigns` | Forge campaigns with live funding totals | No |
+| `get_forge_campaign` | One campaign: tiers, stretch goals, progress | No |
 
-Run the server in mock mode (the default — no API key needed):
+Honesty model: `verification` is `verified` only after third-party human testing; quality fields (`graphicsFidelity`, `economyComplexity`) are `null` until a human rated them. AI recommends, humans judge.
 
-```bash
-npm run dev
-```
-
-You should see, on stderr:
-
-```
-[snowbll-mcp] running on stdio — data mode: mock
-```
+## Quick start (agents)
 
-The server speaks MCP over stdio, so it's meant to be launched by an MCP client
-(Claude Desktop, Cursor, etc.) rather than used interactively. To smoke-test the
-built binary directly:
+### Claude Code
 
 ```bash
-npm run build
-node dist/index.js
-```
-
-## Connect it to Claude / Cursor (local development)
-
-After `npm run build`, point your MCP client at the built file. Use an absolute
-path to `dist/index.js`.
-
-```json
-{
-  "mcpServers": {
-    "snowbll": {
-      "command": "node",
-      "args": ["C:/PATH/TO/snowbll-mcp/dist/index.js"],
-      "env": {
-        "SNOWBLL_USE_MOCK": "true"
-      }
-    }
-  }
-}
+claude mcp add snowbll -- npx -y snowbll-mcp
 ```
 
-- **Claude Desktop:** add this to `claude_desktop_config.json`
-  (Settings → Developer → Edit Config), then restart Claude Desktop.
-- **Cursor / Windsurf:** add it to the editor's MCP settings (`mcp.json`).
-
-### Future: install from npm
-
-Once Snowbll MCP is published and you have an API key, no local build is needed:
+### Claude Desktop / Cursor / Windsurf / Hermes (stdio)
 
 ```json
 {
@@ -90,144 +45,67 @@ Once Snowbll MCP is published and you have an API key, no local build is needed:
     "snowbll": {
       "command": "npx",
       "args": ["-y", "snowbll-mcp"],
-      "env": {
-        "SNOWBLL_API_KEY": "snb_YOUR_API_KEY"
-      }
+      "env": { "SNOWBLL_API_KEY": "sb_YOUR_API_KEY" }
     }
   }
 }
 ```
 
-## Configuration
-
-| Variable           | Default                       | Description                                                                 |
-| ------------------ | ----------------------------- | --------------------------------------------------------------------------- |
-| `SNOWBLL_USE_MOCK` | `true`                        | Use local mock intelligence. Set to `false` to call the real Snowbll API.   |
-| `SNOWBLL_API_URL`  | `https://api.snowbll.com/v1`  | Base URL of the Snowbll API (live mode only).                               |
-| `SNOWBLL_API_KEY`  | _(none)_                      | Required when `SNOWBLL_USE_MOCK=false`. Format `snb_...`.                    |
-| `SNOWBLL_API_TIMEOUT_MS` | `10000`                 | Per-request timeout (live mode). Hung requests abort and surface an error.  |
-| `SNOWBLL_API_RETRIES` | `2`                        | Retries after the first attempt for transient errors (timeout, 429, 5xx).   |
-
-Mock mode is the default: the server runs with zero configuration and never
-needs an API key. In live mode (`SNOWBLL_USE_MOCK=false`), a missing
-`SNOWBLL_API_KEY` produces a clear, actionable error. Live requests time out and
-retry transient failures (429/5xx) with exponential backoff; non-retryable 4xx
-errors fail fast.
-
-## Tests
-
-```bash
-npm test
-```
-
-Runs the suite via Node's built-in test runner (`tsx test/all.test.ts`): mock
-intelligence logic, output-schema round-trips, client mock/live routing, and the
-HTTP layer's timeout/retry behaviour (against a local server). No network.
+Omit the `env` block to run keyless (search, game lookups, and Forge tools still work — only `get_persona` needs a key).
 
-## Common workflows
+### ChatGPT (remote connector — no install)
 
-**Understand a player**
-1. `get_player_overview` — high-level identity and current objective.
-2. `analyze_player_behaviour` — full behavioural analysis (`depth: "deep"` for correlations and risks).
-3. `get_persona_cards` / `get_playstyle_dna` — evidence-backed detail.
+1. Settings → Connectors (requires a plan with connectors/developer mode).
+2. Add a custom connector with URL `https://www.snowbll.com/api/mcp`, authentication **None**.
+3. Ask: *"Use Snowbll to find an economy sim like Lemonade Tycoon with a deep economy."*
 
-**Explain taste and behaviour**
-- `explain_taste_pattern` with a question like _"Why do I abandon open-world RPGs?"_
-- `detect_genre_mismatch` to surface where stated taste diverges from observed behaviour.
+The remote server also implements OpenAI's `search` / `fetch` connector contract, so it works in ChatGPT deep research too.
 
-**Predict game fit**
-- `predict_game_fit` for one title.
-- `compare_games_for_player` to rank 2–5 candidates.
+### Claude (claude.ai custom connector / remote)
 
-**Recommend what to play next**
-- `recommend_games` with an objective (`likely_to_finish`, `hidden_gems`, `deep_systems`, `comfort_games`, `short_sessions`, `high_progression`).
+Add a custom connector with URL `https://www.snowbll.com/api/mcp`. Public tools need no auth.
 
-## Tool catalog
+### Verify any setup
 
-| Tool                         | Input                                                   | What it returns                                                            |
-| ---------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------- |
-| `get_player_overview`        | _none_                                                  | Totals, persona match, current objective, identity summary.                |
-| `get_playstyle_dna`          | _none_                                                  | Playstyle traits with scores and tiers, plus the player's unique edge.     |
-| `get_persona_cards`          | _none_                                                  | Persona cards with rarity, level, progress, and evidence.                  |
-| `get_activity_patterns`      | _none_                                                  | Active hours, session-length distribution, platform split, play rhythm.    |
-| `get_completion_behavior`    | _none_                                                  | Completion rate, strong/weak categories, drop-off signals.                 |
-| `get_purchase_behavior`      | `includeSensitiveSignals?`                              | Purchase aggregates and buy-vs-play mismatch.                              |
-| `detect_genre_mismatch`      | `includePurchaseSignals?`, `includeCompletionSignals?` | Where claimed/purchased taste diverges from observed behaviour.            |
-| `analyze_player_behaviour`   | `depth?`, `includeEvidence?`                            | Full behavioural analysis with evidence and interpretation.               |
-| `explain_taste_pattern`      | `topic`                                                 | Explanation, supporting signals, and actionable advice for a topic.        |
-| `predict_game_fit`           | `gameTitle`, `platform?`                                | Fit score, finish likelihood, drop-off risk, and reasoning for one game.   |
-| `compare_games_for_player`   | `games[2..5]`                                           | Ranked comparison with a best pick.                                        |
-| `recommend_games`            | `objective?`, `limit?`                                  | Behaviour-fit game recommendations for a chosen objective.                 |
-| `crosscheck_recommendations` | `objective?`, `limit?`                                  | Games validated by TWO engines (consensus + referee) with an agreement score. |
+Ask the agent:
 
-## Resources
+> Use search_games to find: "economy sim like Lemonade Tycoon with a deep economy"
 
-Attach a player's Snowbll context directly (read-only) instead of calling several tools:
+A working setup returns a short candidate list, each with `reasons`.
 
-| Resource URI                     | Contents                                                |
-| -------------------------------- | ------------------------------------------------------- |
-| `snowbll://player/profile`       | Combined overview + playstyle DNA + personas + activity |
-| `snowbll://player/overview`      | High-level identity and current objective               |
-| `snowbll://player/playstyle-dna` | Playstyle traits with scores and tiers                  |
-| `snowbll://player/personas`      | Persona cards                                            |
+## Quick start (humans)
 
-## Prompts
-
-Ready-made templates, surfaced as slash-commands in Claude Desktop / Cursor:
-
-| Prompt              | Arguments    | What it does                                 |
-| ------------------- | ------------ | -------------------------------------------- |
-| `understand-player` | —            | Build a full profile of the player           |
-| `what-to-play`      | `objective?` | Recommend the next game and explain why      |
-| `should-i-play`     | `gameTitle`  | Predict fit and finish likelihood for a game |
-| `compare-games`     | `games`      | Rank 2–5 games by behavioural fit            |
-
-> **Structured output:** the behaviour-intelligence tools return validated
-> `structuredContent` (machine-readable JSON) alongside the text result.
-
-## Privacy
-
-By default, Snowbll MCP tools return **aggregate behaviour intelligence** — not
-raw session logs, raw purchase data, private posts, or friend data.
-`get_purchase_behavior` only exposes raw, purchase-level detail when explicitly
-asked via `includeSensitiveSignals: true`; otherwise it returns aggregates only.
+```bash
+npm install -g snowbll-mcp
+
+snowbll search "cozy farming game with deep crafting"
+snowbll forge                 # campaigns on The Forge
+snowbll login                 # mint + store an API key (email+password account)
+snowbll whoami
+snowbll persona               # your gaming persona
+snowbll setup                 # wizard + ready-to-paste agent configs
+```
 
-## Extending to a real backend
+## API keys (developer preview)
 
-`src/client.ts` is the single seam between the MCP tools and the data source.
-Each tool maps to one `client.call(endpoint, payload, mockFn)`:
+Keys (`sb_…`) belong to Snowbll accounts and are hashed at rest — the plaintext is shown once.
 
-- In **mock mode**, `mockFn()` (from `src/mockData.ts`) returns the data.
-- In **live mode**, the same call `POST`s `payload` to `SNOWBLL_API_URL + endpoint`
-  with `Authorization: Bearer <SNOWBLL_API_KEY>` and returns the JSON response.
+- `snowbll login` — sign in with an email+password Snowbll account; mints and stores a key in `~/.snowbll/config.json`.
+- Accounts created with Google/Discord have no password: ask the Snowbll team for a preview key, then `snowbll setup` to paste it.
+- `snowbll keys list|create|revoke` manages keys; `SNOWBLL_API_KEY` env always wins over the stored key.
 
-To wire up the real Snowbll API, implement those endpoints to match the response
-shapes in `src/mockData.ts` (exported as TypeScript interfaces) and set
-`SNOWBLL_USE_MOCK=false`. No changes to `index.ts` are required.
+Keep keys out of browser code, public repos, and shared transcripts.
 
-## Project layout
+## Configuration
 
-```
-snowbll-mcp/
-  package.json
-  tsconfig.json
-  README.md
-  src/
-    index.ts           # MCP server: registers tools, resources & prompts over stdio
-    client.ts          # game data layer: mock-by-default, future real-API client
-    communityClient.ts # community/forum data layer (Community Recommendation Engine)
-    mockData.ts        # typed mock dataset + helpers (game response shapes)
-    schemas.ts         # zod output schemas (structured output) + type-sync guard
-    resources.ts       # MCP resources (player snapshots)
-    prompts.ts         # MCP prompts (slash-command templates)
-    http.ts            # HTTP helper: timeout, retry, typed errors
-  test/                # node:test suite (npm test)
-```
+| Env var | Default | Purpose |
+| --- | --- | --- |
+| `SNOWBLL_API_KEY` | – | Developer-preview API key |
+| `SNOWBLL_API_BASE` | `https://www.snowbll.com` | API origin (point at a local dev server while developing) |
 
-## Tech stack
+## REST instead?
 
-TypeScript (strict, ESM) · Node.js ≥ 18 · `@modelcontextprotocol/sdk` · `zod` ·
-stdio MCP transport.
+Everything the tools do is plain HTTP — `POST https://www.snowbll.com/api/search` is live with no key. Full docs: <https://www.snowbll.com/docs>.
 
 ## License
 

package/dist/api.js

@@ -0,0 +1,138 @@
+import { getApiBase, getApiKey, getSupabaseAnonKey, getSupabaseUrl } from "./config.js";
+/**
+ * Thin client for the live Snowbll API.
+ *
+ * Two surfaces, as documented at https://www.snowbll.com/docs:
+ *  - public endpoints (no key): POST /api/search, GET /api/forge/campaigns[/:id]
+ *  - keyed v1 (developer preview): /api/v1/* with `Authorization: Bearer sb_...`
+ *
+ * Methods prefer the keyed surface when a key is configured and fall back to
+ * the public one when the data is public anyway, so search and Forge browsing
+ * work with zero setup.
+ */
+export class SnowbllApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "SnowbllApiError";
+    }
+}
+async function request(path, options = {}) {
+    const { method = "GET", body, key, timeoutMs = 30_000 } = options;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let res;
+    try {
+        res = await fetch(`${getApiBase()}${path}`, {
+            method,
+            headers: {
+                "content-type": "application/json",
+                ...(key ? { authorization: `Bearer ${key}` } : {}),
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        clearTimeout(timer);
+        if (controller.signal.aborted)
+            throw new SnowbllApiError(0, `Request timed out after ${timeoutMs}ms.`);
+        throw new SnowbllApiError(0, `Network error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    clearTimeout(timer);
+    let json = null;
+    try {
+        json = await res.json();
+    }
+    catch {
+        // Non-JSON body — fall through to the status check.
+    }
+    if (!res.ok) {
+        const msg = json && typeof json === "object" && typeof json.error === "string"
+            ? json.error
+            : `HTTP ${res.status}`;
+        throw new SnowbllApiError(res.status, msg);
+    }
+    return json;
+}
+const NEEDS_KEY = "This needs an API key. Run `snowbll login` (email+password account) or `snowbll setup` to paste one — see https://www.snowbll.com/docs.";
+function requireKey() {
+    const key = getApiKey();
+    if (!key)
+        throw new SnowbllApiError(401, NEEDS_KEY);
+    return key;
+}
+// ─── Catalog ────────────────────────────────────────────────────────────────
+export async function searchGames(query, limit = 5) {
+    const key = getApiKey();
+    if (key)
+        return request("/api/v1/search", { method: "POST", body: { query, limit }, key });
+    // The public search endpoint ignores `limit` (returns up to 5) — trim client-side
+    // so keyless callers still get what they asked for.
+    const data = (await request("/api/search", { method: "POST", body: { query } }));
+    if (Array.isArray(data.results) && limit < data.results.length) {
+        return { ...data, results: data.results.slice(0, Math.max(1, Math.floor(limit))) };
+    }
+    return data;
+}
+export function getGame(gameId) {
+    const id = encodeURIComponent(gameId);
+    const key = getApiKey();
+    // Game detail is public, recommendation-grade data: use the keyed v1 endpoint
+    // when a key is set, else the public keyless one — so get_game works with zero
+    // setup, matching the hosted MCP server (only get_persona is a paid tool).
+    if (key)
+        return request(`/api/v1/games/${id}`, { key });
+    return request(`/api/games/${id}`);
+}
+export function listGames(limit = 20, offset = 0) {
+    return request(`/api/v1/games?limit=${limit}&offset=${offset}`, { key: requireKey() });
+}
+// ─── The Forge ──────────────────────────────────────────────────────────────
+export function listForgeCampaigns(status) {
+    const qs = status ? `?status=${encodeURIComponent(status)}` : "";
+    const key = getApiKey();
+    if (key)
+        return request(`/api/v1/forge/campaigns${qs}`, { key });
+    return request(`/api/forge/campaigns${qs}`);
+}
+export function getForgeCampaign(campaignId) {
+    const id = encodeURIComponent(campaignId);
+    const key = getApiKey();
+    if (key)
+        return request(`/api/v1/forge/campaigns/${id}`, { key });
+    return request(`/api/forge/campaigns/${id}`);
+}
+// ─── Persona + account ──────────────────────────────────────────────────────
+export function getPersona(playerId = "me") {
+    return request(`/api/v1/personas/${encodeURIComponent(playerId)}`, { key: requireKey() });
+}
+export function whoami() {
+    return request("/api/v1/me", { key: requireKey() });
+}
+// ─── Key management (Supabase account auth, not API-key auth) ───────────────
+/** Sign in with a Snowbll email+password account; returns a Supabase access token. */
+export async function supabaseLogin(email, password) {
+    const res = await fetch(`${getSupabaseUrl()}/auth/v1/token?grant_type=password`, {
+        method: "POST",
+        headers: { "content-type": "application/json", apikey: getSupabaseAnonKey() },
+        body: JSON.stringify({ email, password }),
+    });
+    const json = (await res.json().catch(() => ({})));
+    if (!res.ok || !json.access_token) {
+        throw new SnowbllApiError(res.status, json.error_description ||
+            json.msg ||
+            "Sign-in failed. Accounts created with Google/Discord have no password — ask the Snowbll team for a preview key instead.");
+    }
+    return json.access_token;
+}
+export function createKey(accessToken, name) {
+    return request("/api/v1/keys", { method: "POST", body: { name }, key: accessToken });
+}
+export function listKeys(accessToken) {
+    return request("/api/v1/keys", { key: accessToken });
+}
+export function revokeKey(accessToken, id) {
+    return request(`/api/v1/keys/${encodeURIComponent(id)}`, { method: "DELETE", key: accessToken });
+}

package/dist/bin/snowbll-mcp.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { runStdioServer } from "../server.js";
+import { runSetup } from "../setup.js";
+const require = createRequire(import.meta.url);
+const { version } = require("../../package.json");
+/**
+ * `npx snowbll-mcp`        — run the MCP server on stdio (what agents launch)
+ * `npx snowbll-mcp setup`  — interactive setup wizard
+ */
+const arg = process.argv[2];
+if (arg === "setup") {
+    runSetup().catch((err) => {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    });
+}
+else if (arg === "--version" || arg === "-v") {
+    console.log(version);
+}
+else if (arg && arg !== "serve") {
+    console.error(`Unknown command '${arg}'. Usage: snowbll-mcp [setup|serve|--version]`);
+    process.exit(1);
+}
+else {
+    runStdioServer(version).catch((err) => {
+        console.error(`[snowbll-mcp] fatal: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    });
+}

package/dist/bin/snowbll.js

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+import { createInterface } from "node:readline/promises";
+import { createRequire } from "node:module";
+import { createKey, getForgeCampaign, getGame, getPersona, listForgeCampaigns, listGames, listKeys, revokeKey, searchGames, SnowbllApiError, supabaseLogin, whoami, } from "../api.js";
+import { clearConfig, getApiBase, writeConfig } from "../config.js";
+import { runStdioServer } from "../server.js";
+import { runSetup } from "../setup.js";
+const require = createRequire(import.meta.url);
+const { version } = require("../../package.json");
+/** The `snowbll` CLI — the live Snowbll API from your terminal. */
+const HELP = `snowbll v${version} — Snowbll from your terminal (live API: ${getApiBase()})
+
+Usage:
+  snowbll search "<query>" [--limit N] [--json]   Natural-language game search
+  snowbll game <id> [--json]                      One game's full metadata
+  snowbll games [--limit N] [--offset N] [--json] Plain catalog listing (key)
+  snowbll forge [id] [--status live] [--json]     Forge campaigns / one campaign
+  snowbll persona [--json]                        Your gaming persona (key)
+  snowbll whoami [--json]                         Who the configured key belongs to
+  snowbll login                                   Sign in, mint + store an API key
+  snowbll logout                                  Forget the stored key
+  snowbll keys list|create [name]|revoke <id>     Manage your API keys (sign-in)
+  snowbll setup                                   Setup wizard + agent MCP configs
+  snowbll mcp                                     Run the MCP server on stdio
+  snowbll help | --version
+
+Search, game, and forge work without a key; the rest use the developer-preview
+keyed API (run \`snowbll login\` or set SNOWBLL_API_KEY). Docs: https://www.snowbll.com/docs`;
+function parseFlags(args) {
+    const flags = { json: false, rest: [] };
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--json")
+            flags.json = true;
+        else if (a === "--limit")
+            flags.limit = Number(args[++i]);
+        else if (a === "--offset")
+            flags.offset = Number(args[++i]);
+        else if (a === "--status")
+            flags.status = args[++i];
+        else
+            flags.rest.push(a);
+    }
+    return flags;
+}
+const out = (value) => console.log(JSON.stringify(value, null, 2));
+function printSearch(data) {
+    const results = data.results ?? [];
+    if (!results.length) {
+        console.log("No matches.");
+        return;
+    }
+    console.log(`${results.length} match(es) — parsed by ${data.parsedBy ?? "?"}\n`);
+    for (const [i, r] of results.entries()) {
+        console.log(`${i + 1}. ${r.game.title}  [${r.game.genre}]  ${r.game.price} — ${r.game.verification}`);
+        console.log(`   id: ${r.game.id}`);
+        if (r.game.url)
+            console.log(`   ${r.game.url}`);
+        for (const reason of r.reasons)
+            console.log(`   • ${reason}`);
+        console.log("");
+    }
+}
+async function promptCredentials() {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const email = (await rl.question("Snowbll account email: ")).trim();
+    const password = await rl.question("Password (input is visible): ");
+    rl.close();
+    if (!email || !password)
+        throw new SnowbllApiError(400, "Email and password are both required.");
+    return { email, password };
+}
+async function main() {
+    const [command, ...args] = process.argv.slice(2);
+    const flags = parseFlags(args);
+    switch (command) {
+        case "search": {
+            const query = flags.rest.join(" ").trim();
+            if (!query)
+                throw new SnowbllApiError(400, 'Usage: snowbll search "<query>"');
+            const data = await searchGames(query, flags.limit ?? 5);
+            if (flags.json)
+                out(data);
+            else
+                printSearch(data);
+            return;
+        }
+        case "game": {
+            const id = flags.rest[0];
+            if (!id)
+                throw new SnowbllApiError(400, "Usage: snowbll game <id>");
+            out(await getGame(id));
+            return;
+        }
+        case "games": {
+            out(await listGames(flags.limit ?? 20, flags.offset ?? 0));
+            return;
+        }
+        case "forge": {
+            const id = flags.rest[0];
+            out(id ? await getForgeCampaign(id) : await listForgeCampaigns(flags.status));
+            return;
+        }
+        case "persona": {
+            out(await getPersona(flags.rest[0] ?? "me"));
+            return;
+        }
+        case "whoami": {
+            out(await whoami());
+            return;
+        }
+        case "login": {
+            const { email, password } = await promptCredentials();
+            const token = await supabaseLogin(email, password);
+            const machine = process.env.COMPUTERNAME || process.env.HOSTNAME || "cli";
+            const minted = await createKey(token, `cli-${machine}`.slice(0, 60));
+            writeConfig({ apiKey: minted.key });
+            console.log(`Signed in. API key ${minted.key_prefix}… minted and saved to ~/.snowbll/config.json`);
+            console.log("Verify with: snowbll whoami");
+            return;
+        }
+        case "logout": {
+            clearConfig();
+            console.log("Stored key forgotten. (Keys stay valid server-side — revoke with `snowbll keys revoke <id>`.)");
+            return;
+        }
+        case "keys": {
+            const [action, value] = flags.rest;
+            if (!action || !["list", "create", "revoke"].includes(action)) {
+                throw new SnowbllApiError(400, "Usage: snowbll keys list|create [name]|revoke <id>");
+            }
+            const { email, password } = await promptCredentials();
+            const token = await supabaseLogin(email, password);
+            if (action === "list")
+                out(await listKeys(token));
+            else if (action === "create") {
+                const minted = await createKey(token, value || "default");
+                console.log(`New key (shown once): ${minted.key}`);
+            }
+            else {
+                if (!value)
+                    throw new SnowbllApiError(400, "Usage: snowbll keys revoke <id>");
+                out(await revokeKey(token, value));
+            }
+            return;
+        }
+        case "setup": {
+            await runSetup();
+            return;
+        }
+        case "mcp": {
+            await runStdioServer(version);
+            // Keep the process alive — the MCP transport owns stdio from here.
+            return new Promise(() => { });
+        }
+        case "--version":
+        case "-v": {
+            console.log(version);
+            return;
+        }
+        case undefined:
+        case "help":
+        case "--help":
+        case "-h": {
+            console.log(HELP);
+            return;
+        }
+        default:
+            throw new SnowbllApiError(400, `Unknown command '${command}'. Run \`snowbll help\`.`);
+    }
+}
+main().catch((err) => {
+    if (err instanceof SnowbllApiError) {
+        console.error(`Error${err.status ? ` (${err.status})` : ""}: ${err.message}`);
+    }
+    else {
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    process.exit(1);
+});