mcp-server-madeonsol 1.2.1 → 1.3.1

package/README.md

@@ -68,6 +68,7 @@ Add to MCP settings with the same command and env vars.
 |---|---|
 | `madeonsol_kol_feed` | Real-time KOL trade feed (1,000+ wallets) |
 | `madeonsol_kol_coordination` | Multi-KOL convergence signals (v1.1) — peak-density window, exit detection, 0-100 score |
+| `madeonsol_kol_first_touches` | First-KOL-touch events — backtested scout signal. Filter by scout tier, winrate, token age, mint suffix |
 | `madeonsol_kol_leaderboard` | KOL PnL and win rate rankings (180 days of history; periods: today, 7d, 30d, 90d, 180d) |
 | `madeonsol_kol_pairs` | KOL affinity matrix — which KOLs co-trade the same tokens |
 | `madeonsol_kol_hot_tokens` | KOL momentum tokens — accelerating buy interest |
@@ -134,6 +135,23 @@ Real-time push alerts when a KOL cluster co-buys the same token. Fires within ~1
 | `madeonsol_coordination_alerts_update` | Update fields or toggle `is_active` |
 | `madeonsol_coordination_alerts_delete` | Delete permanently |
 
+### KOL Scout Signal — first KOL touches *(new in 1.3)*
+
+Every "first KOL buy on a token mint" event. Filterable by **scout tier** (S/A/B/C from `mv_kol_scout_score`), KOL winrate, token age, mint suffix.
+
+**Backtest:** S-tier scouts attract ≥3 follow-on KOLs within 4h ~50% of the time vs ~14% baseline (38d / 491k buys / 72,549 events). Public leaderboard at [madeonsol.com/kol/scouts](https://madeonsol.com/kol/scouts).
+
+| Tool | Description |
+|---|---|
+| `madeonsol_kol_first_touches` | Recent first-KOL-touch events. Filters: `min_scout_tier`, `min_kol_winrate_7d`, `token_age_max_min`, `mint_suffix`, `preset`, etc. |
+| `madeonsol_first_touch_subscriptions_list` | List your first-touch webhook subscriptions — ULTRA |
+| `madeonsol_first_touch_subscriptions_create` | Create a webhook rule (HMAC-signed). Returns `webhook_secret` once — store it. Up to 10/user — ULTRA |
+| `madeonsol_first_touch_subscriptions_get` | Get one subscription — ULTRA |
+| `madeonsol_first_touch_subscriptions_update` | Update fields or toggle `is_active` — ULTRA |
+| `madeonsol_first_touch_subscriptions_delete` | Delete permanently — ULTRA |
+
+> **Don't poll — push.** Median lead time before the second KOL is 12 seconds. WebSocket channel: `kol:first_touches` (PRO+).
+
 ### Streaming & Webhooks
 
 | Tool | Description |

package/dist/index.js

@@ -537,6 +537,75 @@ function registerTools(server) {
         server.tool("madeonsol_coordination_alerts_delete", "Delete a coordination alert rule permanently.", { id: z.string().describe("Rule UUID") }, { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true }, async ({ id }) => ({
             content: [{ type: "text", text: await restQuery("DELETE", `/kol/coordination/alerts/${encodeURIComponent(id)}`) }],
         }));
+        // ── First-touch signal (read tool + ULTRA webhook subscriptions CRUD) ──
+        server.tool("madeonsol_kol_first_touches", "Recent first-KOL-touch events — every time a tracked KOL was the first to buy a token mint. Filterable by scout tier (S/A/B/C from mv_kol_scout_score), KOL winrate, token age, etc. Backtest: top scouts attract ≥3 follow-on KOLs within 4h ~50% of the time vs ~14% baseline. Median lead time before second KOL is 12s — for trading this signal, use the WebSocket channel rather than polling.", {
+            limit: z.number().min(1).max(100).optional().describe("Number of events to return (1-100, default 50)"),
+            since: z.string().optional().describe("ISO timestamp — events strictly newer than this. Polling cursor."),
+            before: z.string().optional().describe("ISO timestamp — events strictly older than this. Pagination cursor."),
+            kol: z.string().optional().describe("Filter to a single KOL wallet address (base58)"),
+            min_kol_winrate_7d: z.number().min(0).max(100).optional().describe("Minimum 7d winrate of the first-touch KOL (0-100)"),
+            min_scout_tier: z.enum(["S", "A", "B", "C"]).optional().describe("Restrict to first-touch KOLs of this scout tier or better. Requires n_first_touches_30d >= 30."),
+            min_n_touches: z.number().min(1).optional().describe("Lower the minimum sample size for scout scoring (default 30)"),
+            strategy: z.enum(["scalper", "day_trader", "swing_trader", "hodler", "mixed"]).optional().describe("Filter by first-touch KOL's auto-tagged strategy"),
+            token_age_max_min: z.number().min(1).optional().describe("Only events on tokens younger than N minutes (uses token_first_seen)"),
+            min_first_buy_sol: z.number().min(0).optional().describe("Minimum size of the first KOL buy in SOL"),
+            mint_suffix: z.string().optional().describe("Suffix-filter the token mint (e.g. 'pump', 'bonk')"),
+            preset: z.enum(["scout", "fresh_launch"]).optional().describe("Shortcut filter: 'scout' = min_scout_tier=B + min_n_touches=30 + token_age_max_min=60. 'fresh_launch' = token_age_max_min=15."),
+            include: z.string().optional().describe("Comma-separated includes — currently 'followers_4h' (computed for events >=4h old)"),
+        }, { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }, async (args) => {
+            const params = {};
+            for (const [k, v] of Object.entries(args))
+                if (v !== undefined)
+                    params[k] = v;
+            return { content: [{ type: "text", text: await restQuery("GET", `/kol/first-touches?${new URLSearchParams(params).toString()}`) }] };
+        });
+        server.tool("madeonsol_first_touch_subscriptions_list", "List your first-touch webhook subscriptions. ULTRA only.", {}, { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }, async () => ({
+            content: [{ type: "text", text: await restQuery("GET", "/kol/first-touches/subscriptions") }],
+        }));
+        server.tool("madeonsol_first_touch_subscriptions_create", "Create a first-touch webhook subscription. ULTRA only — up to 10 active. Filters: kol (wallet), mint_suffix, min_first_buy_sol, min_scout_tier (S/A/B/C), min_n_touches. Returns webhook_secret ONCE — store it.", {
+            name: z.string().optional().describe("Optional label"),
+            filters: z.object({
+                kol: z.string().optional(),
+                mint_suffix: z.string().optional(),
+                min_first_buy_sol: z.number().min(0).optional(),
+                min_scout_tier: z.enum(["S", "A", "B", "C"]).optional(),
+                min_n_touches: z.number().min(1).optional(),
+            }).optional(),
+            delivery_mode: z.enum(["websocket", "webhook", "both"]).optional().describe("Default 'webhook'"),
+            webhook_url: z.string().url().optional().describe("Required when delivery_mode includes 'webhook'"),
+        }, { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }, async (args) => {
+            const body = {};
+            for (const [k, v] of Object.entries(args))
+                if (v !== undefined)
+                    body[k] = v;
+            return { content: [{ type: "text", text: await restQuery("POST", "/kol/first-touches/subscriptions", body) }] };
+        });
+        server.tool("madeonsol_first_touch_subscriptions_get", "Get one first-touch subscription by id. ULTRA only.", { id: z.string().describe("Subscription UUID") }, { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }, async ({ id }) => ({
+            content: [{ type: "text", text: await restQuery("GET", `/kol/first-touches/subscriptions/${encodeURIComponent(id)}`) }],
+        }));
+        server.tool("madeonsol_first_touch_subscriptions_update", "Update fields on a first-touch subscription, including is_active toggle. ULTRA only.", {
+            id: z.string().describe("Subscription UUID"),
+            name: z.string().nullable().optional(),
+            filters: z.object({
+                kol: z.string().optional(),
+                mint_suffix: z.string().optional(),
+                min_first_buy_sol: z.number().min(0).optional(),
+                min_scout_tier: z.enum(["S", "A", "B", "C"]).optional(),
+                min_n_touches: z.number().min(1).optional(),
+            }).optional(),
+            delivery_mode: z.enum(["websocket", "webhook", "both"]).optional(),
+            webhook_url: z.string().url().nullable().optional(),
+            is_active: z.boolean().optional(),
+        }, { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }, async ({ id, ...patch }) => {
+            const body = {};
+            for (const [k, v] of Object.entries(patch))
+                if (v !== undefined)
+                    body[k] = v;
+            return { content: [{ type: "text", text: await restQuery("PATCH", `/kol/first-touches/subscriptions/${encodeURIComponent(id)}`, body) }] };
+        });
+        server.tool("madeonsol_first_touch_subscriptions_delete", "Delete a first-touch subscription permanently. ULTRA only.", { id: z.string().describe("Subscription UUID") }, { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true }, async ({ id }) => ({
+            content: [{ type: "text", text: await restQuery("DELETE", `/kol/first-touches/subscriptions/${encodeURIComponent(id)}`) }],
+        }));
         console.error("[madeonsol-mcp] Webhook & streaming tools enabled");
     }
     else {
@@ -581,7 +650,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.1.2",
+                    version: "1.3.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." },
@@ -621,6 +690,12 @@ async function main() {
                         { name: "madeonsol_copytrade_update", description: "Update a copy-trade rule. PRO/ULTRA." },
                         { name: "madeonsol_copytrade_delete", description: "Delete a copy-trade rule. PRO/ULTRA." },
                         { name: "madeonsol_copytrade_signals", description: "Recent fired copy-trade signals (up to 7 days). PRO/ULTRA." },
+                        { name: "madeonsol_kol_first_touches", description: "Recent first-KOL-touch events on tokens — backtested scout signal. Filterable by scout tier S/A/B/C, KOL winrate, token age, mint suffix." },
+                        { name: "madeonsol_first_touch_subscriptions_list", description: "List your first-touch webhook subscriptions. ULTRA only." },
+                        { name: "madeonsol_first_touch_subscriptions_create", description: "Create a first-touch webhook subscription with HMAC signing. ULTRA only." },
+                        { name: "madeonsol_first_touch_subscriptions_get", description: "Get one first-touch subscription. ULTRA only." },
+                        { name: "madeonsol_first_touch_subscriptions_update", description: "Update a first-touch subscription. ULTRA only." },
+                        { name: "madeonsol_first_touch_subscriptions_delete", description: "Delete a first-touch subscription. ULTRA only." },
                         { name: "madeonsol_coordination_alerts_list", description: "List your KOL coordination alert rules. PRO/ULTRA." },
                         { name: "madeonsol_coordination_alerts_create", description: "Create a coordination alert rule (push via WS + webhook, <1s latency). PRO/ULTRA." },
                         { name: "madeonsol_coordination_alerts_get", description: "Get one coordination alert rule. PRO/ULTRA." },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-server-madeonsol",
-  "version": "1.2.1",
+  "version": "1.3.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",