bykaranteli-mcp 0.7.2 → 0.8.0

package/README.md

@@ -2,7 +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.
 
-Backed by 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).
+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).
+
+## 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.
 
 ## Quick start
 
@@ -83,3 +88,11 @@ node dist/index.js   # speaks MCP over stdio
 ## License
 
 MIT. Attribution appreciated: "ByKaranteli (bykaranteli.com)".
+
+## Paid depth (optional)
+
+The 20 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:
+<https://bykaranteli.com/api/x402>

package/dist/tools.d.ts

@@ -2,12 +2,17 @@
  * Tool registrations for the ByKaranteli MCP server, transport-agnostic.
  * The stdio bin (index.ts) and the hosted Streamable HTTP endpoint on
  * bykaranteli.com both call registerByKaranteliTools on their own server
- * instance, so the 10 tools have exactly one definition.
+ * instance, so all 20 tools have exactly one definition.
  */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 export type RegisterOptions = {
-    /** Override the public API origin (hosted endpoint uses the internal one). */
+    /** Override the API origin used for OUTBOUND fetches (the hosted endpoint
+     * points this at the container-internal origin). */
     baseUrl?: string;
+    /** Origin used in citations returned to the caller. Defaults to baseUrl.
+     * The hosted endpoint must set this, otherwise every response cites the
+     * container-internal address, which is useless to the agent reading it. */
+    publicUrl?: string;
     /** Version string for the outbound user-agent. */
     version?: string;
 };

package/dist/tools.js

@@ -2,11 +2,12 @@
  * Tool registrations for the ByKaranteli MCP server, transport-agnostic.
  * The stdio bin (index.ts) and the hosted Streamable HTTP endpoint on
  * bykaranteli.com both call registerByKaranteliTools on their own server
- * instance, so the 10 tools have exactly one definition.
+ * instance, so all 20 tools have exactly one definition.
  */
 import { z } from "zod/v4";
 export function registerByKaranteliTools(server, options) {
     const BASE_URL = (options?.baseUrl ?? process.env.BYKARANTELI_BASE_URL ?? "https://bykaranteli.com").replace(/\/+$/, "");
+    const PUBLIC_URL = (options?.publicUrl ?? process.env.BYKARANTELI_PUBLIC_URL ?? "https://bykaranteli.com").replace(/\/+$/, "");
     const USER_AGENT = `bykaranteli-mcp/${options?.version ?? "dev"} (+https://github.com/bykarantelicom/bykaranteli-mcp)`;
     const TIMEOUT_MS = 15_000;
     // Read-only GET tools over an open-world public API, all of them.
@@ -78,7 +79,7 @@ export function registerByKaranteliTools(server, options) {
                         explainer: euphoria.explainer,
                     }
                     : undefined,
-                source: `${BASE_URL}/indices`,
+                source: `${PUBLIC_URL}/indices`,
             });
         }
         catch (err) {
@@ -109,8 +110,8 @@ export function registerByKaranteliTools(server, options) {
             const filtered = rows.filter((r) => dateSet.has(String(r.date)) && (!symbol || String(r.symbol).toUpperCase() === symbol));
             return ok({
                 rows: filtered.slice(0, 400),
-                note: "Recorded from public exchange streams; totals are a floor (Binance throttles its stream). Live 24h view: " + BASE_URL + "/liquidations",
-                source: `${BASE_URL}/liquidations`,
+                note: "Recorded from public exchange streams; totals are a floor (Binance throttles its stream). Live 24h view: " + PUBLIC_URL + "/liquidations",
+                source: `${PUBLIC_URL}/liquidations`,
             });
         }
         catch (err) {
@@ -133,7 +134,7 @@ export function registerByKaranteliTools(server, options) {
             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.",
-                source: `${BASE_URL}/etf`,
+                source: `${PUBLIC_URL}/etf`,
             });
         }
         catch (err) {
@@ -162,9 +163,9 @@ export function registerByKaranteliTools(server, options) {
                         note: `${want} is not in the top-30 heatmap set. Tracked symbols: ${d.rows.map((r) => r.symbol).join(", ")}`,
                     });
                 }
