@lobstack-ai/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lobstack
+
+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,238 @@
+# @lobstack-ai/mcp
+
+An MCP server for the [Lobstack](https://www.lobstack.ai) Gateway. One API key
+reaches every major model, and every call comes back with a receipt: which model
+served it, how many tokens, what it cost.
+
+Works in Claude Desktop, Claude Code, Cursor, Zed, or anything else that speaks
+the Model Context Protocol over stdio.
+
+## Try it without a key
+
+`lobstack_route_preview` is unauthenticated. Install the server with no
+credential at all and an agent can still ask "which model would this prompt go
+to, and what would it cost":
+
+```
+npx -y @lobstack-ai/mcp
+```
+
+Add it to your client using one of the blocks below, leave `env` out, and ask:
+
+> Preview how Lobstack would route: "summarise this changelog into three bullets"
+
+The other three tools need a key, minted in Console → API keys.
+
+## Install
+
+### Claude Desktop
+
+`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS,
+`%APPDATA%\Claude\claude_desktop_config.json` on Windows:
+
+```json
+{
+  "mcpServers": {
+    "lobstack": {
+      "command": "npx",
+      "args": ["-y", "@lobstack-ai/mcp"],
+      "env": {
+        "LOBSTACK_API_KEY": "lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The four `lobstack_*` tools appear under the tools menu.
+
+### Cursor
+
+`~/.cursor/mcp.json` for every project, or `.cursor/mcp.json` for one:
+
+```json
+{
+  "mcpServers": {
+    "lobstack": {
+      "command": "npx",
+      "args": ["-y", "@lobstack-ai/mcp"],
+      "env": {
+        "LOBSTACK_API_KEY": "lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add lobstack --env LOBSTACK_API_KEY=lsk_live_... -- npx -y @lobstack-ai/mcp
+```
+
+### Zed
+
+In `settings.json`, under `context_servers`:
+
+```json
+{
+  "context_servers": {
+    "lobstack": {
+      "source": "custom",
+      "command": "npx",
+      "args": ["-y", "@lobstack-ai/mcp"],
+      "env": {
+        "LOBSTACK_API_KEY": "lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+### `lobstack_route_preview`
+
+Scores a prompt against the same router the paid path uses and reports the model
+that would serve it, the capability tier, the complexity score, and the
+estimated cost. Runs no inference and spends nothing. **Needs no API key.**
+
+| argument | type | notes |
+| --- | --- | --- |
+| `prompt` | string, required | Scored, never sent to a model. Max 8000 characters. |
+| `requested_model` | string | A model to compare against. Defaults to `auto`. |
+| `plan_tier` | string | Plan id, which sets the ceiling the router may reach. |
+| `expected_output_tokens` | integer | Defaults to half the prompt. |
+| `conversation_length` | integer | Messages already in the conversation. |
+
+Token counts are estimates — roughly four characters per token. The billed
+figure always comes from the provider's own usage block on the real request, and
+the tool says so in every answer.
+
+A `baseline` is returned only when you named a model and the router moved away
+from it. On `auto` it is `null`: there is no model you asked for to compare
+against.
+
+### `lobstack_models`
+
+The catalogue: model key, label, tier, provider, context window, and USD per
+million input and output tokens. Optional `tier` and `provider` filters.
+
+A model the registry cannot price comes back with `null` prices and renders as
+`—`. It is not free.
+
+### `lobstack_chat`
+
+Sends a prompt or a conversation and returns the reply plus the receipt.
+
+| argument | type | notes |
+| --- | --- | --- |
+| `prompt` | string | A single user message. Use this **or** `messages`. |
+| `messages` | array | `{ role, content }`, OpenAI-shaped. Use this **or** `prompt`. |
+| `model` | string | Defaults to `auto` — the router picks the cheapest capable model. |
+| `system` | string | Prepended to the conversation. |
+| `max_tokens` | integer | Cap on the reply. |
+| `temperature` | number | Some models do not accept it; the receipt says when it was dropped. |
+
+The reply and the receipt come back as two separate content blocks, so whatever
+consumes the answer does not get a price line concatenated onto it. The
+structured result carries:
+
+```json
+{
+  "text": "...",
+  "model": { "requested": "claude-opus-5", "served": "claude-haiku-4-5", "routed": true },
+  "usage": { "prompt_tokens": 400, "completion_tokens": 140, "total_tokens": 540 },
+  "receipt": {
+    "request_id": "req_...",
+    "cost_usd": 0.0011,
+    "cost_display": "$0.001100",
+    "priced": true,
+    "savings": {
+      "amount_usd": 0.0044,
+      "label": "saved",
+      "named": true,
+      "baseline_model": "claude-opus-5",
+      "baseline_reason": "named"
+    }
+  },
+  "quota": { "meter": "spend", "remaining_usd": 16.75 },
+  "dropped_params": []
+}
+```
+
+### `lobstack_spend`
+
+What the organization has spent over `7d`, `14d`, `30d` or `90d`, grouped by
+`day`, `model`, `key` or `agent`, with request counts, tokens, errors and
+latency percentiles. Requires a key holding the `usage:read` scope.
+
+It also reports `unpriced_requests` and sets `is_floor`. The endpoint sums an
+unpriced row as zero — the only arithmetic available — so a total that includes
+one is a lower bound, not a total, and this tool says which.
+
+It does **not** report a savings total. `/api/v1/usage` does not compute one,
+and adding up savings client-side would mean pricing the org's tokens against a
+copy of the rate card. Savings are reported per call, by `lobstack_chat`, where
+the gateway sends them with the reason attached.
+
+## Two rules about the numbers
+
+**A null cost is not zero.** `cost_usd: null` means the gateway could not price
+the call. It renders as `unpriced`, never as `$0.00`. Rendering it as `$0.00`
+writes off a real charge, and that exact substitution ran for three months in
+production.
+
+**`baseline_reason` decides what a saving may be called.**
+
+- `named` — you asked for a model and got something cheaper. Like-for-like, and
+  the only case labelled `saved`.
+- `plan_ceiling` — you sent `auto`, so the comparison is against the most
+  expensive model your plan allows. Real, and not something you asked for:
+  labelled `vs ceiling`, with the baseline model named next to it.
+- missing — treated as unnamed. A receipt that does not say where its baseline
+  came from does not get the flattering reading.
+
+## Configuration
+
+| variable | default | notes |
+| --- | --- | --- |
+| `LOBSTACK_API_KEY` | none | Read once at startup. Never logged, never in a tool result. |
+| `LOBSTACK_BASE_URL` | `https://www.lobstack.ai/api/gateway/v1` | For staging and self-hosted deployments. |
+
+**Use `www`, not the bare apex.** `lobstack.ai` redirects to `www.lobstack.ai`,
+and [RFC 9110 §15.4](https://www.rfc-editor.org/rfc/rfc9110#section-15.4)
+requires a client to drop `Authorization` across a host change — so the gateway
+answers a perfectly good key with "missing credentials". This server rewrites
+the apex and tells you it did, and refuses to follow any other 3xx rather than
+send a request whose credential has been stripped.
+
+### The key
+
+`LOBSTACK_API_KEY` is read from this process's environment and from nowhere
+else. No tool takes a key, a token, or a base URL as an argument: a base URL
+that can arrive as a tool argument is a credential that can be redirected by
+whoever wrote the argument. Error text is scrubbed on the way out, including
+text that came back from upstream.
+
+This process holds a live credential for as long as your MCP client runs. The
+dependency list is the MCP SDK, zod, and what those two bring with them.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+The tests run a real MCP client against the server over an in-memory transport,
+and the server against a fake gateway over real HTTP. The fake gateway writes
+its SSE stream in two pieces with the cut landing mid-frame, serves a model with
+no price, and refuses any request to `/route-preview` that arrives carrying an
+`Authorization` header — so a client that leaks a credential to a public
+endpoint fails a test rather than shipping.
+
+## Licence
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Where the Gateway is, where the key comes from, and why neither is a tool
+ * argument.
+ *
+ * This process holds a live credential for the whole time the MCP client is
+ * running. Two consequences shape this file.
+ *
+ * The key is read from the environment once, at construction, and never from a
+ * tool call. If `base_url` were a tool argument, any agent — or anything that
+ * got a sentence into an agent's context — could point a `chat` call at a host
+ * of its choosing and the `Authorization` header would follow. So the base URL
+ * is process configuration, full stop. `LOBSTACK_BASE_URL` exists for staging
+ * and self-hosted deployments; no tool schema in this repo accepts a URL.
+ *
+ * And the key never leaves. `scrub()` below runs over every error string that
+ * makes it into a tool result, because the one place a credential tends to
+ * resurface is in somebody else's error message.
+ */
+/**
+ * The host that answers without a redirect.
+ *
+ * `lobstack.ai` 307s to `www.lobstack.ai`. RFC 9110 §15.4 requires a client to
+ * drop `Authorization` across a host change, so a caller who points at the bare
+ * apex gets "missing credentials" back while holding a perfectly good key —
+ * which is exactly the failure that made the Gateway look broken for three
+ * months. It is corrected, out loud, rather than honoured. See `resolveBase`.
+ */
+export declare const DEFAULT_BASE_URL = "https://www.lobstack.ai/api/gateway/v1";
+/** The gateway lives under this prefix; `/api/v1/usage` is its sibling. */
+export declare const GATEWAY_PREFIX = "/api/gateway/v1";
+export declare function looksLikeApiKey(token: string): boolean;
+export declare class ConfigError extends Error {
+    readonly hint: string | undefined;
+    constructor(message: string, hint?: string);
+}
+export interface ResolvedBase {
+    /** Origin only, no trailing slash. Paths are composed from it. */
+    origin: string;
+    /** True when the apex was rewritten to `www`. Reported, never silent. */
+    corrected: boolean;
+}
+/**
+ * Normalise a base URL, and refuse the one that silently breaks auth.
+ *
+ * Accepts either spelling of the same thing — `https://www.lobstack.ai` and
+ * `https://www.lobstack.ai/api/gateway/v1` — because the documented default is
+ * the full endpoint and people copy what they read. Both reduce to the origin,
+ * which `gatewayUrl` and `apiUrl` then compose against.
+ */
+export declare function resolveBase(explicit?: string | null): ResolvedBase;
+/** A path under the OpenAI-compatible gateway, e.g. `/chat/completions`. */
+export declare const gatewayUrl: (origin: string, path: string) => string;
+/** A path under the platform API, e.g. `/v1/usage`. */
+export declare const apiUrl: (origin: string, path: string) => string;
+export interface Config {
+    base: ResolvedBase;
+    /** Null when no credential is configured. The value is never rendered. */
+    apiKey: string | null;
+    /** True when a key is present but is not shaped like a Lobstack API key. */
+    keyShapeUnrecognised: boolean;
+}
+export declare function loadConfig(overrides?: {
+    baseUrl?: string | null;
+    apiKey?: string | null;
+}): Config;
+/**
+ * Remove the credential from a string before anybody reads it.
+ *
+ * Two passes, because there are two ways a key gets into text. The literal
+ * configured value covers an upstream that echoes back what it was sent — and
+ * a self-hosted gateway token that does not match the `lsk_` shape. The pattern
+ * covers a key that arrived from somewhere else entirely: a pasted config, a
+ * provider's error body, a log line quoted into a response.
+ */
+export declare function scrub(text: string, apiKey?: string | null): string;

package/dist/config.js

@@ -0,0 +1,111 @@
+/**
+ * Where the Gateway is, where the key comes from, and why neither is a tool
+ * argument.
+ *
+ * This process holds a live credential for the whole time the MCP client is
+ * running. Two consequences shape this file.
+ *
+ * The key is read from the environment once, at construction, and never from a
+ * tool call. If `base_url` were a tool argument, any agent — or anything that
+ * got a sentence into an agent's context — could point a `chat` call at a host
+ * of its choosing and the `Authorization` header would follow. So the base URL
+ * is process configuration, full stop. `LOBSTACK_BASE_URL` exists for staging
+ * and self-hosted deployments; no tool schema in this repo accepts a URL.
+ *
+ * And the key never leaves. `scrub()` below runs over every error string that
+ * makes it into a tool result, because the one place a credential tends to
+ * resurface is in somebody else's error message.
+ */
+/**
+ * The host that answers without a redirect.
+ *
+ * `lobstack.ai` 307s to `www.lobstack.ai`. RFC 9110 §15.4 requires a client to
+ * drop `Authorization` across a host change, so a caller who points at the bare
+ * apex gets "missing credentials" back while holding a perfectly good key —
+ * which is exactly the failure that made the Gateway look broken for three
+ * months. It is corrected, out loud, rather than honoured. See `resolveBase`.
+ */
+export const DEFAULT_BASE_URL = "https://www.lobstack.ai/api/gateway/v1";
+/** The apex, and the host it redirects to. */
+const APEX = "lobstack.ai";
+const WWW = "www.lobstack.ai";
+/** The gateway lives under this prefix; `/api/v1/usage` is its sibling. */
+export const GATEWAY_PREFIX = "/api/gateway/v1";
+/**
+ * The shape a Lobstack API key has: `lsk_{live,test}_` + 8 hex selector + 48
+ * hex secret. See `src/lib/api-keys.ts` in the platform.
+ *
+ * Used for two things and neither of them is admission control: telling a user
+ * their token does not look like an API key, and scrubbing anything key-shaped
+ * out of text on its way to a tool result. The Gateway also accepts per-agent
+ * gateway tokens and the platform agent secret, so a token that fails this test
+ * is still sent — refusing it here would lock out self-hosted deployments.
+ */
+const KEY_SHAPE = /lsk_(?:live|test)_[0-9a-f]{8}[0-9a-f]{48}/g;
+export function looksLikeApiKey(token) {
+    return new RegExp(`^${KEY_SHAPE.source}$`).test(token.trim());
+}
+export class ConfigError extends Error {
+    hint;
+    constructor(message, hint) {
+        super(message);
+        this.name = "ConfigError";
+        this.hint = hint;
+    }
+}
+/**
+ * Normalise a base URL, and refuse the one that silently breaks auth.
+ *
+ * Accepts either spelling of the same thing — `https://www.lobstack.ai` and
+ * `https://www.lobstack.ai/api/gateway/v1` — because the documented default is
+ * the full endpoint and people copy what they read. Both reduce to the origin,
+ * which `gatewayUrl` and `apiUrl` then compose against.
+ */
+export function resolveBase(explicit) {
+    const raw = (explicit || process.env.LOBSTACK_BASE_URL || DEFAULT_BASE_URL).trim();
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new ConfigError(`LOBSTACK_BASE_URL is not a URL: ${JSON.stringify(raw)}.`, `Use an absolute URL, e.g. ${DEFAULT_BASE_URL}`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new ConfigError(`LOBSTACK_BASE_URL must be http or https, not ${url.protocol.replace(":", "")}.`, `Use an absolute URL, e.g. ${DEFAULT_BASE_URL}`);
+    }
+    // One known redirect, corrected. Someone else's host is left exactly as
+    // given: this is not a policy about other people's domains.
+    if (url.hostname === APEX) {
+        url.hostname = WWW;
+        return { origin: url.origin, corrected: true };
+    }
+    return { origin: url.origin.replace(/\/+$/, ""), corrected: false };
+}
+/** A path under the OpenAI-compatible gateway, e.g. `/chat/completions`. */
+export const gatewayUrl = (origin, path) => `${origin}${GATEWAY_PREFIX}${path}`;
+/** A path under the platform API, e.g. `/v1/usage`. */
+export const apiUrl = (origin, path) => `${origin}/api${path}`;
+export function loadConfig(overrides = {}) {
+    const base = resolveBase(overrides.baseUrl ?? null);
+    const raw = (overrides.apiKey ?? process.env.LOBSTACK_API_KEY ?? "").trim();
+    return {
+        base,
+        apiKey: raw || null,
+        keyShapeUnrecognised: !!raw && !looksLikeApiKey(raw),
+    };
+}
+/**
+ * Remove the credential from a string before anybody reads it.
+ *
+ * Two passes, because there are two ways a key gets into text. The literal
+ * configured value covers an upstream that echoes back what it was sent — and
+ * a self-hosted gateway token that does not match the `lsk_` shape. The pattern
+ * covers a key that arrived from somewhere else entirely: a pasted config, a
+ * provider's error body, a log line quoted into a response.
+ */
+export function scrub(text, apiKey) {
+    let out = text;
+    if (apiKey && apiKey.length >= 8)
+        out = out.split(apiKey).join("[redacted]");
+    return out.replace(KEY_SHAPE, "[redacted]");
+}

package/dist/gateway.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Talking to the Gateway.
+ *
+ * One fetch wrapper, because there is one rule that must never be skipped on
+ * any request: do not follow a redirect with a credential attached.
+ *
+ * A redirect that changes host makes every conforming HTTP client drop
+ * `Authorization` (RFC 9110 §15.4), so the Gateway answers a perfectly good key
+ * with "missing credentials" and the user goes looking for a problem with their
+ * key. `redirect: "manual"` plus a loud failure is the only honest response:
+ * the request did not fail because the key is bad, it failed because the key
+ * was never sent.
+ */
+import { type Config } from "./config.js";
+export declare class GatewayError extends Error {
+    readonly hint: string | undefined;
+    readonly status: number | undefined;
+    readonly requestId: string | undefined;
+    constructor(message: string, opts?: {
+        hint?: string;
+        status?: number;
+        requestId?: string;
+    });
+}
+/** Identifies this client in the Gateway's traces. Not a credential. */
+export declare const CLIENT_ID = "lobstack-mcp";
+export interface FetchOpts {
+    method?: string;
+    body?: string;
+    /** Send no `Authorization` at all. Used by route_preview, which needs none. */
+    anonymous?: boolean;
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+}
+export declare function gwFetch(cfg: Config, url: string, opts?: FetchOpts): Promise<Response>;
+/** A readable error out of a non-2xx response, with the key scrubbed out. */
+export declare function errorFrom(cfg: Config, res: Response, hint?: string): Promise<GatewayError>;
+/** Quota, as the Gateway reports it on every response. See `lib/gateway/quota.ts`. */
+export interface Quota {
+    meter: string;
+    allowance_usd?: number | null;
+    spent_usd?: number | null;
+    remaining_usd?: number | null;
+    limit?: number | null;
+    used?: number | null;
+    remaining?: number | null;
+    credits?: number | null;
+    resets_at?: string | null;
+}
+/**
+ * Pull the allowance off response headers.
+ *
+ * Worth doing because it is free: the Gateway sets these on every answer,
+ * including the streamed one, so an agent finds out it is close to a 402 on the
+ * call before the one that fails rather than after it. There is no key-
+ * authenticated endpoint that reports this on its own — `/api/user/allowance`
+ * needs a browser session — so this is the only honest place to get it.
+ */
+export declare function quotaFromHeaders(h: Headers): Quota | null;
+/** One line describing the allowance, or null when the Gateway did not report one. */
+export declare function describeQuota(q: Quota | null): string | null;

package/dist/gateway.js

@@ -0,0 +1,126 @@
+/**
+ * Talking to the Gateway.
+ *
+ * One fetch wrapper, because there is one rule that must never be skipped on
+ * any request: do not follow a redirect with a credential attached.
+ *
+ * A redirect that changes host makes every conforming HTTP client drop
+ * `Authorization` (RFC 9110 §15.4), so the Gateway answers a perfectly good key
+ * with "missing credentials" and the user goes looking for a problem with their
+ * key. `redirect: "manual"` plus a loud failure is the only honest response:
+ * the request did not fail because the key is bad, it failed because the key
+ * was never sent.
+ */
+import { scrub } from "./config.js";
+export class GatewayError extends Error {
+    hint;
+    status;
+    requestId;
+    constructor(message, opts = {}) {
+        super(message);
+        this.name = "GatewayError";
+        this.hint = opts.hint;
+        this.status = opts.status;
+        this.requestId = opts.requestId;
+    }
+}
+/** Identifies this client in the Gateway's traces. Not a credential. */
+export const CLIENT_ID = "lobstack-mcp";
+export async function gwFetch(cfg, url, opts = {}) {
+    const headers = {
+        Accept: "application/json, text/event-stream",
+        "x-lobstack-client": CLIENT_ID,
+        ...(opts.headers ?? {}),
+    };
+    if (opts.body !== undefined)
+        headers["Content-Type"] = "application/json";
+    if (!opts.anonymous && cfg.apiKey)
+        headers.Authorization = `Bearer ${cfg.apiKey}`;
+    let res;
+    try {
+        res = await fetch(url, {
+            method: opts.method ?? "GET",
+            body: opts.body,
+            signal: opts.signal ?? null,
+            redirect: "manual",
+            headers,
+        });
+    }
+    catch (e) {
+        throw new GatewayError(`could not reach the gateway: ${scrub(e instanceof Error ? e.message : String(e), cfg.apiKey)}`, { hint: `Base URL in use: ${cfg.base.origin}` });
+    }
+    if (res.status >= 300 && res.status < 400) {
+        // Not followed, and not quietly.
+        const location = res.headers.get("location");
+        throw new GatewayError(`the gateway redirected (${res.status}) to ${location || "somewhere else"}; the request was not followed.`, {
+            status: res.status,
+            hint: "A redirect across hosts strips the Authorization header, so the key would never arrive. " +
+                "Set LOBSTACK_BASE_URL to the host that answers directly — https://www.lobstack.ai, never the bare apex.",
+        });
+    }
+    return res;
+}
+/** A readable error out of a non-2xx response, with the key scrubbed out. */
+export async function errorFrom(cfg, res, hint) {
+    const requestId = res.headers.get("x-lobstack-request-id") ?? undefined;
+    let message = `HTTP ${res.status}`;
+    try {
+        const body = (await res.json());
+        const inner = typeof body?.error === "string" ? body.error : body?.error?.message;
+        if (inner)
+            message = inner;
+    }
+    catch {
+        /* not JSON */
+    }
+    return new GatewayError(scrub(message, cfg.apiKey), { status: res.status, requestId, hint });
+}
+const numOrNull = (v) => {
+    if (v === null || v.trim() === "")
+        return null;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : null;
+};
+/**
+ * Pull the allowance off response headers.
+ *
+ * Worth doing because it is free: the Gateway sets these on every answer,
+ * including the streamed one, so an agent finds out it is close to a 402 on the
+ * call before the one that fails rather than after it. There is no key-
+ * authenticated endpoint that reports this on its own — `/api/user/allowance`
+ * needs a browser session — so this is the only honest place to get it.
+ */
+export function quotaFromHeaders(h) {
+    const meter = h.get("x-lobstack-quota-meter");
+    if (!meter)
+        return null;
+    const q = { meter };
+    if (meter === "spend") {
+        q.allowance_usd = numOrNull(h.get("x-lobstack-quota-allowance-usd"));
+        q.spent_usd = numOrNull(h.get("x-lobstack-quota-spent-usd"));
+        q.remaining_usd = numOrNull(h.get("x-lobstack-quota-remaining-usd"));
+    }
+    else {
+        q.limit = numOrNull(h.get("x-lobstack-quota-limit"));
+        q.used = numOrNull(h.get("x-lobstack-quota-used"));
+        q.remaining = numOrNull(h.get("x-lobstack-quota-remaining"));
+        q.credits = numOrNull(h.get("x-lobstack-quota-credits"));
+    }
+    q.resets_at = h.get("x-lobstack-quota-resets");
+    return q;
+}
+/** One line describing the allowance, or null when the Gateway did not report one. */
+export function describeQuota(q) {
+    if (!q)
+        return null;
+    if (q.meter === "spend") {
+        if (q.remaining_usd === null || q.remaining_usd === undefined)
+            return null;
+        const of = q.allowance_usd != null ? ` of $${q.allowance_usd.toFixed(2)}` : "";
+        return `  allowance $${q.remaining_usd.toFixed(4)} remaining${of}`;
+    }
+    if (q.remaining === null || q.remaining === undefined)
+        return null;
+    const of = q.limit != null ? ` of ${q.limit}` : "";
+    return `  allowance ${q.remaining} requests remaining${of} (${q.meter} meter)`;
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * The executable. Stdio transport, and nothing else.
+ *
+ * Two rules for a stdio MCP server, both easy to break by accident:
+ *
+ *   1. stdout is the protocol. Anything written to it that is not a JSON-RPC
+ *      frame corrupts the session. Diagnostics go to stderr.
+ *   2. the key is in the environment of this process. It is never printed, not
+ *      at startup, not in a banner, not in an error. The startup line below
+ *      says whether a key is present, which is the only part of it anybody
+ *      needs to debug a config.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+/**
+ * The executable. Stdio transport, and nothing else.
+ *
+ * Two rules for a stdio MCP server, both easy to break by accident:
+ *
+ *   1. stdout is the protocol. Anything written to it that is not a JSON-RPC
+ *      frame corrupts the session. Diagnostics go to stderr.
+ *   2. the key is in the environment of this process. It is never printed, not
+ *      at startup, not in a banner, not in an error. The startup line below
+ *      says whether a key is present, which is the only part of it anybody
+ *      needs to debug a config.
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer, SERVER_NAME, SERVER_VERSION } from "./server.js";
+import { loadConfig } from "./config.js";
+async function main() {
+    const cfg = loadConfig();
+    const server = createServer();
+    await server.connect(new StdioServerTransport());
+    process.stderr.write(`${SERVER_NAME} mcp ${SERVER_VERSION} · ${cfg.base.origin}` +
+        `${cfg.base.corrected ? " (apex rewritten to www; a redirect would strip the key)" : ""}` +
+        ` · key ${cfg.apiKey ? "configured" : "not set — lobstack_route_preview still works"}\n`);
+}
+main().catch((e) => {
+    process.stderr.write(`lobstack-mcp failed to start: ${e instanceof Error ? e.message : String(e)}\n`);
+    process.exit(1);
+});