bykaranteli-mcp 0.7.3 → 0.9.0

package/README.md

@@ -7,7 +7,7 @@ MCP (Model Context Protocol) server for **live crypto derivatives data**: fundin
 ## Hosted endpoint (no install)
 
 Paste `https://mcp.bykaranteli.com` as a custom connector in any MCP-capable
-assistant. Same 20 tools, nothing to install, no key.
+assistant. Same 23 tools, nothing to install, no key.
 
 ## Quick start
 
@@ -91,7 +91,7 @@ MIT. Attribution appreciated: "ByKaranteli (bykaranteli.com)".
 
 ## Paid depth (optional)
 
-The 20 tools above are free and stay free. For recorded history and raw records
+The 23 tools above are free and stay free. For recorded history and raw records
 beyond the live snapshots, bykaranteli.com also exposes pay-per-call x402
 endpoints (USDC on Solana or Base, priced per call, no account):
 <https://bykaranteli.com/developers#x402> · machine catalog:

package/dist/tools.js

@@ -24,7 +24,10 @@ export function registerByKaranteliTools(server, options) {
                 headers: { accept: "application/json", "user-agent": USER_AGENT },
             });
             if (!res.ok) {
-                throw new Error(`${path} returned HTTP ${res.status}`);
+                /* Carry the route's own error body (audit P3 #412): "HTTP 400" alone
+                 * hid the actual reason (unknown metric, bad symbol...). */
+                const body = (await res.text().catch(() => "")).replace(/\s+/g, " ").slice(0, 240);
+                throw new Error(`${path} returned HTTP ${res.status}${body ? `: ${body}` : ""}`);
             }
             return await res.json();
         }
@@ -32,14 +35,29 @@ export function registerByKaranteliTools(server, options) {
             clearTimeout(timer);
         }
     }