-                return ok({ generatedAt: d.generatedAt, row, source: `${BASE_URL}/heatmap` });
+                return ok({ generatedAt: d.generatedAt, row, source: `${PUBLIC_URL}/heatmap` });
             }
-            return ok({ ...d, source: `${BASE_URL}/heatmap` });
+            return ok({ ...d, source: `${PUBLIC_URL}/heatmap` });
         }
         catch (err) {
             return fail(err);
@@ -178,7 +179,7 @@ export function registerByKaranteliTools(server, options) {
     }, async () => {
         try {
             const d = (await fetchJson("/api/public/funding-arb"));
-            return ok({ ...d, source: `${BASE_URL}/funding-arb` });
+            return ok({ ...d, source: `${PUBLIC_URL}/funding-arb` });
         }
         catch (err) {
             return fail(err);
@@ -221,13 +222,13 @@ export function registerByKaranteliTools(server, options) {
                         note: `${want} is not in the tracked pressure universe right now.`,
                     });
                 }
-                return ok({ generatedAt: d.generatedAt, item: slim(item), source: `${BASE_URL}/pressure` });
+                return ok({ generatedAt: d.generatedAt, item: slim(item), source: `${PUBLIC_URL}/pressure` });
             }
             return ok({
                 generatedAt: d.generatedAt,
                 items: d.items.slice(0, limit ?? 20).map(slim),
                 totalTracked: d.items.length,
-                source: `${BASE_URL}/pressure`,
+                source: `${PUBLIC_URL}/pressure`,
             });
         }
         catch (err) {
@@ -242,7 +243,7 @@ export function registerByKaranteliTools(server, options) {
     }, async () => {
         try {
             const d = (await fetchJson("/api/public/top-movers"));
-            return ok({ ...d, source: `${BASE_URL}/top-movers` });
+            return ok({ ...d, source: `${PUBLIC_URL}/top-movers` });
         }
         catch (err) {
             return fail(err);
@@ -256,7 +257,7 @@ export function registerByKaranteliTools(server, options) {
     }, async () => {
         try {
             const d = (await fetchJson("/api/public/recent"));
-            return ok({ ...d, source: `${BASE_URL}/signals` });
+            return ok({ ...d, source: `${PUBLIC_URL}/signals` });
         }
         catch (err) {
             return fail(err);
@@ -288,7 +289,7 @@ export function registerByKaranteliTools(server, options) {
                     return ok({
                         symbol: want,
                         window_days: w,
-                        note: `No closed signals recorded for ${want} in the last ${w} days (or the symbol is not tracked). Try window_days: 180, or check ${BASE_URL}/symbols/${want}.`,
+                        note: `No closed signals recorded for ${want} in the last ${w} days (or the symbol is not tracked). Try window_days: 180, or check ${PUBLIC_URL}/symbols/${want}.`,
                     });
                 }
                 throw err;
@@ -298,7 +299,7 @@ export function registerByKaranteliTools(server, options) {
             return ok({
                 ...d,
                 daily_points: Array.isArray(daily) ? daily.slice(-30) : daily,
-                source: `${BASE_URL}/symbols/${want}`,
+                source: `${PUBLIC_URL}/symbols/${want}`,
             });
         }
         catch (err) {
@@ -313,7 +314,7 @@ export function registerByKaranteliTools(server, options) {
     }, async () => {
         try {
             const d = (await fetchJson("/api/v1/public/leaderboard"));
-            return ok({ ...d, source: `${BASE_URL}/leaderboard` });
+            return ok({ ...d, source: `${PUBLIC_URL}/leaderboard` });
         }
         catch (err) {
             return fail(err);
@@ -449,4 +450,48 @@ export function registerByKaranteliTools(server, options) {
             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(await fetchJson("/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(await fetchJson("/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(await fetchJson(`/api/public/context?metric=${encodeURIComponent(metric)}`));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bykaranteli-mcp",
-  "version": "0.7.2",
+  "version": "0.8.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": {