levelbox-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Koh
+
+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

@@ -0,0 +1,147 @@
+# levelbox-mcp
+
+Open-source MCP bridge for **levelbox.ai** — connect your AI assistant (Claude Desktop, Claude Code, etc.) to the remote levelbox wheel screener over Model Context Protocol.
+
+This is a **client/bridge** that lets AI agents access the levelbox screener tools, not a server.
+
+## Install
+
+```bash
+npm install -g levelbox-mcp
+```
+
+## Quick Start
+
+### 1. Authenticate
+
+```bash
+levelbox-mcp login
+```
+
+This opens a browser to sign in with your **levelbox.ai** account (Google OAuth or email/password). Credentials are stored locally and auto-refresh.
+
+**Headless fallback** (e.g., on a remote machine without a browser):
+
+```bash
+levelbox-mcp login --token <access_token> --refresh <refresh_token>
+```
+
+### 2. Configure Your AI Assistant
+
+Add this block to your MCP configuration:
+
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "levelbox": {
+      "command": "npx",
+      "args": ["-y", "levelbox-mcp", "connect"]
+    }
+  }
+}
+```
+
+**Claude Code** (`.mcp.json` in your project, or globally via `claude mcp add`):
+
+```json
+{
+  "mcpServers": {
+    "levelbox": {
+      "command": "npx",
+      "args": ["-y", "levelbox-mcp", "connect"]
+    }
+  }
+}
+```
+
+Restart your assistant to load the levelbox tools.
+
+### 3. Use the Tools
+
+Your assistant now has access to:
+
+- **list_themes** — Browse available screener themes (filter types, criteria)
+- **list_candidates** — View screened candidates for a theme
+- **top_candidates** — Get the top N candidates by rank
+- **get_candidate** — Fetch details for a specific symbol
+- **pick_symbol** — Add a symbol to your watchlist
+- **unpick_symbol** — Remove a symbol from your watchlist
+- **list_picks** — View your current picks/watchlist
+
+**Analytical use only.** These tools provide market data, valuations, and signals to inform your analysis — not investment directives. Use them to research, backtest, and understand opportunities, then make your own decisions.
+
+## Commands
+
+- **`levelbox-mcp connect`** (default) — Start the MCP bridge (stdio). This is what the config block runs.
+- **`levelbox-mcp login`** — Authenticate with levelbox.ai (opens browser or accepts `--token`/`--refresh`).
+- **`levelbox-mcp logout`** — Clear stored credentials.
+- **`levelbox-mcp status`** — Show login status and configured base URL.
+
+## Configuration
+
+Set via environment variables or command-line flags. Flags override env vars.
+
+| Env Var                      | Flag                  | Default                        |
+| ---------------------------- | --------------------- | ------------------------------ |
+| `LEVELBOX_MCP_URL`           | `--base-url`          | `https://api.levelbox.ai/mcp`  |
+| `LEVELBOX_SUPABASE_URL`      | `--supabase-url`      | (from env, required for login) |
+| `LEVELBOX_SUPABASE_ANON_KEY` | `--supabase-anon-key` | (from env, required for login) |
+
+Example:
+
+```bash
+LEVELBOX_MCP_URL=http://localhost:8000/mcp levelbox-mcp connect
+# or
+levelbox-mcp --base-url http://localhost:8000/mcp connect
+```
+
+## Setup Note: Browser Login & OAuth
+
+For **Google OAuth** and other OAuth redirects to work, the **levelbox.ai Supabase project's Auth settings must allow localhost redirects**:
+
+1. Go to your Supabase project → **Authentication** → **URL Configuration**
+2. Add `http://localhost:*` and/or `http://127.0.0.1:*` to **Redirect URLs**
+
+**Email/password login works without this.**
+
+If you see an OAuth redirect error, check that these URLs are in your allowlist.
+
+## Troubleshooting
+
+### 401 "Not Logged In"
+
+The token has expired or refresh failed:
+
+```bash
+levelbox-mcp login
+```
+
+Re-authenticate to refresh your local credentials.
+
+### Connection refused
+
+Check that the base URL is correct:
+
+```bash
+levelbox-mcp status
+# Shows current base-url; update via LEVELBOX_MCP_URL or --base-url
+```
+
+### MCP tool not showing in your assistant
+
+Ensure the config block is in the right file:
+
+- **Claude Desktop:** `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
+- **Claude Code:** `.mcp.json` in your project root or globally (~/.claude/.mcp.json)
+
+Restart your assistant after updating the config.
+
+## License
+
+MIT — see LICENSE.
+
+## Repository
+
+https://github.com/danielkoh/levelbox-mcp

package/bin/levelbox-mcp.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import("../dist/cli.js");

package/dist/chunk-2CRXJH3H.js

@@ -0,0 +1,61 @@
+import {
+  getValidAccessToken
+} from "./chunk-K4KHIFRJ.js";
+
+// src/connect.ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+async function buildRemoteClient(cfg, token) {
+  const client = new Client({ name: "levelbox-mcp", version: "0.1.0" });
+  const transport = new StreamableHTTPClientTransport(new URL(cfg.baseUrl), {
+    requestInit: { headers: { Authorization: `Bearer ${token}` } }
+  });
+  await client.connect(transport);
+  return client;
+}
+function isUnauthorized(e) {
+  const s = String(e?.message ?? e);
+  return e?.status === 401 || /401|unauthor/i.test(s);
+}
+function makeHandlers(getRemote) {
+  let remotePromise = getRemote();
+  async function withRetry(fn) {
+    try {
+      return await fn(await remotePromise);
+    } catch (e) {
+      if (!isUnauthorized(e)) throw e;
+      remotePromise = getRemote(true);
+      return fn(await remotePromise);
+    }
+  }
+  return {
+    listTools: async () => withRetry((remote) => remote.listTools()),
+    callTool: async (params) => withRetry((remote) => remote.callTool(params))
+  };
+}
+async function runBridge(cfg) {
+  let remote = null;
+  const getRemote = async (forceRefresh = false) => {
+    if (remote && !forceRefresh) return remote;
+    const token = await getValidAccessToken(cfg);
+    remote = await buildRemoteClient(cfg, token);
+    return remote;
+  };
+  const h = makeHandlers(getRemote);
+  const server = new Server(
+    { name: "levelbox-mcp", version: "0.1.0" },
+    { capabilities: { tools: {} } }
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => h.listTools());
+  server.setRequestHandler(CallToolRequestSchema, async (req) => h.callTool(req.params));
+  await server.connect(new StdioServerTransport());
+}
+
+export {
+  buildRemoteClient,
+  makeHandlers,
+  runBridge
+};

package/dist/chunk-7A2TMCJM.js

@@ -0,0 +1,32 @@
+// src/auth/store.ts
+import { homedir } from "os";
+import { join } from "path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from "fs";
+function credsPath() {
+  return join(homedir(), ".levelbox", "credentials.json");
+}
+function readCreds() {
+  try {
+    return JSON.parse(readFileSync(credsPath(), "utf8"));
+  } catch {
+    return null;
+  }
+}
+function writeCreds(c) {
+  const dir = join(homedir(), ".levelbox");
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 448 });
+  writeFileSync(credsPath(), JSON.stringify(c, null, 2), { mode: 384 });
+}
+function clearCreds() {
+  try {
+    rmSync(credsPath());
+  } catch {
+  }
+}
+
+export {
+  credsPath,
+  readCreds,
+  writeCreds,
+  clearCreds
+};

package/dist/chunk-FYOY32WT.js

@@ -0,0 +1,22 @@
+// src/config.ts
+var DEFAULTS = {
+  baseUrl: "https://api.levelbox.ai/mcp",
+  supabaseUrl: "https://gmrkfqscgbxapaljfqve.supabase.co",
+  supabaseAnonKey: "sb_publishable__GLbOg-CpEqLuxtmlPab9g_wnE0IH_0"
+};
+function resolveConfig(flags = {}) {
+  const pick = (flag, env, dflt) => flag ?? env ?? dflt;
+  return {
+    baseUrl: pick(flags.baseUrl, process.env.LEVELBOX_MCP_URL, DEFAULTS.baseUrl),
+    supabaseUrl: pick(flags.supabaseUrl, process.env.LEVELBOX_SUPABASE_URL, DEFAULTS.supabaseUrl),
+    supabaseAnonKey: pick(
+      flags.supabaseAnonKey,
+      process.env.LEVELBOX_SUPABASE_ANON_KEY,
+      DEFAULTS.supabaseAnonKey
+    )
+  };
+}
+
+export {
+  resolveConfig
+};

package/dist/chunk-K4KHIFRJ.js

@@ -0,0 +1,29 @@
+import {
+  readCreds,
+  writeCreds
+} from "./chunk-7A2TMCJM.js";
+
+// src/auth/refresh.ts
+async function refreshTokens(cfg, refreshToken) {
+  const res = await fetch(`${cfg.supabaseUrl}/auth/v1/token?grant_type=refresh_token`, {
+    method: "POST",
+    headers: { apikey: cfg.supabaseAnonKey, "Content-Type": "application/json" },
+    body: JSON.stringify({ refresh_token: refreshToken })
+  });
+  if (!res.ok) throw new Error(`token refresh failed (${res.status}) \u2014 run: levelbox-mcp login`);
+  const j = await res.json();
+  return { accessToken: j.access_token, refreshToken: j.refresh_token, expiresAt: j.expires_at };
+}
+async function getValidAccessToken(cfg, now = Math.floor(Date.now() / 1e3)) {
+  const c = readCreds();
+  if (!c) throw new Error("not logged in \u2014 run: levelbox-mcp login");
+  if (c.expiresAt - now > 60) return c.accessToken;
+  const t = await refreshTokens(cfg, c.refreshToken);
+  writeCreds({ ...c, ...t });
+  return t.accessToken;
+}
+
+export {
+  refreshTokens,
+  getValidAccessToken
+};

package/dist/cli.d.ts

@@ -0,0 +1,18 @@
+import { Command } from 'commander';
+
+interface CliDeps {
+    connect: () => Promise<void>;
+    loginToken: (token: string, refresh: string) => Promise<void>;
+    loginBrowser: () => Promise<void>;
+    logout: () => Promise<void>;
+    status: () => Promise<void>;
+}
+interface GlobalOpts {
+    baseUrl?: string;
+    supabaseUrl?: string;
+    supabaseAnonKey?: string;
+}
+declare function buildProgram(deps: CliDeps): Command;
+declare function main(): Promise<void>;
+
+export { type CliDeps, type GlobalOpts, buildProgram, main };

package/dist/cli.js

@@ -0,0 +1,85 @@
+// src/cli.ts
+import { Command } from "commander";
+import { pathToFileURL } from "url";
+function buildProgram(deps) {
+  const program = new Command();
+  program.name("levelbox-mcp").description("MCP bridge for levelbox.ai \u2014 run as default to start the bridge").option("--base-url <url>", "levelbox API base URL").option("--supabase-url <url>", "Supabase project URL").option("--supabase-anon-key <key>", "Supabase anon key").exitOverride();
+  program.command("connect", { isDefault: true }).description("Start the MCP stdio bridge (default when no subcommand is given)").action(async () => {
+    await deps.connect();
+  });
+  program.command("login").description("Authenticate with levelbox.ai").option("--token <access_token>", "Access token (paste mode)").option("--refresh <refresh_token>", "Refresh token (required with --token)").action(async (opts) => {
+    if (opts.token && opts.refresh) {
+      await deps.loginToken(opts.token, opts.refresh);
+    } else {
+      await deps.loginBrowser();
+    }
+  });
+  program.command("logout").description("Remove stored credentials").action(async () => {
+    await deps.logout();
+  });
+  program.command("status").description("Show current auth status and configured base URL").action(async () => {
+    await deps.status();
+  });
+  return program;
+}
+async function main() {
+  const { resolveConfig } = await import("./config-2FXMX7WT.js");
+  const { runBridge } = await import("./connect-4G7SN4WT.js");
+  const { loginWithToken, loginWithBrowser } = await import("./login-3K4VUHVG.js");
+  const { clearCreds, readCreds } = await import("./store-O2JHTLQU.js");
+  let cfg = resolveConfig();
+  const deps = {
+    connect: async () => {
+      await runBridge(cfg);
+    },
+    loginToken: async (token, refresh) => {
+      await loginWithToken(cfg, token, refresh);
+      process.stderr.write("levelbox-mcp: logged in (token)\n");
+    },
+    loginBrowser: async () => {
+      await loginWithBrowser(cfg);
+      process.stderr.write("levelbox-mcp: logged in (browser)\n");
+    },
+    logout: async () => {
+      clearCreds();
+      process.stderr.write("levelbox-mcp: credentials removed\n");
+    },
+    status: async () => {
+      const creds = readCreds();
+      const now = Math.floor(Date.now() / 1e3);
+      if (!creds) {
+        process.stderr.write(`levelbox-mcp: not logged in
+base-url: ${cfg.baseUrl}
+`);
+      } else {
+        const valid = creds.expiresAt > now;
+        process.stderr.write(
+          `levelbox-mcp: logged in
+account: ${creds.supabaseUrl}
+token valid: ${valid}
+base-url: ${cfg.baseUrl}
+`
+        );
+      }
+    }
+  };
+  const program = buildProgram(deps);
+  program.hook("preAction", () => {
+    const opts = program.opts();
+    cfg = resolveConfig(opts);
+  });
+  await program.parseAsync(process.argv);
+}
+var argv1 = process.argv[1] ?? "";
+var isEntry = argv1.endsWith("/levelbox-mcp") || argv1.endsWith("/levelbox-mcp.mjs") || pathToFileURL(argv1).href === import.meta.url;
+if (isEntry) {
+  main().catch((err) => {
+    process.stderr.write(`levelbox-mcp: ${String(err)}
+`);
+    process.exit(1);
+  });
+}
+export {
+  buildProgram,
+  main
+};

package/dist/config-2FXMX7WT.js

@@ -0,0 +1,6 @@
+import {
+  resolveConfig
+} from "./chunk-FYOY32WT.js";
+export {
+  resolveConfig
+};

package/dist/connect-4G7SN4WT.js

@@ -0,0 +1,12 @@
+import {
+  buildRemoteClient,
+  makeHandlers,
+  runBridge
+} from "./chunk-2CRXJH3H.js";
+import "./chunk-K4KHIFRJ.js";
+import "./chunk-7A2TMCJM.js";
+export {
+  buildRemoteClient,
+  makeHandlers,
+  runBridge
+};

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+
+interface LevelboxConfig {
+    baseUrl: string;
+    supabaseUrl: string;
+    supabaseAnonKey: string;
+}
+declare function resolveConfig(flags?: Partial<LevelboxConfig>): LevelboxConfig;
+
+declare function createLevelboxClient(flags?: Partial<LevelboxConfig> & {
+    token?: string;
+}): Promise<Client>;
+
+export { type LevelboxConfig, createLevelboxClient, resolveConfig };

package/dist/index.js

@@ -0,0 +1,22 @@
+import {
+  resolveConfig
+} from "./chunk-FYOY32WT.js";
+import {
+  buildRemoteClient
+} from "./chunk-2CRXJH3H.js";
+import {
+  getValidAccessToken
+} from "./chunk-K4KHIFRJ.js";
+import "./chunk-7A2TMCJM.js";
+
+// src/lib.ts
+async function createLevelboxClient(flags = {}) {
+  const { token, ...configFlags } = flags;
+  const cfg = resolveConfig(configFlags);
+  const accessToken = token ?? await getValidAccessToken(cfg);
+  return buildRemoteClient(cfg, accessToken);
+}
+export {
+  createLevelboxClient,
+  resolveConfig
+};

package/dist/login-3K4VUHVG.js

@@ -0,0 +1,235 @@
+import {
+  refreshTokens
+} from "./chunk-K4KHIFRJ.js";
+import {
+  writeCreds
+} from "./chunk-7A2TMCJM.js";
+
+// src/auth/login.ts
+import { createServer } from "http";
+function requireSupabaseConfig(cfg) {
+  if (!cfg.supabaseUrl || !cfg.supabaseAnonKey) {
+    throw new Error(
+      "supabase not configured \u2014 set LEVELBOX_SUPABASE_URL and LEVELBOX_SUPABASE_ANON_KEY (or pass --supabase-url / --supabase-anon-key)"
+    );
+  }
+}
+function handleCallbackBody(cfg, body) {
+  if (typeof body.access_token !== "string" || body.access_token === "" || typeof body.refresh_token !== "string" || body.refresh_token === "" || typeof body.expires_at !== "number") {
+    throw new Error("invalid session from login page");
+  }
+  return {
+    accessToken: body.access_token,
+    refreshToken: body.refresh_token,
+    expiresAt: body.expires_at,
+    supabaseUrl: cfg.supabaseUrl
+  };
+}
+function buildLoginPage(supabaseUrl, supabaseAnonKey) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>levelbox.ai \u2014 Sign in</title>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+      background: #0f1117;
+      color: #e1e4e8;
+      min-height: 100vh;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+    }
+    .card {
+      background: #161b22;
+      border: 1px solid #30363d;
+      border-radius: 12px;
+      padding: 40px;
+      width: 100%;
+      max-width: 380px;
+    }
+    h1 { font-size: 1.4rem; font-weight: 600; margin-bottom: 8px; }
+    p.tagline { color: #8b949e; font-size: 0.9rem; margin-bottom: 28px; }
+    button, input[type="email"], input[type="password"] {
+      width: 100%;
+      padding: 10px 14px;
+      border-radius: 6px;
+      font-size: 0.95rem;
+      border: 1px solid #30363d;
+      outline: none;
+    }
+    input[type="email"], input[type="password"] {
+      background: #0d1117;
+      color: #e1e4e8;
+      margin-bottom: 10px;
+    }
+    button {
+      cursor: pointer;
+      font-weight: 600;
+      border: none;
+      margin-bottom: 10px;
+    }
+    #btn-google { background: #238636; color: #fff; }
+    #btn-google:hover { background: #2ea043; }
+    #btn-email { background: #21262d; color: #e1e4e8; border: 1px solid #30363d; }
+    #btn-email:hover { background: #30363d; }
+    .divider { text-align: center; color: #8b949e; font-size: 0.8rem; margin: 14px 0; }
+    #status { margin-top: 16px; font-size: 0.9rem; color: #8b949e; text-align: center; }
+    #status.error { color: #f85149; }
+    #status.success { color: #3fb950; }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <h1>levelbox.ai</h1>
+    <p class="tagline">Get paid to wait for your price</p>
+
+    <button id="btn-google">Continue with Google</button>
+
+    <div class="divider">or</div>
+
+    <input type="email" id="email" placeholder="Email address" autocomplete="email" />
+    <input type="password" id="password" placeholder="Password" autocomplete="current-password" />
+    <button id="btn-email">Sign in with Email</button>
+
+    <div id="status"></div>
+  </div>
+
+  <script type="module">
+    // Config injected by the CLI server
+    window.__LVB = { url: ${JSON.stringify(supabaseUrl)}, anon: ${JSON.stringify(supabaseAnonKey)} };
+
+    import { createClient } from "https://esm.sh/@supabase/supabase-js@2.45.4";
+
+    const supabase = createClient(window.__LVB.url, window.__LVB.anon);
+
+    const status = document.getElementById("status");
+
+    function setStatus(msg, kind) {
+      status.textContent = msg;
+      status.className = kind || "";
+    }
+
+    // Listen for successful sign-in and POST the session to the local callback
+    supabase.auth.onAuthStateChange(async (event, session) => {
+      if (event === "SIGNED_IN" && session) {
+        setStatus("Sending credentials to CLI\u2026");
+        try {
+          const res = await fetch("/callback", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+              access_token: session.access_token,
+              refresh_token: session.refresh_token,
+              expires_at: session.expires_at,
+            }),
+          });
+          if (res.ok) {
+            setStatus("You can close this tab.", "success");
+          } else {
+            setStatus("CLI callback failed (" + res.status + "). Please retry.", "error");
+          }
+        } catch (err) {
+          setStatus("Could not reach CLI: " + String(err), "error");
+        }
+      }
+    });
+
+    document.getElementById("btn-google").addEventListener("click", async () => {
+      setStatus("Redirecting to Google\u2026");
+      const { error } = await supabase.auth.signInWithOAuth({
+        provider: "google",
+        options: { redirectTo: location.origin },
+      });
+      if (error) setStatus(error.message, "error");
+    });
+
+    document.getElementById("btn-email").addEventListener("click", async () => {
+      const email = document.getElementById("email").value.trim();
+      const password = document.getElementById("password").value;
+      if (!email || !password) { setStatus("Enter email and password.", "error"); return; }
+      setStatus("Signing in\u2026");
+      const { error } = await supabase.auth.signInWithPassword({ email, password });
+      if (error) setStatus(error.message, "error");
+    });
+  </script>
+</body>
+</html>`;
+}
+async function loginWithBrowser(cfg) {
+  requireSupabaseConfig(cfg);
+  const { default: open } = await import("open");
+  const html = buildLoginPage(cfg.supabaseUrl, cfg.supabaseAnonKey);
+  return new Promise((resolve, reject) => {
+    const TIMEOUT_MS = 12e4;
+    const server = createServer((req, res) => {
+      if (req.method === "GET" && req.url === "/") {
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(html);
+        return;
+      }
+      if (req.method === "POST" && req.url === "/callback") {
+        const chunks = [];
+        req.on("data", (chunk) => chunks.push(chunk));
+        req.on("end", () => {
+          clearTimeout(timer);
+          try {
+            const body = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+            writeCreds(handleCallbackBody(cfg, body));
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ ok: true }));
+            server.close();
+            resolve();
+          } catch (err) {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: String(err) }));
+            server.close();
+            reject(err instanceof Error ? err : new Error(String(err)));
+          }
+        });
+        return;
+      }
+      res.writeHead(404);
+      res.end();
+    });
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      if (!addr || typeof addr === "string") {
+        reject(new Error("Failed to get server address"));
+        return;
+      }
+      const url = `http://127.0.0.1:${addr.port}`;
+      open(url).catch(() => {
+      });
+      process.stderr.write(`
+Open this URL in your browser to sign in:
+  ${url}
+
+`);
+    });
+    const timer = setTimeout(() => {
+      server.close();
+      reject(new Error("Browser login timed out after 120 seconds"));
+    }, TIMEOUT_MS);
+    timer.unref();
+  });
+}
+async function loginWithToken(cfg, _accessToken, refreshToken) {
+  requireSupabaseConfig(cfg);
+  const t = await refreshTokens(cfg, refreshToken);
+  writeCreds({
+    accessToken: t.accessToken,
+    refreshToken: t.refreshToken,
+    expiresAt: t.expiresAt,
+    supabaseUrl: cfg.supabaseUrl
+  });
+}
+export {
+  handleCallbackBody,
+  loginWithBrowser,
+  loginWithToken,
+  requireSupabaseConfig
+};

