@tickerbot/mcp-server 0.3.1 → 0.4.1

package/README.md

@@ -2,6 +2,8 @@
 
 Model Context Protocol server for [Tickerbot](https://tickerbot.io) — the stock market, in SQL. Install in Claude, Cursor, VS Code Copilot, and other MCP-compatible clients to scan ~14,500 US-listed equities plus a curated set of rates, FX and crypto series, replay any day, or subscribe a query — across 421+ signal columns.
 
+This package is a thin stdio bridge to the hosted Tickerbot MCP server at `https://api.tickerbot.io/mcp`. On start it reads the tool list from that server with your key, and it forwards every tool call there and returns the result unchanged. A tool added or changed on Tickerbot reaches you the next time your client starts the server, with no package update. Each request to the hosted server carries an `X-Tickerbot-MCP-Client: @tickerbot/mcp-server/<version>` header, so Tickerbot's call log can tell this package's traffic from other MCP clients; it is a label only.
+
 ## Install
 
 You need a Tickerbot API key. Get one from your [dashboard](https://tickerbot.io/dashboard).
@@ -66,7 +68,7 @@ Add to `.vscode/mcp.json` in your workspace:
 
 ## Tools
 
-33 tools covering scans, signals, tickers (state, history, bars, coverage, ETF holdings), events and their kinds, news, universes and webhook subscriptions (scan, signal, ticker, events and news). Bars and History answer `data`: one symbol gives its rows, a comma list gives them keyed by symbol.
+The tools are whatever the hosted server lists when the bridge starts. At the time of this release that is 35 tools covering scans, signals, tickers (state, history, bars, coverage, ETF holdings), events and their kinds, news, universes and webhook subscriptions (scan, signal, ticker, events and news). History answers `series` keyed by symbol, one flat row per grain step, for one ticker or a comma list. `tickerbot_list_events` and `tickerbot_search_news` were renamed `tickerbot_query_events` and `tickerbot_query_news`; the old names still work, as deprecated tools, until 2027-01-12. An argument a tool does not declare is sent to the API, which answers `unknown_parameter` for it.
 
 | Tool | Endpoint |
 | --- | --- |
@@ -85,27 +87,33 @@ Add to `.vscode/mcp.json` in your workspace:
 | `tickerbot_get_bars` | `GET /v2/tickers/{ticker}/bars/{interval}` |
 | `tickerbot_get_ticker_coverage` | `GET /v2/tickers/{ticker}/coverage` |
 | `tickerbot_get_etf_holdings` | `GET /v2/tickers/{ticker}/holdings` |
-| `tickerbot_list_events` | `GET /v2/events` |
+| `tickerbot_query_events` | `GET /v2/events` |
+| `tickerbot_list_events` | `GET /v2/events` (deprecated: use `tickerbot_query_events`; works until 2027-01-12) |
 | `tickerbot_list_event_kinds` | `GET /v2/events/kinds` |
 | `tickerbot_subscribe_events` | `POST /v2/events/subscribe` |
-| `tickerbot_search_news` | `GET /v2/news` |
+| `tickerbot_query_news` | `GET /v2/news` |
+| `tickerbot_search_news` | `GET /v2/news` (deprecated: use `tickerbot_query_news`; works until 2027-01-12) |
 | `tickerbot_subscribe_news` | `POST /v2/news/subscribe` |
 | `tickerbot_list_universes` | `GET /v2/universes` |
 | `tickerbot_create_universe` | `POST /v2/universes` |
-| `tickerbot_get_universe` | `GET /v2/universes/{id}` |
-| `tickerbot_update_universe` | `PATCH /v2/universes/{id}` |
-| `tickerbot_delete_universe` | `DELETE /v2/universes/{id}` |
+| `tickerbot_get_universe` | `GET /v2/universes/{universe}` |
+| `tickerbot_update_universe` | `PATCH /v2/universes/{universe}` |
+| `tickerbot_delete_universe` | `DELETE /v2/universes/{universe}` |
 | `tickerbot_list_webhooks` | `GET /v2/webhooks` |
-| `tickerbot_get_webhook` | `GET /v2/webhooks/{id}` |
-| `tickerbot_update_webhook` | `PATCH /v2/webhooks/{id}` |
-| `tickerbot_delete_webhook` | `DELETE /v2/webhooks/{id}` |
-| `tickerbot_list_webhook_deliveries` | `GET /v2/webhooks/{id}/deliveries` |
-| `tickerbot_redeliver_webhook_delivery` | `POST /v2/webhooks/{id}/deliveries/{delivery_id}/redeliver` |
-| `tickerbot_enable_webhook` | `POST /v2/webhooks/{id}/enable` |
-| `tickerbot_test_webhook` | `POST /v2/webhooks/{id}/test` |
+| `tickerbot_get_webhook` | `GET /v2/webhooks/{webhook}` |
+| `tickerbot_update_webhook` | `PATCH /v2/webhooks/{webhook}` |
+| `tickerbot_enable_webhook` | `PATCH /v2/webhooks/{webhook}` (deprecated: use `tickerbot_update_webhook` with `enabled: true`; works until 2027-01-12) |
+| `tickerbot_delete_webhook` | `DELETE /v2/webhooks/{webhook}` |
+| `tickerbot_list_webhook_deliveries` | `GET /v2/webhooks/{webhook}/deliveries` |
+| `tickerbot_redeliver_webhook_delivery` | `POST /v2/webhooks/{webhook}/deliveries/{delivery}/redeliver` |
+| `tickerbot_test_webhook` | `POST /v2/webhooks/{webhook}/test` |
 
 Strategies are not exposed via MCP — see the [REST API docs](https://tickerbot.io/api) for those.
 
+### When the hosted server can't be reached
+
+If `api.tickerbot.io/mcp` does not answer at start, the bridge serves the tool list bundled with this version, runs each call itself against the REST API, and writes a warning to stderr. The bundled list can be behind the server's. The bridge retries the server at most once a minute (on `tools/list`) and switches back when it answers. With no `TICKERBOT_API_KEY` set it does not contact the server: it lists the bundled tools and every call answers with how to set a key.
+
 ## Examples
 
 Open Claude and try:
@@ -122,12 +130,20 @@ Open Claude and try:
 
 | Env var | Default | Purpose |
 | --- | --- | --- |
-| `TICKERBOT_API_KEY` | *(required)* | Your API key. Sent as `Authorization: Bearer <key>` on every call. |
-| `TICKERBOT_API_URL` | `https://api.tickerbot.io` | Override the API base URL (for staging or self-hosted). |
+| `TICKERBOT_API_KEY` | *(required)* | Your API key. Sent as `Authorization: Bearer <key>` to the hosted MCP server (and to the REST API in fallback). |
+| `TICKERBOT_API_URL` | `https://api.tickerbot.io` | Override the base URL. The bridge connects to `<base>/mcp`; the fallback calls `<base>/v2/...`. |
 
 ## Remote install
 
-For consumer chat apps (Claude.ai web/mobile, ChatGPT) that don't run subprocesses, use the hosted remote MCP endpoint at `https://mcp.tickerbot.io` instead. See [tickerbot.io/mcp-server](https://tickerbot.io/mcp-server) for setup.
+Clients that connect to an MCP server by URL (Claude.ai web/mobile, ChatGPT, and most desktop and IDE clients) can use the hosted server at `https://api.tickerbot.io/mcp` directly and sign in with OAuth, no package needed. See [tickerbot.io/docs/mcp](https://tickerbot.io/docs/mcp) for setup.
+
+## Development
+
+```bash
+npm install
+npm test                         # builds, then runs the bridge against a stubbed hosted server
+node scripts/regen-tools.mjs     # refresh the bundled fallback list from ../tickerbot (optional)
+```
 
 ## License
 

package/dist/handler.d.ts

@@ -4,9 +4,7 @@ export interface RunToolOptions {
     baseUrl?: string;
     /** Optional user-agent appended to identify the MCP server. */
     userAgent?: string;
-    /** Override the tool lookup. Used when index.ts has fetched the live
-     *  catalog from /mcp/tools — we dispatch against the server's
-     *  current tool definitions, not the baked snapshot. */
+    /** Override the tool lookup (defaults to the bundled snapshot). */
     findTool?: (name: string) => ToolDef | undefined;
 }
 export declare class ToolError extends Error {

package/dist/handler.js

@@ -1,10 +1,10 @@
-// Dispatches an MCP tool call to the Tickerbot REST API.
+// Dispatches an MCP tool call to the Tickerbot REST API, against the
+// bundled snapshot (src/tools.ts).
 //
-// Same handler is used by both transports:
-//   - the stdio binary (src/index.ts) for local desktop/IDE clients
-//   - the HTTP endpoint on main_service for remote chat clients
-//
-// One source of truth for path substitution, query/body assembly, auth.
+// Fallback only (TB-740): the stdio bridge (src/index.ts) forwards calls to
+// the hosted MCP server and uses this runner only while that server cannot
+// be reached, or when no key is set. Mirrors main_service/mcp/handler.js,
+// which runs every call the hosted server answers.
 import { findTool as bakedFindTool } from './tools.js';
 const DEFAULT_BASE_URL = 'https://api.tickerbot.io';
 export class ToolError extends Error {
@@ -113,14 +113,28 @@ function buildRequest(tool, args, baseUrl) {
     const body = {};
     let bodyHasContent = false;
     for (const [key, value] of Object.entries(args)) {
-        if (value === undefined || value === null || value === '')
-            continue;
         // Declared params first; then the older names the route still accepts
-        // (endpoint.accepts, TB-570), sent where the route reads them. Anything
-        // else is ignored. Mirrors main_service/mcp/handler.js.
+        // (endpoint.accepts, TB-570), sent where the route reads them. The name
+        // is judged BEFORE the blank skip (TB-749): any other argument, blank
+        // included, is forwarded so the API answers 400 `unknown_parameter`
+        // instead of the call silently succeeding without it. A query param on
+        // GET, a body field otherwise.
         const where = tool.endpoint.paramLocation[key] ?? tool.endpoint.accepts?.[key];
-        if (!where)
-            continue; // unknown param, ignore
+        if (!where) {
+            if (value === undefined)
+                continue;
+            if (tool.endpoint.method === 'GET') {
+                query.append(key, value === null ? '' : typeof value === 'object' ? JSON.stringify(value) : String(value));
+            }
+            else {
+                body[key] = value;
+                bodyHasContent = true;
+            }
+            continue;
+        }
+        // A blank DECLARED param means "not sent".
+        if (value === undefined || value === null || value === '')
+            continue;
         if (where === 'path') {
             // An older path-param name fills the slot the docs name it by
             // (endpoint.pathAliases, TB-570 step 3: `id` → {universe}).
@@ -138,11 +152,6 @@ function buildRequest(tool, args, baseUrl) {
             bodyHasContent = true;
         }
     }
-    // Fixed query values the tool always sends (endpoint.fixedQuery, TB-570
-    // step 3: `api_version=2027-01-12` on Bars and History, so they answer
-    // `data` — one symbol: its rows; a comma list: keyed by symbol).
-    for (const [k, v] of Object.entries(tool.endpoint.fixedQuery ?? {}))
-        query.set(k, String(v));
     // Fixed body fields (endpoint.fixedBody: a deprecated tool built from its
     // successor, tickerbot_enable_webhook = PATCH `enabled: true`).
     for (const [k, v] of Object.entries(tool.endpoint.fixedBody ?? {})) {

package/dist/hosted.d.ts

@@ -0,0 +1,52 @@
+export interface HostedTool {
+    name: string;
+    description?: string;
+    inputSchema: {
+        type: 'object';
+        [k: string]: unknown;
+    };
+    outputSchema?: {
+        type: 'object';
+        [k: string]: unknown;
+    };
+    [k: string]: unknown;
+}
+export interface HostedCallResult {
+    content: unknown[];
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+    [k: string]: unknown;
+}
+/** The server could not be reached or did not answer with JSON-RPC. */
+export declare class HostedUnavailable extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+/** The server answered with a JSON-RPC error object. */
+export declare class HostedRpcError extends Error {
+    readonly code: number;
+    readonly data?: unknown | undefined;
+    constructor(code: number, message: string, data?: unknown | undefined);
+}
+export interface HostedClientOptions {
+    url: string;
+    apiKey: string;
+    userAgent: string;
+    clientVersion: string;
+    /** Sent as X-Tickerbot-MCP-Client: `@tickerbot/mcp-server/<version>`. */
+    clientLabel: string;
+}
+export declare class HostedClient {
+    private readonly opts;
+    private nextId;
+    private sessionId;
+    private protocolVersion;
+    constructor(opts: HostedClientOptions);
+    /** initialize + notifications/initialized + tools/list. */
+    connect(timeoutMs: number): Promise<HostedTool[]>;
+    listTools(timeoutMs: number): Promise<HostedTool[]>;
+    callTool(name: string, args: Record<string, unknown>, timeoutMs: number): Promise<HostedCallResult>;
+    private notify;
+    private request;
+    private post;
+}

package/dist/hosted.js

@@ -0,0 +1,158 @@
+// Client for the hosted Tickerbot MCP server ({baseUrl}/mcp, served by
+// main_service/endpoints/mcp.js).
+//
+// The hosted server speaks MCP over Streamable HTTP in its single-JSON form:
+// every JSON-RPC message is one POST to /mcp with `Authorization: Bearer
+// <key>`, and the answer is one JSON body (a notification gets 202 and no
+// body). It keeps no session and never streams, so this client is a plain
+// fetch per message. It still behaves as a spec client (Accept lists
+// text/event-stream, an mcp-session-id is echoed back if one is issued, an
+// SSE answer is read) so a later server change does not break old installs.
+//
+// No key, or a key the server refuses outright, answers HTTP 401 on every
+// request. A key the server accepts at the door but the REST API refuses
+// (malformed, revoked) passes initialize and tools/list; its tools/call
+// comes back as an isError result carrying the REST 401 text, which the
+// bridge returns unchanged.
+/** The server could not be reached or did not answer with JSON-RPC. */
+export class HostedUnavailable extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'HostedUnavailable';
+    }
+}
+/** The server answered with a JSON-RPC error object. */
+export class HostedRpcError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+        this.name = 'HostedRpcError';
+    }
+}
+const CLIENT_PROTOCOL_VERSION = '2025-06-18';
+export class HostedClient {
+    opts;
+    nextId = 1;
+    sessionId;
+    protocolVersion;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /** initialize + notifications/initialized + tools/list. */
+    async connect(timeoutMs) {
+        const init = (await this.request('initialize', {
+            protocolVersion: CLIENT_PROTOCOL_VERSION,
+            capabilities: {},
+            clientInfo: { name: this.opts.userAgent, version: this.opts.clientVersion },
+        }, timeoutMs));
+        if (init && typeof init.protocolVersion === 'string')
+            this.protocolVersion = init.protocolVersion;
+        await this.notify('notifications/initialized', timeoutMs);
+        return this.listTools(timeoutMs);
+    }
+    async listTools(timeoutMs) {
+        const result = (await this.request('tools/list', {}, timeoutMs));
+        if (!result || !Array.isArray(result.tools) || result.tools.length === 0) {
+            throw new HostedUnavailable('tools/list returned no tools');
+        }
+        return result.tools;
+    }
+    async callTool(name, args, timeoutMs) {
+        const result = (await this.request('tools/call', { name, arguments: args }, timeoutMs));
+        if (!result || !Array.isArray(result.content)) {
+            throw new HostedUnavailable('tools/call returned no content');
+        }
+        return result;
+    }
+    async notify(method, timeoutMs) {
+        await this.post({ jsonrpc: '2.0', method }, timeoutMs);
+    }
+    async request(method, params, timeoutMs) {
+        const id = this.nextId++;
+        const message = await this.post({ jsonrpc: '2.0', id, method, params }, timeoutMs, id);
+        if (!message)
+            throw new HostedUnavailable(`${method}: no response`);
+        if (message.error) {
+            const e = message.error;
+            throw new HostedRpcError(typeof e.code === 'number' ? e.code : -32603, e.message ?? 'Unknown error', e.data);
+        }
+        return message.result;
+    }
+    async post(body, timeoutMs, id) {
+        const headers = {
+            Authorization: `Bearer ${this.opts.apiKey}`,
+            'Content-Type': 'application/json',
+            Accept: 'application/json, text/event-stream',
+            'User-Agent': this.opts.userAgent,
+            // Names this client on every request (TB-740). The hosted server
+            // forwards it on its REST calls so the call log can tell npm-bridge
+            // usage from other clients; it must match `@tickerbot/mcp-server/<semver>`.
+            'X-Tickerbot-MCP-Client': this.opts.clientLabel,
+        };
+        if (this.sessionId)
+            headers['mcp-session-id'] = this.sessionId;
+        if (this.protocolVersion)
+            headers['mcp-protocol-version'] = this.protocolVersion;
+        let res;
+        try {
+            res = await fetch(this.opts.url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+        }
+        catch (err) {
+            const reason = err instanceof Error ? (err.name === 'TimeoutError' ? `timed out after ${timeoutMs} ms` : err.message) : String(err);
+            throw new HostedUnavailable(`${this.opts.url}: ${reason}`);
+        }
+        const session = res.headers.get('mcp-session-id');
+        if (session)
+            this.sessionId = session;
+        if (res.status === 202)
+            return null;
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new HostedUnavailable(`${this.opts.url} answered ${res.status}${text ? `: ${text.slice(0, 300)}` : ''}`, res.status);
+        }
+        if (id === undefined) {
+            await res.body?.cancel().catch(() => { });
+            return null;
+        }
+        const type = res.headers.get('content-type') ?? '';
+        const text = await res.text();
+        const candidates = type.includes('text/event-stream') ? parseSse(text) : [parseJson(text)];
+        for (const c of candidates.flatMap((m) => (Array.isArray(m) ? m : [m]))) {
+            if (c && typeof c === 'object' && c.id === id)
+                return c;
+        }
+        throw new HostedUnavailable(`${this.opts.url}: no JSON-RPC response for id ${id}`);
+    }
+}
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+// Each SSE event's data lines joined, parsed as JSON.
+function parseSse(text) {
+    const out = [];
+    for (const event of text.split(/\r?\n\r?\n/)) {
+        const data = event
+            .split(/\r?\n/)
+            .filter((l) => l.startsWith('data:'))
+            .map((l) => l.slice(5).replace(/^ /, ''))
+            .join('\n');
+        if (data)
+            out.push(parseJson(data));
+    }
+    return out;
+}

package/dist/index.js

@@ -1,82 +1,117 @@
-// Stdio MCP server entrypoint.
+// Stdio MCP server entrypoint: a thin bridge to the hosted Tickerbot MCP
+// server (TB-740).
 //
-// Local install target. Launched by the user's MCP client (Claude Desktop,
-// Claude Code, Cursor, VS Code Copilot, etc.) as a subprocess that talks
-// JSON-RPC over stdin/stdout.
+// Launched by the user's MCP client (Claude Desktop, Claude Code, Cursor,
+// VS Code Copilot, etc.) as a subprocess that talks JSON-RPC over
+// stdin/stdout. The key comes from TICKERBOT_API_KEY.
 //
-// Reads the API key from TICKERBOT_API_KEY and forwards every tool call
-// through src/handler.ts → api.tickerbot.io.
+// On start it connects to {baseUrl}/mcp (https://api.tickerbot.io/mcp) with
+// the key, and the tool list it serves is the hosted server's tools/list,
+// verbatim. Every tools/call is forwarded there and its result returned
+// unchanged. So a tool added or changed on main_service reaches npm users on
+// their client's next launch, with no npm publish.
 //
-// Tool catalog: at startup, this subprocess fetches the live catalog from
-// {baseUrl}/mcp/tools. main_service is the single source of truth — any
-// add/rename/description-tweak on the server side shows up here on the
-// next subprocess spawn (which means the next Claude Desktop relaunch).
-// If the fetch fails (offline, server down, network error), we fall back
-// to the baked snapshot in tools.ts so the package still works.
+// Fallback: if the hosted server cannot be reached at start, the bridge
+// serves the bundled snapshot (src/tools.ts) and runs calls itself against
+// the REST API (src/handler.ts), and says so on stderr. While in fallback it
+// retries the hosted server on tools/list, at most once a minute, and
+// switches over when it answers.
+//
+// With no key the bridge does not contact the server (it would answer 401):
+// it serves the snapshot, and every call answers the missing-key message.
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, McpError, } from '@modelcontextprotocol/sdk/types.js';
 import { tools as bakedTools } from './tools.js';
 import { runTool, ToolError } from './handler.js';
+import { HostedClient, HostedRpcError } from './hosted.js';
 import { createRequire } from 'node:module';
 // package.json is the one place the version lives; the hardcoded '0.1.0'
-// this replaced was reported to every client through 0.2.1.
-const { name: SERVER_NAME, version: SERVER_VERSION } = createRequire(import.meta.url)('../package.json');
+// this replaced was reported to every client through 0.2.1. The mcpb bundle
+// is CJS with no import.meta.url and no package.json beside it, so
+// scripts/build-mcpb.sh inlines the two fields as TICKERBOT_MCP_PACKAGE.
+const { name: SERVER_NAME, version: SERVER_VERSION } = (process.env.TICKERBOT_MCP_PACKAGE
+    ? JSON.parse(process.env.TICKERBOT_MCP_PACKAGE)
+    : createRequire(import.meta.url)('../package.json'));
 const DEFAULT_BASE_URL = 'https://api.tickerbot.io';
-const DISCOVERY_TIMEOUT_MS = 3000;
-async function fetchLiveCatalog(baseUrl) {
-    const url = `${baseUrl}/mcp/tools`;
-    try {
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), DISCOVERY_TIMEOUT_MS);
-        const res = await fetch(url, {
-            headers: { Accept: 'application/json', 'User-Agent': '@tickerbot/mcp-server' },
-            signal: controller.signal,
-        });
-        clearTimeout(timer);
-        if (!res.ok) {
-            process.stderr.write(`[tickerbot-mcp] discovery: ${url} returned ${res.status}; using baked snapshot\n`);
-            return null;
-        }
-        const body = (await res.json());
-        if (!Array.isArray(body.tools) || body.tools.length === 0) {
-            process.stderr.write(`[tickerbot-mcp] discovery: malformed response from ${url}; using baked snapshot\n`);
-            return null;
-        }
-        return body.tools;
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        process.stderr.write(`[tickerbot-mcp] discovery: ${url} failed (${message}); using baked snapshot\n`);
-        return null;
-    }
+const CONNECT_TIMEOUT_MS = Number(process.env.TICKERBOT_MCP_CONNECT_TIMEOUT_MS) || 5000;
+const CALL_TIMEOUT_MS = 120_000;
+const RETRY_INTERVAL_MS = 60_000;
+const USER_AGENT = `${SERVER_NAME}/${SERVER_VERSION}`;
+function log(line) {
+    process.stderr.write(`[tickerbot-mcp] ${line}\n`);
+}
+function snapshotTools() {
+    return bakedTools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema,
+    }));
 }
 async function main() {
     const apiKey = process.env.TICKERBOT_API_KEY;
     if (!apiKey) {
-        process.stderr.write(`[tickerbot-mcp] TICKERBOT_API_KEY is not set. Get a key from https://tickerbot.io/dashboard and add it to your MCP client config (env block).\n`);
+        log(`TICKERBOT_API_KEY is not set. Get a key from https://tickerbot.io/dashboard and add it to your MCP client config (env block).`);
+    }
+    const baseUrl = (process.env.TICKERBOT_API_URL || DEFAULT_BASE_URL).replace(/\/+$/, '');
+    const hostedUrl = `${baseUrl}/mcp`;
+    const hosted = apiKey
+        ? new HostedClient({ url: hostedUrl, apiKey, userAgent: USER_AGENT, clientVersion: SERVER_VERSION, clientLabel: `${SERVER_NAME}/${SERVER_VERSION}` })
+        : null;
+    // 'hosted': tools and calls go to {baseUrl}/mcp. 'snapshot': the bundled
+    // fallback, calls run here against the REST API.
+    let mode = 'snapshot';
+    let activeTools = snapshotTools();
+    let lastAttempt = 0;
+    async function tryHosted() {
+        if (!hosted)
+            return false;
+        lastAttempt = Date.now();
+        try {
+            activeTools = await hosted.connect(CONNECT_TIMEOUT_MS);
+            mode = 'hosted';
+            return true;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            log(`WARNING: hosted MCP server unreachable (${message}). Serving the bundled snapshot of ${bakedTools.length} tools, which may be out of date; retrying at most once a minute.`);
+            return false;
+        }
     }
-    const baseUrl = process.env.TICKERBOT_API_URL || DEFAULT_BASE_URL;
-    // Fetch the live catalog before announcing tools. The handshake (`initialize`
-    // + `tools/list`) happens after server.connect(), so we have a window to
-    // populate `activeTools` with the server's current view.
-    const live = await fetchLiveCatalog(baseUrl);
-    const activeTools = live ?? bakedTools;
-    const catalogSource = live ? 'live' : 'snapshot';
-    const toolMap = new Map(activeTools.map((t) => [t.name, t]));
-    const findTool = (name) => toolMap.get(name);
+    // Connect before announcing tools. The client's initialize + tools/list
+    // arrive after server.connect(), so they always see the result.
+    await tryHosted();
     const server = new Server({ name: SERVER_NAME, version: SERVER_VERSION }, { capabilities: { tools: {} } });
-    server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: activeTools.map((t) => ({
-            name: t.name,
-            description: t.description,
-            inputSchema: t.inputSchema,
-        })),
-    }));
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        if (mode === 'snapshot' && hosted && Date.now() - lastAttempt >= RETRY_INTERVAL_MS) {
+            if (await tryHosted())
+                log(`hosted MCP server reachable again; serving its ${activeTools.length} tools`);
+        }
+        return { tools: activeTools };
+    });
     server.setRequestHandler(CallToolRequestSchema, async (req) => {
         const { name, arguments: args } = req.params;
+        if (mode === 'hosted' && hosted) {
+            try {
+                return await hosted.callTool(name, (args ?? {}), CALL_TIMEOUT_MS);
+            }
+            catch (err) {
+                if (err instanceof HostedRpcError)
+                    throw new McpError(err.code, err.message, err.data);
+                // Not retried locally: the call may have reached the server (a POST
+                // that creates a webhook must not run twice).
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    content: [{ type: 'text', text: `Tickerbot MCP server unreachable: ${message}` }],
+                    isError: true,
+                };
+            }
+        }
         try {
-            const result = await runTool(name, (args ?? {}), apiKey ?? '', { baseUrl, findTool });
+            const result = await runTool(name, (args ?? {}), apiKey ?? '', {
+                baseUrl,
+                userAgent: USER_AGENT,
+            });
             return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
         }
         catch (err) {
@@ -93,7 +128,7 @@ async function main() {
     });
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    process.stderr.write(`[tickerbot-mcp] ${SERVER_NAME} v${SERVER_VERSION} ready (${activeTools.length} tools, catalog: ${catalogSource})\n`);
+    log(`${SERVER_NAME} v${SERVER_VERSION} ready (${activeTools.length} tools, catalog: ${mode === 'hosted' ? hostedUrl : 'bundled snapshot'})`);
 }
 function formatToolError(err) {
     const parts = [err.message];
@@ -108,6 +143,6 @@ function formatToolError(err) {
     return parts.join('\n');
 }
 main().catch((err) => {
-    process.stderr.write(`[tickerbot-mcp] fatal: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+    log(`fatal: ${err instanceof Error ? err.stack ?? err.message : String(err)}`);
     process.exit(1);
 });

package/dist/tools.d.ts

@@ -19,9 +19,6 @@ export interface ToolDef {
         /** An older path-param name -> the slot the docs name it by (TB-570
          *  step 3: `id` fills {universe} / {webhook}, `delivery_id` {delivery}). */
         pathAliases?: Record<string, string>;
-        /** Query values every call sends (TB-570 step 3: `api_version`, so
-         *  Bars and History answer the `data` shape the descriptions name). */
-        fixedQuery?: Record<string, string>;
         /** Body fields every call sends (a deprecated tool built from its
          *  successor: tickerbot_enable_webhook is PATCH `enabled: true`). */
         fixedBody?: Record<string, unknown>;
@@ -32,6 +29,8 @@ interface JsonSchemaProp {
     description: string;
     enum?: readonly string[];
     default?: unknown;
+    /** A regex the value must match (an id form, a date). */
+    pattern?: string;
     items?: {
         type: string;
     };