bykaranteli-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ByKaranteli (bykaranteli.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# bykaranteli-mcp
+
+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).
+
+## Quick start
+
+### Claude Code
+
+```bash
+claude mcp add bykaranteli -- npx -y bykaranteli-mcp
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "bykaranteli": {
+      "command": "npx",
+      "args": ["-y", "bykaranteli-mcp"]
+    }
+  }
+}
+```
+
+### Cursor / other MCP clients
+
+Any stdio MCP client works: command `npx`, args `["-y", "bykaranteli-mcp"]`.
+
+Requires Node.js 18 or newer.
+
+## Tools
+
+| Tool | What it answers |
+|---|---|
+| `get_market_indices` | "What is the Fear & Greed index today?", "What is BTC dominance right now?" |
+| `get_funding_heatmap` | "What are funding rates right now?", "What is SOL's funding?" |
+| `get_funding_arbitrage` | "Any funding arb opportunities?", "Best venue to long/short BTC for carry?" |
+| `get_pressure_scores` | "Which coins are over-leveraged / crowded right now?" |
+| `get_top_movers` | "Biggest OI spikes today?", "Most extreme funding right now?" |
+| `get_recent_signals` | "How did the signals do in the last 24h?" |
+| `get_symbol_performance` | "Win rate on ETHUSDT over 90 days?" |
+| `get_strategy_leaderboard` | "Which strategies are performing best?" |
+
+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`.
+
+## Configuration
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `BYKARANTELI_BASE_URL` | `https://bykaranteli.com` | Override the API host (testing only) |
+
+## Data notes
+
+- Signal performance is a **live-only** track record: real published signals with SHA-256 receipts, evaluated net of fees, slippage and funding. Never backtests. Verify any signal at [bykaranteli.com/verify](https://bykaranteli.com/verify).
+- Funding, OI and pressure data refresh every 15 to 30 minutes; indices every 30 minutes.
+- Nothing here is financial advice. See [bykaranteli.com/risk-guide](https://bykaranteli.com/risk-guide).
+
+## Development
+
+```bash
+npm install
+npm run build
+node dist/index.js   # speaks MCP over stdio
+```
+
+## License
+
+MIT. Attribution appreciated: "ByKaranteli (bykaranteli.com)".

package/dist/index.js

@@ -0,0 +1,297 @@
+#!/usr/bin/env node
+/**
+ * bykaranteli-mcp · MCP server for live crypto derivatives data
+ *
+ * Wraps the free, no-auth public JSON API at https://bykaranteli.com
+ * (docs: https://bykaranteli.com/developers). All data is Binance USDT-M
+ * perpetuals unless a tool says otherwise. Every response carries a
+ * generated-at timestamp; quote it when citing values.
+ */
+import { createRequire } from "node:module";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+// Single source of truth for the version: package.json ships in the tarball
+// and sits one level above both src/ and dist/.
+const { version: VERSION } = createRequire(import.meta.url)("../package.json");
+const BASE_URL = (process.env.BYKARANTELI_BASE_URL ?? "https://bykaranteli.com").replace(/\/+$/, "");
+const USER_AGENT = `bykaranteli-mcp/${VERSION} (+https://github.com/bykarantelicom/bykaranteli-mcp)`;
+const TIMEOUT_MS = 15_000;
+// Read-only GET tools over an open-world public API, all of them.
+const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
+/** Invalid tool input (not a network problem): no retry hint in the error. */
+class InputError extends Error {
+}
+async function fetchJson(path) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error(`${path} timed out after ${TIMEOUT_MS / 1000}s`)), TIMEOUT_MS);
+    try {
+        const res = await fetch(`${BASE_URL}${path}`, {
+            signal: controller.signal,
+            headers: { accept: "application/json", "user-agent": USER_AGENT },
+        });
+        if (!res.ok) {
+            throw new Error(`${path} returned HTTP ${res.status}`);
+        }
+        return await res.json();
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+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 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.`;
+    return {
+        content: [{ type: "text", text }],
+        isError: true,
+    };
+}
+const SYMBOL_RE = /^[A-Z0-9]{5,20}$/;
+function normalizeSymbol(raw) {
+    // Accept the spellings models actually produce: "BTC/USDT", "btc-usdt",
+    // "BTC USDT", bare "BTC". Strip separators, then expand to the USDT perp.
+    const s = raw.trim().toUpperCase().replace(/[\s/_-]+/g, "");
+    const expanded = s.endsWith("USDT") ? s : `${s}USDT`;
+    if (!SYMBOL_RE.test(expanded)) {
+        throw new InputError(`"${raw}" is not a valid symbol. Use a Binance USDT-M perp symbol like BTCUSDT or a coin name like BTC.`);
+    }
+    return expanded;
+}
+const server = new McpServer({
+    name: "bykaranteli",
+    version: VERSION,
+});
+server.registerTool("get_market_indices", {
+    title: "Crypto market indices (Fear & Greed, BTC dominance, euphoria)",
+    description: "Call this when the user asks about overall crypto market sentiment or macro state: the Fear & Greed index (today and yesterday), Bitcoin dominance percentage, total market cap, or the Retail Euphoria composite. Live values refreshed about every 30 minutes.",
+    inputSchema: {},
+    annotations: READ_ONLY,
+}, async () => {
+    try {
+        const d = (await fetchJson("/api/public/indices"));
+        // Trim heavy internals (weights/contributions) but keep the readable parts.
+        const euphoria = d.euphoria;
+        return ok({
+            generatedAt: d.generatedAt,
+            fearGreed: d.fearGreed,
+            global: d.global,
+            stablecoins: d.stablecoins,
+            euphoria: euphoria
+                ? {
+                    score: euphoria.score,
+                    regime: euphoria.regime,
+                    regimeLabel: euphoria.regimeLabel,
+                    explainer: euphoria.explainer,
+                }
+                : undefined,
+            source: `${BASE_URL}/indices`,
+        });
+    }
+    catch (err) {
+        return fail(err);
+    }
+});
+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.",
+    inputSchema: {
+        symbol: z
+            .string()
+            .optional()
+            .describe("Optional. Filter to one symbol, e.g. BTCUSDT or just BTC. Omit to get all 30 rows."),
+    },
+    annotations: READ_ONLY,
+}, async ({ symbol }) => {
+    try {
+        const d = (await fetchJson("/api/public/heatmap"));
+        if (symbol) {
+            const want = normalizeSymbol(symbol);
+            const row = d.rows.find((r) => r.symbol === want);
+            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(", ")}`,
+                });
+            }
+            return ok({ generatedAt: d.generatedAt, row, source: `${BASE_URL}/heatmap` });
+        }
+        return ok({ ...d, source: `${BASE_URL}/heatmap` });
+    }
+    catch (err) {
+        return fail(err);
+    }
+});
+server.registerTool("get_funding_arbitrage", {
+    title: "Cross-exchange funding arbitrage opportunities",
+    description: "Call this when the user asks about funding arbitrage, funding rate differences between exchanges, or delta-neutral carry trades. Compares funding across Binance, OKX, Bybit, Gate, HTX and BingX for 12 major perps and returns the best long/short venue per symbol with gross and net annualized APR (net of taker fees and weekly rebalance cost).",
+    inputSchema: {},
+    annotations: READ_ONLY,
+}, async () => {
+    try {
+        const d = (await fetchJson("/api/public/funding-arb"));
+        return ok({ ...d, source: `${BASE_URL}/funding-arb` });
+    }
+    catch (err) {
+        return fail(err);
+    }
+});
+server.registerTool("get_pressure_scores", {
+    title: "Derivatives pressure scores (funding + OI + basis composite)",
+    description: "Call this when the user asks which coins are crowded or over-leveraged, or asks for the pressure/derivatives-stress score of specific coins. For a quick top-10 ranking of the highest-stress coins right now, use get_top_movers instead. Each symbol gets a 0-100 composite score built from funding rate, 1h/4h/24h open interest deltas and basis, with a LONG/SHORT/NEUTRAL direction and a plain-language regime label.",
+    inputSchema: {
+        symbol: z
+            .string()
+            .optional()
+            .describe("Optional. Return only this symbol, e.g. BTCUSDT or BTC."),
+        limit: z.coerce
+            .number()
+            .int()
+            .min(1)
+            .max(50)
+            .optional()
+            .describe("Optional. Max rows to return when no symbol filter is set (default 20, sorted by score)."),
+    },
+    annotations: READ_ONLY,
+}, async ({ symbol, limit }) => {
+    try {
+        const d = (await fetchJson("/api/public/pressure"));
+        const slim = (it) => ({
+            symbol: it.symbol,
+            score: it.score,
+            direction: it.direction,
+            regimeLabel: it.regimeLabel,
+            components: it.components,
+            explainer: it.explainer,
+        });
+        if (symbol) {
+            const want = normalizeSymbol(symbol);
+            const item = d.items.find((i) => i.symbol === want);
+            if (!item) {
+                return ok({
+                    generatedAt: d.generatedAt,
+                    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,
+            items: d.items.slice(0, limit ?? 20).map(slim),
+            totalTracked: d.items.length,
+            source: `${BASE_URL}/pressure`,
+        });
+    }
+    catch (err) {
+        return fail(err);
+    }
+});
+server.registerTool("get_top_movers", {
+    title: "Top movers: OI spikes, extreme funding, widest basis, highest stress",
+    description: "Call this when the user asks what is moving in crypto derivatives right now, which coins have the biggest open interest changes, the most extreme funding, the widest basis, or the highest derivatives stress. Returns four top-10 lists in one call.",
+    inputSchema: {},
+    annotations: READ_ONLY,
+}, async () => {
+    try {
+        const d = (await fetchJson("/api/public/top-movers"));
+        return ok({ ...d, source: `${BASE_URL}/top-movers` });
+    }
+    catch (err) {
+        return fail(err);
+    }
+});
+server.registerTool("get_recent_signals", {
+    title: "Recent closed trading signals with verified outcomes",
+    description: "Call this when the user asks how the ByKaranteli signal engine is doing today, or wants recent closed LONG/SHORT signals with real outcomes (TP1, SL or TIMEOUT) and net basis-point results. Includes a 24h summary (wins, losses, net bps). Every signal is published with a SHA-256 receipt and results are net of fees, slippage and funding; live signals only, never backtests.",
+    inputSchema: {},
+    annotations: READ_ONLY,
+}, async () => {
+    try {
+        const d = (await fetchJson("/api/public/recent"));
+        return ok({ ...d, source: `${BASE_URL}/signals` });
+    }
+    catch (err) {
+        return fail(err);
+    }
+});
+server.registerTool("get_symbol_performance", {
+    title: "Per-symbol signal performance and recent trades",
+    description: "Call this when the user asks how signals performed on a specific coin (win rate, profit factor, net PnL, best/worst trade) or wants that coin's recent closed signals. Data is the live verified track record for one Binance USDT-M perp over a 30, 90 or 180 day window.",
+    inputSchema: {
+        symbol: z.string().describe("The symbol, e.g. BTCUSDT, or a coin name like BTC."),
+        window_days: z
+            .preprocess((v) => (typeof v === "string" && v.trim() !== "" && Number.isFinite(Number(v)) ? Number(v) : v), z.union([z.literal(30), z.literal(90), z.literal(180)]))
+            .optional()
+            .describe("Optional lookback window in days (30, 90 or 180). Default 90."),
+    },
+    annotations: READ_ONLY,
+}, async ({ symbol, window_days }) => {
+    try {
+        const want = normalizeSymbol(symbol);
+        const w = window_days ?? 90;
+        let d;
+        try {
+            d = (await fetchJson(`/api/v1/public/symbols/${want}?window=${w}`));
+        }
+        catch (err) {
+            // The API 404s when the symbol has no closed signals in the chosen
+            // window (data-dependent, not an invalid request). Say so plainly.
+            if (err instanceof Error && err.message.includes("HTTP 404")) {
+                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}.`,
+                });
+            }
+            throw err;
+        }
+        // daily_points can be long; the stats + recent signals carry the answer.
+        const daily = d.daily_points;
+        return ok({
+            ...d,
+            daily_points: Array.isArray(daily) ? daily.slice(-30) : daily,
+            source: `${BASE_URL}/symbols/${want}`,
+        });
+    }
+    catch (err) {
+        return fail(err);
+    }
+});
+server.registerTool("get_strategy_leaderboard", {
+    title: "Strategy leaderboard with verified live results",
+    description: "Call this when the user asks which trading strategies are performing best, or wants win rate, profit factor, drawdown and Sharpe per strategy. Rankings are computed from live closed signals only (no backtests), net of fees.",
+    inputSchema: {},
+    annotations: READ_ONLY,
+}, async () => {
+    try {
+        const d = (await fetchJson("/api/v1/public/leaderboard"));
+        return ok({ ...d, source: `${BASE_URL}/leaderboard` });
+    }
+    catch (err) {
+        return fail(err);
+    }
+});
+async function main() {
+    // If the host dies while a response is in flight, exit quietly instead of
+    // crashing with an unhandled EPIPE from the stdout pipe. Non-EPIPE stream
+    // errors would be swallowed once a listener exists, so log and exit nonzero.
+    process.stdout.on("error", (err) => {
+        if (err.code === "EPIPE")
+            process.exit(0);
+        console.error("bykaranteli-mcp stdout error:", err);
+        process.exit(1);
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stdout is the JSON-RPC channel; log to stderr only.
+    console.error(`bykaranteli-mcp ready (base: ${BASE_URL})`);
+}
+main().catch((err) => {
+    console.error("bykaranteli-mcp fatal:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "bykaranteli-mcp",
+  "version": "0.1.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",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc && node -e \"require('fs').chmodSync('dist/index.js', 0o755)\"",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js",
+    "prepare": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "crypto",
+    "funding-rate",
+    "open-interest",
+    "liquidation",
+    "fear-and-greed",
+    "btc-dominance",
+    "binance",
+    "derivatives",
+    "trading",
+    "claude"
+  ],
+  "author": "ByKaranteli (https://bykaranteli.com)",
+  "license": "MIT",
+  "homepage": "https://bykaranteli.com/developers",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bykarantelicom/bykaranteli-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bykarantelicom/bykaranteli-mcp/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.5.0"
+  }
+}