mcp-server-madeonsol 1.14.0 → 1.15.1

package/README.md

@@ -13,6 +13,8 @@ MCP server for [MadeOnSol](https://madeonsol.com) Solana KOL intelligence API. U
 
 > Real-time Solana trading intelligence: track 1,069 KOL wallets with <3s latency, score 23,000+ Pump.fun deployers, surface deshred deploy signals **~500ms before on-chain confirmation**, detect multi-KOL coordination, and stream every DEX trade across 9+ programs. Free tier: 200 requests/day at [madeonsol.com/pricing](https://madeonsol.com/pricing) — no credit card required.
 
+> **New in 1.15.0** — **Almost-bonded discovery + trending sorts.** New tool `madeonsol_almost_bonded` — pre-bond pump.fun tokens near graduation, ranked by velocity (Δprogress/min): "95% and accelerating" beats "92% stalled". Each token carries `progress_pct`, `velocity_pct_per_min`, `eta_minutes`, `stalled`, `real_sol_reserves`, `market_cap_usd`, `liquidity_usd`, `authorities_revoked`, `deployer_tier`, and `age_minutes`. Params: `min_progress`, `max_progress`, `min_velocity_pct_per_min`, `max_age_minutes`, `deployer_tier`, `authority_revoked`, `min_liq`, `sort` (velocity_desc / progress_desc / eta_asc), `limit`. PRO/ULTRA only. Plus `madeonsol_tokens_list` gains four momentum sorts — `mc_change_5m_desc`, `mc_change_1h_desc`, `volume_1h_desc`, and `trending` (composite recent-volume × positive-momentum rank).
+>
 > **New in 1.14.0** — **Token trade flow.** New tool `madeonsol_token_flow` — a trade-flow aggregate (organic-vs-fake volume) over a `1h`/`24h` window: `unique_wallets` / `unique_buyers` / `unique_sellers`, `buy_count` / `sell_count` / `total_trades`, `buy_sol` / `sell_sol` / `net_sol` (sell − buy; positive = net SOL leaving the pool), and `trades_per_wallet` (wash-trading proxy). PRO/ULTRA only. Deployer alerts (`madeonsol_deployer_alerts`) now carry `deployers.deployer_sol_balance` — the deployer wallet's SOL balance at alert time (null for historical rows).
 >
 > **New in 1.13.0** — **Token OHLCV candles.** New tool `madeonsol_token_candles` — historical price candles (1m/5m/15m/1h/4h/1d) aggregated from the on-chain trade firehose. Each candle has `t/open/high/low/close/volume_usd/trades/market_cap_usd`. PRO returns OHLCV for the last 30 days; ULTRA adds buy/sell volume + count splits, net flow, MEV volume, open/close liquidity, high/low MC, and full history. PRO/ULTRA only.
@@ -63,6 +65,37 @@ Add to `claude_desktop_config.json` or Cursor MCP settings (free tier at https:/
 
 Restart Claude Desktop and ask: *"What are KOLs buying right now?"*
 
+## AI agent quickstart (x402 / pay-per-call)
+
+Building an autonomous agent? Skip the signup. Point a **funded Solana wallet** at the server and every tool call **auto-pays a micropayment** over [x402](https://x402.org) — no API key, no account, no rate-limit dance.
+
+```json
+{
+  "mcpServers": {
+    "madeonsol": {
+      "command": "mcp-server-madeonsol",
+      "env": {
+        "SVM_PRIVATE_KEY": "<base58 solana private key>"
+      }
+    }
+  }
+}
+```
+
+How it works:
+
+- The wallet behind `SVM_PRIVATE_KEY` settles each request as a **USDC micropayment on Solana** (~$0.005–$0.02 per call, settled on-chain). No subscription, no quota.
+- The free **`madeonsol_discovery`** tool needs no auth and returns every endpoint with its exact per-call price — call it first to see what each tool costs.
+- Install the x402 peer deps alongside the server (only required for this mode):
+
+  ```bash
+  npm install -g mcp-server-madeonsol @x402/fetch @x402/svm @x402/core @solana/kit @scure/base
+  ```
+
+> **Data only.** MadeOnSol returns trading *intelligence* — it never trades, signs swaps, or takes custody of funds. The only thing your wallet ever pays for is the per-call data fee.
+
+Prefer a fixed monthly bill, free tier, or no wallet? Use the developer path below.
+
 ## Authentication
 
 Two options (in priority order):
@@ -172,7 +205,8 @@ Scored from 1M+ early-buyer records (wallets seen in the first 20 buyers of Pump
 
 | Tool | Tier | Description |
 |---|---|---|
-| `madeonsol_tokens_list` | PRO+ | Filtered, sortable token directory — MC band, liquidity floor, primary DEX, authority/safety flags, computed 1h volume / MEV-share / MC-change deltas. Default `min_liq=2000` skips phantom-MC dust. |
+| `madeonsol_tokens_list` | PRO+ | Filtered, sortable token directory — MC band, liquidity floor, primary DEX, authority/safety flags, computed 1h volume / MEV-share / MC-change deltas, plus momentum sorts (`mc_change_5m_desc`, `mc_change_1h_desc`, `volume_1h_desc`, `trending`). Default `min_liq=2000` skips phantom-MC dust. |
+| `madeonsol_almost_bonded` | PRO+ | Pre-bond pump.fun tokens near graduation, ranked by velocity (Δprogress/min) — `progress_pct`, `velocity_pct_per_min`, `eta_minutes`, `stalled`, `deployer_tier`, `age_minutes` |
 | `madeonsol_token_cap_table` | PRO+ | First non-deployer early buyers, enriched with PnL/KOL/bot flags. PRO=10, ULTRA=20 |
 | `madeonsol_token_buyer_quality` | All | 0–100 buyer-quality score + full breakdown (5-min cached) |
 | `madeonsol_token_risk` | PRO+ | Transparent 0–100 rug-risk/safety score with `band`, explainable `factors[]`, and raw `inputs` |

package/dist/index.d.ts

@@ -1,2 +1,17 @@
 #!/usr/bin/env node
-export {};
+export type AuthMode = "madeonsol" | "x402" | "none";
+/**
+ * Pure selection of the auth mode from environment. Extracted from initAuth()
+ * so the routing/auth-mode logic is unit-testable without setting up signers or
+ * network. Priority: MADEONSOL_API_KEY (Bearer) > SVM_PRIVATE_KEY (x402) > none.
+ */
+export declare function resolveAuthMode(env?: {
+    MADEONSOL_API_KEY?: string;
+    SVM_PRIVATE_KEY?: string;
+}): AuthMode;
+/**
+ * Pure path rewrite. Tools are authored against /api/x402/ paths. In x402 / none
+ * mode the path is kept as-is; in madeonsol (API key) mode the prefix is
+ * rewritten to /api/v1/. Extracted from query() so it is unit-testable.
+ */
+export declare function rewritePath(path: string, mode: AuthMode): string;

package/dist/index.js

@@ -11,7 +11,29 @@ const PORT = parseInt(process.env.PORT || "3100", 10);
 const MODE = process.env.MCP_TRANSPORT || "stdio"; // "stdio" or "http"
 let authMode = "none";
 let paidFetch = fetch;
-const UA = "mcp-server-madeonsol/1.14.0";
+/**
+ * Pure selection of the auth mode from environment. Extracted from initAuth()
+ * so the routing/auth-mode logic is unit-testable without setting up signers or
+ * network. Priority: MADEONSOL_API_KEY (Bearer) > SVM_PRIVATE_KEY (x402) > none.
+ */
+export function resolveAuthMode(env = process.env) {
+    if (env.MADEONSOL_API_KEY)
+        return "madeonsol";
+    if (env.SVM_PRIVATE_KEY)
+        return "x402";
+    return "none";
+}
+/**
+ * Pure path rewrite. Tools are authored against /api/x402/ paths. In x402 / none
+ * mode the path is kept as-is; in madeonsol (API key) mode the prefix is
+ * rewritten to /api/v1/. Extracted from query() so it is unit-testable.
+ */
+export function rewritePath(path, mode) {
+    return mode === "x402" || mode === "none"
+        ? path
+        : path.replace("/api/x402/", "/api/v1/");
+}
+const UA = "mcp-server-madeonsol/1.15.1";
 function apiKeyHeaders() {
     const h = { "User-Agent": UA };
     if (authMode === "madeonsol") {
@@ -20,12 +42,13 @@ function apiKeyHeaders() {
     return h;
 }
 async function initAuth() {
-    if (MADEONSOL_API_KEY) {
+    const mode = resolveAuthMode({ MADEONSOL_API_KEY, SVM_PRIVATE_KEY: PRIVATE_KEY });
+    if (mode === "madeonsol") {
         authMode = "madeonsol";
         console.error("[madeonsol-mcp] Using MadeOnSol API key (Bearer auth)");
         return;
     }
-    if (PRIVATE_KEY) {
+    if (mode === "x402" && PRIVATE_KEY) {
         try {
             const { wrapFetchWithPayment } = await import("@x402/fetch");
             const { x402Client } = await import("@x402/core/client");
@@ -50,9 +73,7 @@ async function initAuth() {
 }
 async function query(path, params) {
     // API key uses /api/v1/ endpoints; x402 uses /api/x402/
-    const apiPath = authMode === "x402" || authMode === "none"
-        ? path
-        : path.replace("/api/x402/", "/api/v1/");
+    const apiPath = rewritePath(path, authMode);
     const url = new URL(apiPath, BASE_URL);
     if (params) {
         for (const [k, v] of Object.entries(params)) {
@@ -507,7 +528,7 @@ function registerTools(server) {
             min_liq_mc_ratio: z.number().optional().describe("Minimum liquidity-to-MC ratio (0-1). Filters out tokens where liquidity is thin relative to market cap."),
             max_liq_mc_ratio: z.number().optional().describe("Maximum liquidity-to-MC ratio (0-1)."),
             deployer_tier: z.enum(["elite", "good", "moderate", "rising", "cold", "unranked"]).optional().describe("Filter by deployer reputation tier."),
-            sort: z.enum(["mc_desc", "mc_asc", "last_trade_desc", "liquidity_desc", "cumulative_volume_desc"]).optional().describe("Sort axis (default mc_desc)"),
+            sort: z.enum(["mc_desc", "mc_asc", "last_trade_desc", "liquidity_desc", "cumulative_volume_desc", "mc_change_5m_desc", "mc_change_1h_desc", "volume_1h_desc", "trending"]).optional().describe("Sort axis (default mc_desc). Momentum sorts: mc_change_5m_desc, mc_change_1h_desc, volume_1h_desc, trending (composite recent-volume × positive-momentum rank)."),
             limit: z.number().min(1).max(100).optional().describe("Page size (max 100)"),
             offset: z.number().min(0).optional().describe("Pagination offset"),
         }, { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }, async (args) => {
@@ -520,6 +541,26 @@ function registerTools(server) {
             const text = res.ok ? JSON.stringify(await res.json(), null, 2) : `Error ${res.status}: ${await res.text().catch(() => "")}`;
             return { content: [{ type: "text", text }] };
         });
+        server.tool("madeonsol_almost_bonded", "Pre-bond pump.fun tokens approaching graduation, ranked by VELOCITY (Δprogress/min) — '95% and accelerating' beats '92% stalled'. Each token is enriched with its deployer's reputation tier. progress_pct comes from on-chain real_token_reserves depletion; velocity_pct_per_min is null until a 5-minute snapshot exists; eta_minutes is a linear projection from current velocity. Returns tokens[] with mint, symbol, name, progress_pct, velocity_pct_per_min, eta_minutes, stalled, real_sol_reserves, market_cap_usd, liquidity_usd, authorities_revoked, deployer_tier, age_minutes. PRO/ULTRA only.", {
+            min_progress: z.number().min(0).max(100).optional().describe("Lower bound on bonding progress % (default 80)"),
+            max_progress: z.number().min(0).max(100).optional().describe("Upper bound on bonding progress % (default 99.99 — already-bonded excluded)"),
+            min_velocity_pct_per_min: z.number().optional().describe("Minimum Δprogress/min; tokens without a 5m-ago snapshot are dropped when set"),
+            max_age_minutes: z.number().min(1).optional().describe("Max minutes since deploy (post-filter)"),
+            deployer_tier: z.enum(["elite", "good", "moderate", "rising", "cold", "unranked"]).optional().describe("Filter by deployer reputation tier"),
+            authority_revoked: z.boolean().optional().describe("Only tokens whose mint+freeze authorities are revoked"),
+            min_liq: z.number().min(0).optional().describe("Minimum liquidity in USD"),
+            sort: z.enum(["velocity_desc", "progress_desc", "eta_asc"]).optional().describe("Sort axis (default velocity_desc)"),
+            limit: z.number().min(1).max(100).optional().describe("Page size (1-100, default 50)"),
+        }, { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }, async (args) => {
+            const url = new URL(`${BASE_URL}/api/v1/tokens/almost-bonded`);
+            for (const [k, v] of Object.entries(args)) {
+                if (v !== undefined)
+                    url.searchParams.set(k, typeof v === "boolean" ? (v ? "true" : "false") : String(v));
+            }
+            const res = await fetch(url.toString(), { headers: { "Content-Type": "application/json", ...apiKeyHeaders() } });
+            const text = res.ok ? JSON.stringify(await res.json(), null, 2) : `Error ${res.status}: ${await res.text().catch(() => "")}`;
+            return { content: [{ type: "text", text }] };
+        });
         // ── Alpha wallet intelligence ──
         server.tool("madeonsol_alpha_leaderboard", "Top statistically profitable early-buyer wallets, scored from 47,000+ early-buyer records. BASIC=25 (truncated), PRO=100, ULTRA=500 + bot signals.", {
             period: z.enum(["7d", "30d", "all"]).default("30d").describe("Time window"),
@@ -908,7 +949,7 @@ async function main() {
                 res.end(JSON.stringify({
                     name: "madeonsol",
                     description: "Solana KOL trading intelligence and deployer analytics. Real-time data from 1,000+ KOL wallets, 6,700+ Pump.fun deployers, 47,000+ scored alpha wallets, copy-trade rules, and wallet tracker. Supports MadeOnSol API key (msk_) or x402 micropayments.",
-                    version: "1.13.0",
+                    version: "1.15.1",
                     tools: [
                         { name: "madeonsol_kol_feed", description: "Get real-time Solana KOL trades from 1,000+ tracked wallets." },
                         { name: "madeonsol_kol_coordination", description: "Get KOL convergence signals — tokens multiple KOLs are accumulating." },
@@ -930,7 +971,8 @@ async function main() {
                         { name: "madeonsol_test_webhook", description: "Send a test payload to verify a webhook. Pro/Ultra." },
                         { name: "madeonsol_stream_token", description: "Get a 24h WebSocket streaming token. Pro/Ultra." },
                         { name: "madeonsol_me", description: "Inspect your account — tier, quota state, remaining requests, subscription expiry, per-feature usage." },
-                        { name: "madeonsol_tokens_list", description: "Filtered, sortable token directory — MC band, liquidity floor, primary DEX, authority/safety flags, computed 1h volume / MEV-share / MC-change. PRO+." },
+                        { name: "madeonsol_tokens_list", description: "Filtered, sortable token directory — MC band, liquidity floor, primary DEX, authority/safety flags, computed 1h volume / MEV-share / MC-change, plus momentum sorts (mc_change_5m_desc, mc_change_1h_desc, volume_1h_desc, trending). PRO+." },
+                        { name: "madeonsol_almost_bonded", description: "Pre-bond pump.fun tokens near graduation, ranked by velocity (Δprogress/min) — progress_pct, velocity_pct_per_min, eta_minutes, stalled, deployer_tier. PRO+." },
                         { name: "madeonsol_wallet_tracker_watchlist", description: "List your tracked wallets and remaining capacity." },
                         { name: "madeonsol_wallet_tracker_add", description: "Add a wallet to your watchlist." },
                         { name: "madeonsol_wallet_tracker_remove", description: "Remove a wallet from your watchlist." },
@@ -992,7 +1034,7 @@ async function main() {
                         transport = new StreamableHTTPServerTransport({
                             sessionIdGenerator: undefined,
                         });
-                        const server = new McpServer({ name: "madeonsol", version: "1.13.0" });
+                        const server = new McpServer({ name: "madeonsol", version: "1.15.1" });
                         registerTools(server);
                         await server.connect(transport);
                     }
@@ -1036,4 +1078,8 @@ async function main() {
         await server.connect(transport);
     }
 }
-main().catch(console.error);
+// Only auto-run when executed as a program (CLI / spawned process), not when
+// the module is imported by a test for its exported pure helpers.
+if (process.env.MADEONSOL_MCP_NO_AUTORUN !== "1") {
+    main().catch(console.error);
+}

package/glama.json

@@ -2,7 +2,7 @@
   "name": "mcp-server-madeonsol",
   "display_name": "MadeOnSol — Solana memecoin intelligence",
   "description": "Real-time Solana memecoin trading intelligence — track 1,000+ KOL wallets with <3s latency, score 6,700+ Pump.fun deployers, surface multi-KOL coordination signals, run server-side copy-trade rules, and stream every DEX trade across 9+ programs. Backtested first-touch scout signal (S-tier scouts attract ≥3 follow-on KOLs ~50% of the time vs 14% baseline). Free tier 200 requests per day; auth via msk_ API key or x402 micropayments.",
-  "version": "1.7.4",
+  "version": "1.15.1",
   "homepage": "https://madeonsol.com/solana-api",
   "repository": "https://github.com/LamboPoewert/mcp-server-madeonsol",
   "license": "MIT",
@@ -46,7 +46,8 @@
     { "name": "madeonsol_alpha_leaderboard", "description": "Top profitable early-buyer wallets — 47,000+ scored, up to 500 on ULTRA." },
     { "name": "madeonsol_alpha_wallet", "description": "Full alpha profile + bot-signal flags for one wallet." },
     { "name": "madeonsol_alpha_linked", "description": "Behaviorally linked wallets (co-bought 3+ tokens within 2s)." },
-    { "name": "madeonsol_tokens_list", "description": "Filtered token directory — MC band, liquidity, MEV-share, velocity, primary DEX, authority flags." },
+    { "name": "madeonsol_tokens_list", "description": "Filtered token directory — MC band, liquidity, MEV-share, velocity, primary DEX, authority flags, momentum/trending sorts." },
+    { "name": "madeonsol_almost_bonded", "description": "Pre-bond pump.fun tokens near graduation, ranked by velocity (Δprogress/min) — progress, eta, stalled, deployer tier." },
     { "name": "madeonsol_token_get", "description": "Single token detail — MC, holders, velocity, MEV-share, history age." },
     { "name": "madeonsol_token_batch", "description": "Bulk token detail fetch — up to 50 mints per call." },
     { "name": "madeonsol_token_cap_table", "description": "First non-deployer early buyers for a token, enriched with PnL/KOL/bot flags." },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-server-madeonsol",
-  "version": "1.14.0",
+  "version": "1.15.1",
   "mcpName": "io.github.LamboPoewert/madeonsol",
   "description": "MCP server for MadeOnSol Solana KOL intelligence API — use from Claude, Cursor, or any MCP client",
   "type": "module",
@@ -16,6 +16,7 @@
   ],
   "scripts": {
     "build": "tsc",
+    "test": "vitest run",
     "preflight": "bash ../../scripts/preflight-publish.sh",
     "prepublishOnly": "npm run preflight && npm run build"
   },
@@ -61,6 +62,7 @@
   },
   "devDependencies": {
     "@types/node": "^20",
-    "typescript": "^5"
+    "typescript": "^5",
+    "vitest": "^4.1.5"
   }
 }