bykaranteli-mcp 0.8.0 → 0.9.1

package/README.md

@@ -2,12 +2,12 @@
 
 MCP (Model Context Protocol) server for **live crypto derivatives data**: funding rates, cross-exchange funding arbitrage, open interest pressure, Fear & Greed, BTC dominance and a verified signal track record.
 
-20 read-only tools over the free, no-auth public JSON API of [bykaranteli.com](https://bykaranteli.com/developers). No API key, no account, no rate-limit registration. Data covers Binance USDT-M perpetuals (funding arbitrage additionally compares OKX, Bybit, Gate, HTX and BingX).
+34 read-only tools over the free, no-auth public JSON API of [bykaranteli.com](https://bykaranteli.com/developers). No API key, no account, no rate-limit registration. Data covers Binance USDT-M perpetuals (funding arbitrage additionally compares OKX, Bybit, Gate, HTX, BingX, Kraken, MEXC and Bitget).
 
 ## 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 34 tools, nothing to install, no key.
 
 ## Quick start
 
@@ -62,6 +62,20 @@ Requires Node.js 18 or newer.
 | `get_liquidation_cascades` | "What caused that flush?", "Who got liquidated this week?" |
 | `get_open_interest` | "Is leverage entering the market?", "Are shorts building in XRP?" |
 | `get_psi_charge` | "What liquidity state is the market in?", "Is parked money deploying?" |
+| `get_theme_indices` | "Which crypto narrative is leading: AI, RWA, DePIN, memes, L2s, DeFi?" |
+| `get_factor_board` | "Which indicators sit in an unusual band today, and what followed historically?" |
+| `get_venue_markets` | "Total BTC open interest across exchanges?", "What is the DEX share of perp OI?", "Is USDT off peg anywhere?" |
+| `get_lead_lag` | "Does Coinbase or Binance move first?" |
+| `get_iv_surface` | "What is BTC implied vol by expiry?", "Is downside protection expensive (skew)?" |
+| `get_whale_tape` | "Are whales buying or selling right now?" |
+| `get_correlations` | "How correlated is SOL to BTC over 30 days?" |
+| `get_new_listings` | "Which perpetuals were listed this week, and where first?" |
+| `get_macro_liquidity` | "What is the Fed balance sheet / RRP / stablecoin supply doing?" |
+| `get_network_health` | "Bitcoin hashrate, difficulty, fees, mempool right now?" |
+| `get_altseason` | "Is it altseason?", "What is the altcoin season index?" |
+| `get_metric_context` | "Is today's funding extreme historically?", "Where does this reading sit in its distribution?" |
+| `get_quantum_exposure` | "How much Bitcoin is quantum-vulnerable?", "What is the P2PK exposure?" |
+| `get_liqmap` | "Where are the BTC liquidation clusters?", "Where would leveraged longs get liquidated?" |
 
 All responses are JSON and carry a `generatedAt` timestamp plus a `source` URL to the human-readable page. Symbols accept both `BTCUSDT` and bare `BTC`.
 
@@ -91,7 +105,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 34 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, 2000);
+                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, HTX and dYdX 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`,
             });
         }
@@ -131,9 +209,24 @@ export function registerByKaranteliTools(server, options) {
             const d = (await fetchJson("/api/v1/public/datasets/etf-flows.json"));
             const rows = Array.isArray(d.rows) ? d.rows : [];
             const filtered = rows.filter((r) => !asset || String(r.asset) === asset);
+            /* Window by DATE like get_liquidations (audit D14-03): the old row-count
+             * slice could cut one asset's day in half and reported no totals and no
+             * truncation flag, so partial sums read as full ones. */
+            const wantDays = days ?? 10;
+            const dates = [...new Set(filtered.map((r) => String(r.date)))].sort().reverse().slice(0, wantDays);
+            const dateSet = new Set(dates);
+            const windowed = filtered.filter((r) => dateSet.has(String(r.date)));
+            const totals = {};
+            for (const r of windowed) {
+                const a = String(r.asset);
+                totals[a] = (totals[a] ?? 0) + (Number(r.net_inflow_usd) || 0);
+            }
             return ok({
-                rows: filtered.slice(0, (days ?? 10) * (asset ? 1 : 2)),
-                note: "Finalized US trading days only; a positive net_inflow_usd means the funds bought more of the asset than they sold that day.",
+                rows: windowed,
+                window_days: dates.length,
+                window_net_inflow_usd: totals,
+                truncated: dates.length < new Set(filtered.map((r) => String(r.date))).size,
+                note: "Finalized US trading days only; a positive net_inflow_usd means the funds bought more of the asset than they sold that day. window_net_inflow_usd sums the returned window per asset.",
                 source: `${PUBLIC_URL}/etf`,
             });
         }
@@ -142,8 +235,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 +253,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` });
@@ -299,6 +392,7 @@ export function registerByKaranteliTools(server, options) {
             return ok({
                 ...d,
                 daily_points: Array.isArray(daily) ? daily.slice(-30) : daily,
+                daily_points_truncated: Array.isArray(daily) ? daily.length > 30 : false,
                 source: `${PUBLIC_URL}/symbols/${want}`,
             });
         }