package/dist/store-O2JHTLQU.js

@@ -0,0 +1,12 @@
+import {
+  clearCreds,
+  credsPath,
+  readCreds,
+  writeCreds
+} from "./chunk-7A2TMCJM.js";
+export {
+  clearCreds,
+  credsPath,
+  readCreds,
+  writeCreds
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "levelbox-mcp",
+  "version": "0.1.0",
+  "description": "Open-source MCP bridge for levelbox.ai — connect your AI assistant to the levelbox wheel screener.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "levelbox-mcp": "bin/levelbox-mcp.mjs"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "bin",
+    "skill",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "lint": "eslint . && prettier --check .",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1",
+    "@supabase/supabase-js": "^2",
+    "commander": "^12",
+    "open": "^10"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "eslint": "^9",
+    "prettier": "^3",
+    "tsup": "^8",
+    "typescript": "^5",
+    "typescript-eslint": "^8",
+    "vitest": "^2"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: levelbox-mcp
+description: Open-source MCP client bridge to levelbox.ai wheel screener — install, login, add config, access screening tools.
+---
+
+# levelbox-mcp
+
+## What it is
+
+A client/bridge that connects your AI assistant to **levelbox.ai**, an options wheel screener. It exposes screener tools over Model Context Protocol so Claude (Desktop, Code, or other AI apps) can query candidates, themes, and manage your picks.
+
+## Install & Setup
+
+### Step 1: Install the CLI
+
+```bash
+npm install -g levelbox-mcp
+```
+
+### Step 2: Authenticate
+
+```bash
+levelbox-mcp login
+```
+
+Opens a browser to sign in with your levelbox.ai account (Google OAuth or email/password). Credentials auto-refresh locally.
+
+### Step 3: Add the MCP Config Block
+
+Add to your Claude Desktop / Claude Code MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "levelbox": {
+      "command": "npx",
+      "args": ["-y", "levelbox-mcp", "connect"]
+    }
+  }
+}
+```
+
+- **Claude Desktop:** `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
+- **Claude Code:** `.mcp.json` in project root or `~/.claude/.mcp.json`
+
+Restart your assistant.
+
+### Step 4: Use the Tools
+
+Your assistant now has access to the levelbox screener:
+
+- **list_themes** — Browse screening themes
+- **list_candidates** — Get candidates for a theme
+- **top_candidates** — Top N candidates by rank
+- **get_candidate** — Details for a symbol
+- **pick_symbol** — Add to watchlist
+- **unpick_symbol** — Remove from watchlist
+- **list_picks** — View your picks
+
+## Important
+
+**Analytical use only.** These tools provide market data, analysis, and signals — not investment advice. Use them to research and understand opportunities. You decide what to do.
+
+## Troubleshooting
+
+- **401 "Not logged in"?** Run `levelbox-mcp login` to refresh credentials.
+- **Browser login fails with OAuth error?** Check that your Supabase project's **Auth > URL Configuration** allows `http://localhost:*` (email/password works without it).
+- **Not seeing tools?** Restart your AI assistant and verify the config block is in the right file.
+
+## Env Vars
+
+- `LEVELBOX_MCP_URL` (default: `https://api.levelbox.ai/mcp`)
+- `LEVELBOX_SUPABASE_URL` (required for login)
+- `LEVELBOX_SUPABASE_ANON_KEY` (required for login)
+
+Or use flags: `--base-url`, `--supabase-url`, `--supabase-anon-key`.
+
+---
+
+**Repo:** https://github.com/danielkoh/levelbox-mcp