+    /* Every answer carries where it came from and when (README promise; audit
+     * P3 #416): routes that already emit these keep their own values. */
+    function withProvenance(data, path) {
+        if (!data || typeof data !== "object" || Array.isArray(data))
+            return data;
+        const record = data;
+        return {
+            ...record,
+            generatedAt: typeof record.generatedAt === "string" ? record.generatedAt : new Date().toISOString(),
+            source: typeof record.source === "string" ? record.source : `${PUBLIC_URL}${path.replace(/^\/api\/public/, "").split("?")[0] || "/"}`,
+        };
+    }
     function ok(data) {
         return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
     }
     function fail(err) {
         const message = err instanceof Error ? err.message : String(err);
+        const permanent = /returned HTTP 4\d\d/.test(message);
         const text = err instanceof InputError
             ? `Invalid input: ${message}`
-            : `Error fetching data from bykaranteli.com: ${message}. The API is free and unauthenticated; transient errors usually resolve on retry.`;
+            : permanent
+                ? `Error fetching data from bykaranteli.com: ${message}. This is a permanent error for these inputs (wrong parameter or route), not a transient one; retrying will not help.`
+                : `Error fetching data from bykaranteli.com: ${message}. The API is free and unauthenticated; transient errors usually resolve on retry.`;
         return {
             content: [{ type: "text", text }],
             isError: true,
@@ -88,7 +106,7 @@ export function registerByKaranteliTools(server, options) {
     });
     server.registerTool("get_liquidations", {
         title: "Crypto liquidations: daily long/short totals per symbol and exchange",
-        description: "Call this when the user asks how much was liquidated in crypto futures, whether longs or shorts got flushed, or for liquidation history. Returns daily long and short liquidation totals in USD per symbol and exchange, recorded from ByKaranteli's own Binance, Bybit and OKX stream collectors (recorded events, a floor, not estimates). One row per finalized UTC day, symbol and exchange; history begins 2026-07-30 and grows daily.",
+        description: "Call this when the user asks how much was liquidated in crypto futures, whether longs or shorts got flushed, or for liquidation history. Returns daily long and short liquidation totals in USD per symbol and exchange, recorded from ByKaranteli's own Binance, Bybit, OKX, Gate and HTX stream collectors (recorded events, a floor, not estimates). One row per finalized UTC day, symbol and exchange; history begins 2026-07-30 and grows daily.",
         inputSchema: {
             symbol: z
                 .string()
@@ -107,10 +125,70 @@ export function registerByKaranteliTools(server, options) {
             const wantDays = days ?? 7;
             const dates = [...new Set(rows.map((r) => String(r.date)))].sort().reverse().slice(0, wantDays);
             const dateSet = new Set(dates);
-            const filtered = rows.filter((r) => dateSet.has(String(r.date)) && (!symbol || String(r.symbol).toUpperCase() === symbol));
+            /* Bare "BTC" is accepted like every other tool (audit P3 #414). */
+            const wantSymbol = symbol ? (symbol.endsWith("USDT") ? symbol : `${symbol}USDT`) : undefined;
+            const filtered = rows.filter((r) => dateSet.has(String(r.date)) && (!wantSymbol || String(r.symbol).toUpperCase() === wantSymbol));
+            /* Totals are computed over EVERY matching row before the row cap. A
+             * symbol-less 7-day call matches ~7,000 rows; returning only the first
+             * 400 (one day, alphabetically) used to understate the weekly total
+             * 11.5x with no warning in the payload (audit 2026-08-20 P1-67). */
+            const num = (v) => {
+                const n = Number(v);
+                return Number.isFinite(n) ? n : 0;
+            };
+            const byDate = new Map();
+            let longTotal = 0;
+            let shortTotal = 0;
+            let eventsTotal = 0;
+            for (const r of filtered) {
+                const date = String(r.date);
+                const long = num(r.long_liquidations_usd);
+                const short = num(r.short_liquidations_usd);
+                const events = num(r.events);
+                longTotal += long;
+                shortTotal += short;
+                eventsTotal += events;
+                const day = byDate.get(date) ?? { date, long_liquidations_usd: 0, short_liquidations_usd: 0, events: 0, rows: 0 };
+                day.long_liquidations_usd += long;
+                day.short_liquidations_usd += short;
+                day.events += events;
+                day.rows += 1;
+                byDate.set(date, day);
+            }
+            const MAX_ROWS = 400;
+            /* Largest rows first within the cap, newest day first. */
+            const ordered = [...filtered].sort((a, b) => {
+                const dd = String(b.date).localeCompare(String(a.date));
+                if (dd !== 0)
+                    return dd;
+                return (num(b.long_liquidations_usd) + num(b.short_liquidations_usd)) - (num(a.long_liquidations_usd) + num(a.short_liquidations_usd));
+            });
+            const truncated = ordered.length > MAX_ROWS;
+            const baseNote = "Recorded from public exchange streams; totals are a floor (Binance throttles its stream). Live 24h view: " + PUBLIC_URL + "/liquidations";
             return ok({
-                rows: filtered.slice(0, 400),
-                note: "Recorded from public exchange streams; totals are a floor (Binance throttles its stream). Live 24h view: " + PUBLIC_URL + "/liquidations",
+                summary: {
+                    window_days: wantDays,
+                    dates_covered: dates,
+                    totals: {
+                        long_liquidations_usd: Math.round(longTotal),
+                        short_liquidations_usd: Math.round(shortTotal),
+                        total_liquidations_usd: Math.round(longTotal + shortTotal),
+                        events: eventsTotal,
+                        rows_matched: filtered.length,
+                    },
+                    by_date: [...byDate.values()].sort((a, b) => b.date.localeCompare(a.date)).map((d) => ({
+                        ...d,
+                        long_liquidations_usd: Math.round(d.long_liquidations_usd),
+                        short_liquidations_usd: Math.round(d.short_liquidations_usd),
+                    })),
+                },
+                rows: ordered.slice(0, MAX_ROWS),
+                rows_returned: Math.min(ordered.length, MAX_ROWS),
+                rows_matched: filtered.length,
+                truncated,
+                note: truncated
+                    ? `rows is capped at ${MAX_ROWS} of ${filtered.length} matching rows (largest first). Use summary.totals and summary.by_date for complete figures, or pass a symbol filter. ` + baseNote
+                    : baseNote,
                 source: `${PUBLIC_URL}/liquidations`,
             });
         }
@@ -142,8 +220,8 @@ export function registerByKaranteliTools(server, options) {
         }
     });
     server.registerTool("get_funding_heatmap", {
-        title: "Funding rates across top-30 Binance perps",
-        description: "Call this when the user asks for the full current funding table across the top-30 Binance perp universe, or the funding rate of one specific coin. For a pre-ranked top-10 of the most extreme funding rates, use get_top_movers instead. Returns per-symbol funding rate (per settlement interval), 24h open interest change and 24h price change for the top-30 Binance USDT-M perpetuals. Positive funding means longs pay shorts.",
+        title: "Funding rates across the ~30 most traded Binance perps",
+        description: "Call this when the user asks for the full current funding table across the ~30 most traded Binance perps (28-30 rows; contracts without a live funding print are skipped), or the funding rate of one specific coin. For a pre-ranked top-10 of the most extreme funding rates, use get_top_movers instead. Returns per-symbol funding rate (per settlement interval), 24h open interest change and 24h price change for the most traded Binance USDT-M perpetuals. Positive funding means longs pay shorts.",
         inputSchema: {
             symbol: z
                 .string()
@@ -160,7 +238,7 @@ export function registerByKaranteliTools(server, options) {
                 if (!row) {
                     return ok({
                         generatedAt: d.generatedAt,
-                        note: `${want} is not in the top-30 heatmap set. Tracked symbols: ${d.rows.map((r) => r.symbol).join(", ")}`,
+                        note: `${want} is not in the heatmap set. Tracked symbols: ${d.rows.map((r) => r.symbol).join(", ")}`,
                     });
                 }
                 return ok({ generatedAt: d.generatedAt, row, source: `${PUBLIC_URL}/heatmap` });
@@ -327,7 +405,7 @@ export function registerByKaranteliTools(server, options) {
         annotations: READ_ONLY,
     }, async () => {
         try {
-            return ok(await fetchJson("/api/public/cot"));
+            return ok(withProvenance(await fetchJson("/api/public/cot"), "/api/public/cot"));
         }
         catch (err) {
             return fail(err);
@@ -340,7 +418,7 @@ export function registerByKaranteliTools(server, options) {
         annotations: READ_ONLY,
     }, async () => {
         try {
-            return ok(await fetchJson("/api/public/options"));
+            return ok(withProvenance(await fetchJson("/api/public/options"), "/api/public/options"));
         }
         catch (err) {
             return fail(err);
@@ -353,7 +431,7 @@ export function registerByKaranteliTools(server, options) {
         annotations: READ_ONLY,
     }, async () => {
         try {
-            return ok(await fetchJson("/api/public/premium"));
+            return ok(withProvenance(await fetchJson("/api/public/premium"), "/api/public/premium"));
         }
         catch (err) {
             return fail(err);
@@ -366,7 +444,7 @@ export function registerByKaranteliTools(server, options) {
         annotations: READ_ONLY,
     }, async () => {
         try {
-            return ok(await fetchJson("/api/public/flow"));
+            return ok(withProvenance(await fetchJson("/api/public/flow"), "/api/public/flow"));
         }
         catch (err) {
             return fail(err);
@@ -379,7 +457,7 @@ export function registerByKaranteliTools(server, options) {
         annotations: READ_ONLY,
     }, async () => {
         try {
-            return ok(await fetchJson("/api/public/options-flow"));
+            return ok(withProvenance(await fetchJson("/api/public/options-flow"), "/api/public/options-flow"));
         }
         catch (err) {
             return fail(err);
@@ -392,7 +470,7 @@ export function registerByKaranteliTools(server, options) {
         annotations: READ_ONLY,
     }, async () => {
         try {
-            return ok(await fetchJson("/api/public/slippage"));
+            return ok(withProvenance(await fetchJson("/api/public/slippage"), "/api/public/slippage"));
         }
         catch (err) {
             return fail(err);
@@ -405,7 +483,7 @@ export function registerByKaranteliTools(server, options) {
         annotations: READ_ONLY,
     }, async () => {
         try {
-            return ok(await fetchJson("/api/public/events"));
+            return ok(withProvenance(await fetchJson("/api/public/events"), "/api/public/events"));
         }
         catch (err) {
             return fail(err);
@@ -418,7 +496,7 @@ export function registerByKaranteliTools(server, options) {
         annotations: READ_ONLY,
     }, async () => {
         try {
-            return ok(await fetchJson("/api/public/incidents"));
+            return ok(withProvenance(await fetchJson("/api/public/incidents"), "/api/public/incidents"));
         }
         catch (err) {
             return fail(err);
@@ -431,7 +509,7 @@ export function registerByKaranteliTools(server, options) {
         annotations: READ_ONLY,
     }, async () => {
         try {
-            return ok(await fetchJson("/api/public/oi"));
+            return ok(withProvenance(await fetchJson("/api/public/oi"), "/api/public/oi"));
         }
         catch (err) {
             return fail(err);
@@ -444,7 +522,187 @@ export function registerByKaranteliTools(server, options) {
         annotations: READ_ONLY,
     }, async () => {
         try {
-            return ok(await fetchJson("/api/public/charge"));
+            return ok(withProvenance(await fetchJson("/api/public/charge"), "/api/public/charge"));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool("get_altseason", {
+        title: "Altcoin Season Index (live + recorded history)",
+        description: "Call this when the user asks whether it is altseason, how altcoins are doing against Bitcoin, or about market rotation. Returns the live Altcoin Season Index (share of the top 50 Binance perpetual altcoins beating BTC over the trailing 90 days; >=75 altseason, <=25 bitcoin season), the strongest and weakest large alts, and the recorded daily history (never reconstructed).",
+        inputSchema: {},
+        annotations: READ_ONLY,
+    }, async () => {
+        try {
+            return ok(withProvenance(await fetchJson("/api/public/altseason"), "/api/public/altseason"));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool("get_quantum_exposure", {
+        title: "Quantum-exposed Bitcoin (daily first-party measurement)",
+        description: "Call this when the user asks how much Bitcoin is vulnerable to a quantum computer, about quantum-exposed supply, P2PK coins, or Satoshi-era exposure. Returns the latest daily measurement from ByKaranteli's own Bitcoin Core node: exposed BTC and its share of held value and UTXO count, composition by script family, dormancy cohorts, the dormant-P2PK watch set, and provenance hashes (base_height, base_hash, txoutset_hash) so any figure can be re-verified against any node.",
+        inputSchema: {},
+        annotations: READ_ONLY,
+    }, async () => {
+        try {
+            return ok(withProvenance(await fetchJson("/api/public/quantum"), "/api/public/quantum"));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool("get_metric_context", {
+        title: "Historical context for any recorded metric (conditional distribution)",
+        description: "Call this when the user asks whether a metric's current reading is high or low, or what happened after similar readings. Buckets today's value against the metric's own recorded daily history and returns the median forward BTC return and up-share per bucket at +1/+3/+7 days, with the all-days base rate alongside. Honesty rules: buckets under 30 days are suppressed, and most metrics do NOT separate from the base rate; the interpretation says so plainly. History, not a forecast. Metrics include coinbase_premium_pct, kraken_btc_premium_pct, dvol_btc, fear_greed, funding_btc_daily_pct, etf_btc_net_flow_usd, vpin_btc, altseason_index, stablecoin_total_mcap_busd, fred_dff, fred_dgs10, fred_walcl_busd, fred_rrp_busd and the btc_* network series.",
+        inputSchema: {
+            metric: z
+                .string()
+                .regex(/^[a-z0-9_]{2,50}$/)
+                .describe("Metric key, e.g. coinbase_premium_pct, fear_greed, altseason_index, stablecoin_total_mcap_busd."),
+        },
+        annotations: READ_ONLY,
+    }, async ({ metric }) => {
+        try {
+            return ok(withProvenance(await fetchJson(`/api/public/context?metric=${encodeURIComponent(metric)}`), `/api/public/context?metric=${encodeURIComponent(metric)}`));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool("get_theme_indices", {
+        title: "Crypto narrative indices (AI, RWA, DePIN, meme, L1, L2, DeFi, quantum)",
+        description: "Call this when the user asks which crypto narrative or sector is leading, about rotation between AI, RWA, DePIN, memecoins, layer 1, layer 2, DeFi or quantum coins, or for a theme index. Returns eight equal-weight fixed-basket indices rebased to 100 on 2025-01-01 with 1d/7d/30d/90d/YTD returns, vs BTC, and the member lists; daily points are omitted unless include_points is true.",
+        inputSchema: { include_points: z.boolean().optional().describe("boolean, optional: include the daily index points (large)") },
+        annotations: READ_ONLY,
+    }, async (args) => {
+        try {
+            const path = args.include_points === true ? "/api/public/themes" : "/api/public/themes?points=0";
+            return ok(withProvenance(await fetchJson(path), path));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool("get_factor_board", {
+        title: "Factor board: what followed days like today across recorded metrics",
+        description: "Call this when the user asks which indicators currently sit in an unusual band, whether a metric's current level historically preceded BTC moves, or for a cross-metric conditional overview. Returns every recorded metric in its historical band with the median 7-day BTC move that followed versus the base rate, with an n >= 30 gate; distributions, not forecasts.",
+        inputSchema: {},
+        annotations: READ_ONLY,
+    }, async () => {
+        try {
+            return ok(withProvenance(await fetchJson("/api/public/factors"), "/api/public/factors"));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool("get_venue_markets", {
+        title: "Exchange coverage: OI, volume, funding and pegs across 43 exchanges",
+        description: "Call this when the user asks about total open interest across exchanges, which venues hold the most OI, DEX versus CEX share, funding dispersion between venues, or stablecoin pegs. Returns the latest 10-minute snapshot aggregates across 56 feeds on 43 exchanges; pass symbol for one coin's per-venue rows.",
+        inputSchema: { symbol: z.string().optional().describe("string, optional base asset, e.g. BTC") },
+        annotations: READ_ONLY,
+    }, async (args) => {
+        try {
+            const path = args.symbol ? `/api/public/venues/markets?symbol=${encodeURIComponent(args.symbol.toUpperCase())}` : "/api/public/venues/markets";
+            return ok(withProvenance(await fetchJson(path), path));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool("get_lead_lag", {
+        title: "Venue lead-lag: who moves first (Coinbase, Kraken, Binance)",
+        description: "Call this when the user asks which exchange leads price discovery or whether spot or perp moves first. Returns per-pair daily cross-correlations of one-minute returns at lags -3..+3 and the lead asymmetry, with the share of days each venue led.",
+        inputSchema: {},
+        annotations: READ_ONLY,
+    }, async () => {
+        try {
+            return ok(withProvenance(await fetchJson("/api/public/venues/lead-lag"), "/api/public/venues/lead-lag"));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool("get_iv_surface", {
+        title: "Options implied-volatility surface and 25-delta skew",
+        description: "Call this when the user asks about implied volatility by strike or expiry, skew, put versus call IV, term structure of IV, or whether downside protection is expensive. Returns the IV surface (expiry x moneyness), per-expiry ATM / 25-delta put and call IV, skew and butterfly, and the constant-30d history, from the daily Deribit chain.",
+        inputSchema: { currency: z.string().optional().describe("BTC or ETH, default BTC") },
+        annotations: READ_ONLY,
+    }, async (args) => {
+        try {
+            const path = `/api/public/options/surface?currency=${(args.currency ?? "BTC").toUpperCase() === "ETH" ? "ETH" : "BTC"}`;
+            return ok(withProvenance(await fetchJson(path), path));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool("get_whale_tape", {
+        title: "Whale tape: $1M+ aggressive prints with 24h buy share",
+        description: "Call this when the user asks about whale trades, large market orders, or whether big players are buying or selling right now. Returns recent $1M+ aggressive prints recorded live from our own sockets and 24h aggregates with the buy share.",
+        inputSchema: {},
+        annotations: READ_ONLY,
+    }, async () => {
+        try {
+            return ok(withProvenance(await fetchJson("/api/public/whales"), "/api/public/whales"));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool("get_correlations", {
+        title: "Crypto correlation matrix",
+        description: "Call this when the user asks how correlated two coins are, for decorrelated pairs, or how tightly alts track BTC. Returns the 30-day rolling Pearson correlation matrix of daily returns across the top perpetuals.",
+        inputSchema: {},
+        annotations: READ_ONLY,
+    }, async () => {
+        try {
+            return ok(withProvenance(await fetchJson("/api/public/correlations"), "/api/public/correlations"));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool("get_new_listings", {
+        title: "New and delisted perpetual contracts",
+        description: "Call this when the user asks what new perpetuals were listed, which exchange listed a coin first, or about delistings. Returns listings and delistings across six exchanges from the hourly scan.",
+        inputSchema: { days: z.number().optional().describe("number, optional window in days, default 30") },
+        annotations: READ_ONLY,
+    }, async (args) => {
+        try {
+            const path = `/api/public/listings?days=${args.days && args.days > 0 ? Math.floor(args.days) : 30}`;
+            return ok(withProvenance(await fetchJson(path), path));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool("get_macro_liquidity", {
+        title: "Macro liquidity: Fed funds, 10y, balance sheet, RRP, stablecoin supply",
+        description: "Call this when the user asks about macro liquidity, the Fed balance sheet, reverse repo, rates or stablecoin supply in relation to crypto. Returns the recorded daily series and latest values.",
+        inputSchema: { days: z.number().optional().describe("number, optional window in days, default 365") },
+        annotations: READ_ONLY,
+    }, async (args) => {
+        try {
+            const path = `/api/public/macro?days=${args.days && args.days > 0 ? Math.floor(args.days) : 365}`;
+            return ok(withProvenance(await fetchJson(path), path));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool("get_network_health", {
+        title: "Bitcoin network health from our own node",
+        description: "Call this when the user asks about Bitcoin hashrate, difficulty, fees or mempool congestion. Returns the recorded daily series and latest values measured on ByKaranteli's own node.",
+        inputSchema: { days: z.number().optional().describe("number, optional window in days, default 365") },
+        annotations: READ_ONLY,
+    }, async (args) => {
+        try {
+            const path = `/api/public/network?days=${args.days && args.days > 0 ? Math.floor(args.days) : 365}`;
+            return ok(withProvenance(await fetchJson(path), path));
         }
         catch (err) {
             return fail(err);

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "bykaranteli-mcp",
-  "version": "0.7.3",
+  "version": "0.9.0",
   "description": "MCP server for live crypto derivatives data from bykaranteli.com: funding rates, funding arbitrage, open interest pressure, Fear & Greed, BTC dominance and verified signal performance. Free, no API key.",
   "type": "module",
   "bin": {
     "bykaranteli-mcp": "dist/index.js"
   },
-  "main": "dist/index.js",
+  "main": "dist/tools.js",
   "files": [
     "dist",
     "README.md",