@@ -327,7 +421,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 +434,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 +447,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 +460,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 +473,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 +486,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 +499,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 +512,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 +525,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 +538,7 @@ 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);
@@ -457,7 +551,7 @@ export function registerByKaranteliTools(server, options) {
         annotations: READ_ONLY,
     }, async () => {
         try {
-            return ok(await fetchJson("/api/public/altseason"));
+            return ok(withProvenance(await fetchJson("/api/public/altseason"), "/api/public/altseason"));
         }
         catch (err) {
             return fail(err);
@@ -470,7 +564,7 @@ export function registerByKaranteliTools(server, options) {
         annotations: READ_ONLY,
     }, async () => {
         try {
-            return ok(await fetchJson("/api/public/quantum"));
+            return ok(withProvenance(await fetchJson("/api/public/quantum"), "/api/public/quantum"));
         }
         catch (err) {
             return fail(err);
@@ -488,7 +582,168 @@ export function registerByKaranteliTools(server, options) {
         annotations: READ_ONLY,
     }, async ({ metric }) => {
         try {
-            return ok(await fetchJson(`/api/public/context?metric=${encodeURIComponent(metric)}`));
+            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().int().min(1).max(30).optional().describe("Window in days, 1-30 (default 30). Longer listing history is the paid x402 dataset.") },
+        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().int().min(1).max(730).optional().describe("Window in days, 1-730 (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().int().min(1).max(730).optional().describe("Window in days, 1-730 (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);
+        }
+    });
+    server.registerTool("get_liqmap", {
+        title: "LiqMap: estimated liquidation clusters with real prints overlaid",
+        description: "Call this when the user asks where liquidation clusters or liquidity pools sit for a perpetual, where leveraged longs/shorts would get liquidated, or for a liquidation heatmap reading. Returns the public LiqMap snapshot for one symbol: modeled liquidation levels by price, zone aggregates and real liquidation prints from six venues. Public tier serves the 24h view; other intervals are a member feature at the source page.",
+        inputSchema: {
+            symbol: z
+                .string()
+                .trim()
+                .toUpperCase()
+                .regex(/^[A-Z0-9]{2,20}$/)
+                .optional()
+                .describe("Symbol like BTCUSDT (bare BTC accepted). Default BTCUSDT."),
+        },
+        annotations: READ_ONLY,
+    }, async ({ symbol }) => {
+        try {
+            const raw = symbol ?? "BTCUSDT";
+            const sym = raw.endsWith("USDT") ? raw : `${raw}USDT`;
+            const path = `/api/liqmap/public?symbol=${encodeURIComponent(sym)}&timeframe=24h`;
+            const data = await fetchJson(path);
+            return ok({ ...data, source: `${PUBLIC_URL}/liqmap/${sym.replace(/USDT$/, "").toLowerCase()}` });
         }
         catch (err) {
             return fail(err);

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "bykaranteli-mcp",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "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",