first-light-mcp 1.0.0

package/README.md

@@ -0,0 +1,148 @@
+# First Light MCP
+
+Native AI access to **BTX (Byron Bay pool) chain intelligence**. This is a
+[Model Context Protocol](https://modelcontextprotocol.io) server that exposes the
+First Light / BTX explorer REST API as a catalog of self-describing tools, so any
+MCP client — Claude Desktop, an IDE agent, or your own framework — can connect and
+query BTX data natively, without hand-building HTTP calls.
+
+It is a **thin, stateless translation layer**. It holds no chain data and makes no
+auth decisions of its own: each tool call maps to one authenticated request against
+the live API (`https://api-explorer.btxbyronbay.com/api`), forwarding your Bearer
+token unchanged, and returns the JSON **with its `caveat` intact**.
+
+## Neutral-facts contract
+
+Every tool returns **provable on-chain observations only** — never identity,
+ownership, holdings, counterparty, accusation, risk verdict, or advice. Each result
+is wrapped as:
+
+```jsonc
+{
+  "observation": { /* the API payload */ },
+  "caveat": "Neutral on-chain facts only. No entity names, identity, ownership, …",
+  "framing": "This is an on-chain observation, not a statement of identity, …"
+}
+```
+
+The `caveat` comes from the API; if an endpoint omits one, the canonical caveat is
+injected so **no result ever leaves without it**. This contract is also stated once
+in the server's `instructions`, advertised to the model at connect time.
+
+## Requirements
+
+- Node.js **18+** (uses global `fetch`).
+- Optional: a First Light **Bearer token** for PRO/Enterprise tools. Public tools
+  work with no token.
+
+## Install
+
+```bash
+# Run directly with npx (no install):
+npx first-light-mcp
+
+# …or install globally:
+npm install -g first-light-mcp
+first-light-mcp
+
+# …or from this folder:
+npm install
+npm start
+```
+
+The server speaks MCP over **stdio** — an MCP client launches it as a subprocess.
+Running it in a plain terminal just prints a readiness line to stderr and then waits
+for JSON-RPC on stdin (that's expected; press Ctrl-C to exit).
+
+## Configure your token
+
+Set the token in the environment the client launches the server with:
+
+| Variable | Purpose |
+|---|---|
+| `FIRST_LIGHT_TOKEN` | Your `flp_…` Bearer key. Sent as `Authorization: Bearer <token>` on every call. Omit for public-only use. |
+| `FIRST_LIGHT_API_BASE` | Optional API base override (default `https://api-explorer.btxbyronbay.com/api`). |
+| `FIRST_LIGHT_TIMEOUT_MS` | Optional per-request timeout in ms (default `30000`). |
+
+If a PRO/Enterprise tool is called without a usable token, the result is a clean
+`{ "error": "auth", "detail": "This tool needs a PRO/Enterprise token…" }` object
+(a `403` from the API surfaces as `{ "error": "tier", … }`) — not data.
+
+## Add to Claude Desktop
+
+Edit `claude_desktop_config.json`:
+
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```jsonc
+{
+  "mcpServers": {
+    "first-light": {
+      "command": "npx",
+      "args": ["-y", "first-light-mcp"],
+      "env": {
+        "FIRST_LIGHT_TOKEN": "flp_your_token_here"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The First Light tools appear in the tools (plug) menu.
+
+> Prefer not to use `npx`? Set `"command": "node"` and
+> `"args": ["C:/path/to/first-light-mcp/src/index.js"]` (or the global
+> `"command": "first-light-mcp"` after `npm install -g`).
+
+The same block works for any MCP client that uses the standard
+`command` / `args` / `env` stdio launcher (Cline, Continue, custom SDK clients, …).
+
+## Tools
+
+Public tools (🟢) need no token. Gated tools (🔒) need a PRO/Enterprise token.
+
+### Public chain
+| Tool | Endpoint | What it answers |
+|---|---|---|
+| 🟢 `network_glance` | `/network/glance` | Height, interval, difficulty, supply, hashrate right now. |
+| 🟢 `get_block` | `/block/{ident}` | Block detail by height **or** hash. |
+| 🟢 `get_tx` | `/tx/{txid}` | Transaction detail with prevouts resolved. |
+| 🟢 `get_address` | `/address/{addr}` | Address aggregate + paginated tx rows (`page`). |
+| 🟢 `blocks_latest` | `/blocks/latest` | Latest N blocks (`n`). |
+| 🟢 `txs_latest` | `/txs/latest` | Latest N confirmed txs (`n`). |
+| 🟢 `search` | `/search` | Resolve a height / hash / txid / address (`q`). |
+| 🟢 `network_supply` | `/network/supply` | Emission & halving analytic. |
+| 🟢 `mempool` | `/mempool` | Mempool summary + recent entries. |
+
+### Market / data
+| Tool | Endpoint | What it answers |
+|---|---|---|
+| 🟢 `market_summary` | `/market/summary` | Live exchange (SafeTrade) bid/ask/mid/last — indicative, thin market. |
+| 🔒 `liquidity` | `/pro/liquidity` | On-chain liquidity funnel: available-float estimate vs venue depth. |
+| 🔒 `usage` | `/pro/usage` | BTX usage view — neutral activity categories & trends. |
+| 🟢 `wbtx_summary` | `/wbtx/summary` | wBTX bridge summary, both chains (testnet backing signal). |
+| 🟢 `supply_demand` | `/supply-demand` | Supply map: cohorts, net-flow, HODL waves (`window`, `price=model\|market`). |
+
+### Provenance
+| Tool | Endpoint | What it answers |
+|---|---|---|
+| 🟢 `trace` | `/trace/{txid}` | Bounded fund tracer forward/back over the spend index (`dir`, `hops`). |
+| 🔒 `cluster` | `/cluster/{addr}` | Co-spend set — **NOT** proof of common ownership (`format`). |
+
+> `trace` and `cluster` are the provenance lenses. `trace` is a public bounded
+> tracer (a token unlocks deeper tiers); `cluster` requires a PRO/Enterprise token.
+
+## What this is / isn't
+
+- **Is:** a stateless stdio adapter over the live First Light API; reuses the API's
+  existing auth, rate limits, tier gates, and neutral caveats verbatim.
+- **Isn't:** a data store, a second source of truth, or an auth bypass. Every gate
+  is decided downstream by the API.
+
+A **hosted remote-MCP variant** (HTTP/SSE, so cloud agents can connect without
+running a subprocess) is a possible follow-up; this package is the stdio server.
+
+## License
+
+MIT.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "first-light-mcp",
+  "version": "1.0.0",
+  "description": "Model Context Protocol server exposing the First Light / BTX explorer chain-intelligence API as native, self-describing AI tools. Neutral on-chain facts only — every result carries its caveat.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "first-light-mcp": "src/index.js"
+  },
+  "main": "src/index.js",
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "check": "node --check src/index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "btx",
+    "blockchain",
+    "explorer",
+    "first-light",
+    "chain-intelligence",
+    "claude"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,474 @@
+#!/usr/bin/env node
+/**
+ * First Light MCP server
+ * ----------------------
+ * A thin, stateless Model Context Protocol (stdio) server that turns the First
+ * Light / BTX explorer REST API into native, self-describing AI tools.
+ *
+ * It holds no chain data and makes no auth decisions of its own: every request
+ * is forwarded to the live API (https://api-explorer.btxbyronbay.com/api) with
+ * the caller's `FIRST_LIGHT_TOKEN` as `Authorization: Bearer <token>`. Every gate
+ * (401 / 403 / 429) is decided downstream by the API. Every result is returned
+ * with its neutral `caveat` intact — provable on-chain facts only, never identity,
+ * ownership, holdings, or a risk verdict.
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+const API_BASE = (
+  process.env.FIRST_LIGHT_API_BASE || "https://api-explorer.btxbyronbay.com/api"
+).replace(/\/+$/, "");
+const TOKEN = process.env.FIRST_LIGHT_TOKEN || "";
+const NAME = "first-light-mcp";
+const VERSION = "1.0.0";
+const REQUEST_TIMEOUT_MS = Number(process.env.FIRST_LIGHT_TIMEOUT_MS || 30000);
+
+// The neutral-facts contract, injected on any payload that lacks its own caveat
+// (e.g. some public endpoints) so no tool result ever leaves without one.
+const CANONICAL_CAVEAT =
+  "Neutral on-chain facts only. No entity names, identity, ownership, holdings, " +
+  "or risk/taint claims are asserted or implied.";
+
+// Framing string attached to EVERY tool result, so the model reasons over the
+// observation as an observation — never as an accusation, verdict, or advice.
+const FRAMING =
+  "This is an on-chain observation, not a statement of identity, ownership, " +
+  "counterparty, holdings, risk, or a recommendation. Do not present it as an " +
+  "accusation, a compliance determination, or advice.";
+
+const SERVER_INSTRUCTIONS = [
+  "First Light MCP exposes the BTX (Byron Bay pool) explorer chain-intelligence API",
+  "as native tools. It is a stateless translation layer over the live REST API.",
+  "",
+  "NEUTRAL-FACTS CONTRACT (hard product principle): every tool returns provable",
+  "on-chain observations ONLY. Never present a result as an identity, ownership,",
+  "holdings, counterparty, accusation, risk verdict, or advice. Each result carries",
+  "a `caveat` field (from the API, or the canonical caveat if the endpoint omits one)",
+  "and a `framing` note — surface them; do not strip, summarize, or relocate them.",
+  "",
+  "AUTH: public tools work with no token. Tools marked PRO/Enterprise require a valid",
+  "`FIRST_LIGHT_TOKEN` (Bearer key). If a gated tool is called without a usable token",
+  "the result is a clean `{ error: 'auth' | 'tier', ... }` object, not data.",
+].join("\n");
+
+// ---------------------------------------------------------------------------
+// Tool registry — one tool = one question. Each entry:
+//   name, gated (needs a token), description (LLM-facing, ends with neutrality),
+//   inputSchema (JSON Schema), build(args) -> { path, query }
+// ---------------------------------------------------------------------------
+
+const S = (props = {}, required = []) => ({
+  type: "object",
+  properties: props,
+  required,
+  additionalProperties: false,
+});
+
+const TOOLS = [
+  // ---- Public chain -------------------------------------------------------
+  {
+    name: "network_glance",
+    gated: false,
+    description:
+      "Network glance: current height, block interval/target, difficulty, circulating supply, hashrate (matrix ops), last-block timing. Use for a fast 'how is the BTX chain doing right now' summary. A neutral network observation.",
+    inputSchema: S(),
+    build: () => ({ path: "/network/glance" }),
+  },
+  {
+    name: "get_block",
+    gated: false,
+    description:
+      "Block detail by height OR block hash. Pass a decimal height (e.g. '155314') or a 64-hex block hash. Returns header, tx list, and metadata. A neutral on-chain fact.",
+    inputSchema: S(
+      {
+        ident: {
+          type: "string",
+          description: "Block height (decimal) or 64-hex block hash.",
+        },
+      },
+      ["ident"]
+    ),
+    build: (a) => ({ path: `/block/${encodeURIComponent(a.ident)}` }),
+  },
+  {
+    name: "get_tx",
+    gated: false,
+    description:
+      "Transaction detail for a txid, with prevouts (inputs) resolved to their source addresses and values. A neutral on-chain fact.",
+    inputSchema: S(
+      { txid: { type: "string", description: "64-hex transaction id." } },
+      ["txid"]
+    ),
+    build: (a) => ({ path: `/tx/${encodeURIComponent(a.txid)}` }),
+  },
+  {
+    name: "get_address",
+    gated: false,
+    description:
+      "Address page: aggregate totals (received/sent/balance) plus a paginated list of the address's transaction rows. `page` is optional (0-based). A neutral on-chain fact, not an ownership or identity claim.",
+    inputSchema: S(
+      {
+        addr: { type: "string", description: "BTX address." },
+        page: {
+          type: "integer",
+          minimum: 0,
+          description: "Optional page number for the tx rows (0-based).",
+        },
+      },
+      ["addr"]
+    ),
+    build: (a) => ({
+      path: `/address/${encodeURIComponent(a.addr)}`,
+      query: { page: a.page },
+    }),
+  },
+  {
+    name: "blocks_latest",
+    gated: false,
+    description:
+      "The latest N confirmed blocks (most recent first). `n` is optional. A neutral on-chain fact.",
+    inputSchema: S({
+      n: {
+        type: "integer",
+        minimum: 1,
+        maximum: 100,
+        description: "How many recent blocks to return (default server-side).",
+      },
+    }),
+    build: (a) => ({ path: "/blocks/latest", query: { n: a.n } }),
+  },
+  {
+    name: "txs_latest",
+    gated: false,
+    description:
+      "The latest N confirmed transactions (most recent first). `n` is optional. A neutral on-chain fact.",
+    inputSchema: S({
+      n: {
+        type: "integer",
+        minimum: 1,
+        maximum: 100,
+        description: "How many recent transactions to return (default server-side).",
+      },
+    }),
+    build: (a) => ({ path: "/txs/latest", query: { n: a.n } }),
+  },
+  {
+    name: "search",
+    gated: false,
+    description:
+      "Universal search over the chain: resolves a query that is a block height, block hash, txid, or address to the right entity. Use when you have an identifier but don't know its type. A neutral lookup.",
+    inputSchema: S(
+      {
+        q: {
+          type: "string",
+          description: "Height, block hash, txid, or address to resolve.",
+        },
+      },
+      ["q"]
+    ),
+    build: (a) => ({ path: "/search", query: { q: a.q } }),
+  },
+  {
+    name: "network_supply",
+    gated: false,
+    description:
+      "Emission & halving analytic: circulating/issued supply, emission schedule, halving context. A neutral supply arithmetic observation.",
+    inputSchema: S(),
+    build: () => ({ path: "/network/supply" }),
+  },
+  {
+    name: "mempool",
+    gated: false,
+    description:
+      "Mempool summary plus recent unconfirmed entries (size, fee context, sample of pending txs). A neutral node-vantage observation of the current mempool.",
+    inputSchema: S(),
+    build: () => ({ path: "/mempool" }),
+  },
+
+  // ---- Market / data ------------------------------------------------------
+  {
+    name: "market_summary",
+    gated: false,
+    description:
+      "Real market price summary from live exchange venue(s) (SafeTrade): best bid/ask, mid, last trade, index price, venue count. NOTE the quote is a USD stablecoin (~1:1 with USD, a label not a USD feed) and the market is thin/newly-listed — treat the price as indicative, not a deep-liquidity mark. Distinct from `/price` (the banked model price). Read the caveat.",
+    inputSchema: S(),
+    build: () => ({ path: "/market/summary" }),
+  },
+  {
+    name: "liquidity",
+    gated: true,
+    description:
+      "PRO/Enterprise. On-chain liquidity funnel: an ESTIMATE of plausibly-available (recently-moved unspent) supply versus single-venue order-book depth/spread/volume. A proxy for available float, NOT a claim any of it is offered for sale, and NOT price discovery. Read the caveat.",
+    inputSchema: S(),
+    build: () => ({ path: "/pro/liquidity" }),
+  },
+  {
+    name: "usage",
+    gated: true,
+    description:
+      "PRO/Enterprise. BTX usage view: how transparent on-chain value is being used, bucketed into neutral activity categories (e.g. exchange-flow, mined-and-held) with trends. BTX is mostly mined-and-held; categories that are 'not yet measurable' say so explicitly. Neutral activity aggregates, not identity. Read the caveat.",
+    inputSchema: S(),
+    build: () => ({ path: "/pro/usage" }),
+  },
+  {
+    name: "wbtx_summary",
+    gated: false,
+    description:
+      "wBTX bridge summary across both chains: bridged supply, reserve/backing signal, freshness, bridge address. NOTE: testnet data only — no mainnet, no real backing; the reserve badge is a mechanical backing-vs-supply + freshness signal, not an audit. Read the caveat.",
+    inputSchema: S(),
+    build: () => ({ path: "/wbtx/summary" }),
+  },
+  {
+    name: "supply_demand",
+    gated: false,
+    description:
+      "On-chain supply map: coin-age & balance cohorts, net-flow, HODL waves — optionally priced. `window` selects the lookback; `price` chooses 'model' (banked model price) or 'market' (live exchange price) for any USD-denominated figures. A neutral supply-structure observation, not trading advice.",
+    inputSchema: S({
+      window: {
+        type: "string",
+        description: "Lookback window (e.g. '24h', '7d', '30d', '1y', 'all').",
+      },
+      price: {
+        type: "string",
+        enum: ["model", "market"],
+        description: "Price source for USD figures: 'model' or 'market'.",
+      },
+    }),
+    build: (a) => ({
+      path: "/supply-demand",
+      query: { window: a.window, price: a.price },
+    }),
+  },
+
+  // ---- Provenance (PRO) ---------------------------------------------------
+  {
+    name: "trace",
+    gated: false, // public tracer per API; token forwarded when present for deeper tiers
+    description:
+      "Bounded fund tracer over the spend index: follows value forward or backward from a txid across a limited number of hops. `dir` = 'forward' (where funds went) or 'back' (where funds came from); `hops` bounds depth (clamped server-side to your tier). 'Traceable' is a proportional flow share on provable edges, NEVER an ownership, sender, or counterparty assertion.",
+    inputSchema: S(
+      {
+        txid: { type: "string", description: "64-hex transaction id to trace from." },
+        dir: {
+          type: "string",
+          enum: ["forward", "back"],
+          description: "Trace direction: 'forward' or 'back'.",
+        },
+        hops: {
+          type: "integer",
+          minimum: 1,
+          description: "Max hops to traverse (clamped to your tier).",
+        },
+      },
+      ["txid"]
+    ),
+    build: (a) => ({
+      path: `/trace/${encodeURIComponent(a.txid)}`,
+      query: { dir: a.dir, hops: a.hops },
+    }),
+  },
+  {
+    name: "cluster",
+    gated: true,
+    description:
+      "PRO/Enterprise. Co-spend set: other addresses that appeared together as inputs in the same transaction(s) as the queried address. This is a provable on-chain co-occurrence and is explicitly NOT proof of common ownership — never state or imply the addresses share an owner. `format` optionally selects the response shape.",
+    inputSchema: S(
+      {
+        addr: { type: "string", description: "BTX address to build the co-spend set for." },
+        format: {
+          type: "string",
+          description: "Optional response format selector supported by the API.",
+        },
+      },
+      ["addr"]
+    ),
+    build: (a) => ({
+      path: `/cluster/${encodeURIComponent(a.addr)}`,
+      query: { format: a.format },
+    }),
+  },
+];
+
+const TOOL_BY_NAME = new Map(TOOLS.map((t) => [t.name, t]));
+
+// ---------------------------------------------------------------------------
+// HTTP client + neutral-facts wrapping
+// ---------------------------------------------------------------------------
+
+function buildUrl(path, query) {
+  const url = new URL(API_BASE + path);
+  for (const [k, v] of Object.entries(query || {})) {
+    if (v !== undefined && v !== null && v !== "") url.searchParams.set(k, String(v));
+  }
+  return url;
+}
+
+/** Wrap an API payload so the caveat is unavoidable and framing is always present. */
+function wrapObservation(payload) {
+  let caveat = CANONICAL_CAVEAT;
+  if (payload && typeof payload === "object" && !Array.isArray(payload)) {
+    if (payload.caveat !== undefined && payload.caveat !== null && payload.caveat !== "") {
+      caveat = payload.caveat;
+    }
+  }
+  return { observation: payload, caveat, framing: FRAMING };
+}
+
+/** Perform the GET and return a structured result object (never throws for HTTP status). */
+async function apiGet(tool, args) {
+  const { path, query } = tool.build(args);
+  const url = buildUrl(path, query);
+
+  const headers = {
+    Accept: "application/json",
+    "User-Agent": `${NAME}/${VERSION}`,
+  };
+  if (TOKEN) headers.Authorization = `Bearer ${TOKEN}`;
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  let res, bodyText;
+  try {
+    res = await fetch(url, { headers, signal: controller.signal });
+    bodyText = await res.text();
+  } catch (err) {
+    clearTimeout(timer);
+    const aborted = err && err.name === "AbortError";
+    return {
+      isError: true,
+      payload: {
+        error: "network",
+        detail: aborted
+          ? `Request timed out after ${REQUEST_TIMEOUT_MS}ms`
+          : `Failed to reach the First Light API: ${err && err.message ? err.message : String(err)}`,
+        endpoint: path,
+      },
+    };
+  }
+  clearTimeout(timer);
+
+  let json;
+  try {
+    json = bodyText ? JSON.parse(bodyText) : null;
+  } catch {
+    json = { raw: bodyText };
+  }
+
+  // Map the API status codes to a clean, model-legible error surface.
+  if (res.status === 401) {
+    return {
+      isError: true,
+      payload: {
+        error: "auth",
+        detail: TOKEN
+          ? "The First Light API rejected the token (invalid, revoked, or expired). Check FIRST_LIGHT_TOKEN."
+          : "This tool needs a PRO/Enterprise token. Set the FIRST_LIGHT_TOKEN environment variable to your First Light Bearer key.",
+        endpoint: path,
+      },
+    };
+  }
+  if (res.status === 403) {
+    return {
+      isError: true,
+      payload: {
+        error: "tier",
+        detail:
+          "This tool needs a higher tier than your token allows (PRO/Enterprise). " +
+          ((json && (json.detail || json.error)) || "Contact the operator to upgrade."),
+        endpoint: path,
+      },
+    };
+  }
+  if (res.status === 429) {
+    const retryAfter = res.headers.get("retry-after");
+    return {
+      isError: true,
+      payload: {
+        error: "rate_limited",
+        detail: "Per-key rate limit exceeded; back off and retry.",
+        retryAfter: retryAfter ? Number(retryAfter) : undefined,
+        endpoint: path,
+      },
+    };
+  }
+  if (res.status === 400) {
+    return {
+      isError: true,
+      payload: {
+        error: "bad_request",
+        detail: (json && (json.detail || json.error)) || "Invalid request parameters.",
+        endpoint: path,
+      },
+    };
+  }
+  if (!res.ok) {
+    return {
+      isError: true,
+      payload: {
+        error: "http_" + res.status,
+        detail: (json && (json.detail || json.error)) || bodyText || res.statusText,
+        endpoint: path,
+      },
+    };
+  }
+
+  return { isError: false, payload: wrapObservation(json) };
+}
+
+// ---------------------------------------------------------------------------
+// MCP server wiring
+// ---------------------------------------------------------------------------
+
+const server = new Server(
+  { name: NAME, version: VERSION },
+  { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOLS.map((t) => ({
+    name: t.name,
+    description:
+      (t.gated ? "[PRO/Enterprise token required] " : "") + t.description,
+    inputSchema: t.inputSchema,
+  })),
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const { name, arguments: args } = req.params;
+  const tool = TOOL_BY_NAME.get(name);
+  if (!tool) {
+    return {
+      isError: true,
+      content: [{ type: "text", text: JSON.stringify({ error: "unknown_tool", detail: `No tool named '${name}'.` }, null, 2) }],
+    };
+  }
+
+  const result = await apiGet(tool, args || {});
+  return {
+    isError: result.isError,
+    content: [{ type: "text", text: JSON.stringify(result.payload, null, 2) }],
+  };
+});
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  // Log to stderr only — stdout is the MCP JSON-RPC channel.
+  console.error(
+    `${NAME} v${VERSION} ready · API ${API_BASE} · token ${TOKEN ? "present" : "absent (public tools only)"} · ${TOOLS.length} tools`
+  );
+}
+
+main().catch((err) => {
+  console.error(`${NAME} fatal:`, err);
+  process.exit(1);
+});