@dritan/mcp 0.6.1 → 0.8.0

package/README.md

@@ -72,22 +72,25 @@ npm run build && npm start
 - `ths_get_score`
 - `ths_get_score_tokens_get`
 - `ths_get_score_tokens_post`
+- `ths_get_top_wallets`
 - `swap_build`
 - `swap_sign_and_broadcast`
 - `swap_build_sign_and_broadcast`
 
 ## Notes
 
-- Wallets default to `~/.config/dritan-mcp/wallets`.
+- Wallets default to the current working directory (`process.cwd()`).
 - Private keys never leave local files; only public address/signature are returned.
 - `swap_sign_and_broadcast` signs locally, then broadcasts via Dritan.
 - `auth_set_api_key` activates a key for the running MCP process without restart.
+- `auth_set_api_key` and successful `x402_create_api_key` responses include a capability summary so agents can immediately guide users to next actions.
 - Agent onboarding without `DRITAN_API_KEY` should present two options:
-  - Option 1: paid x402 flow (`x402_get_pricing` -> `x402_create_api_key_quote` -> user funds agent wallet -> `wallet_transfer_sol` -> `x402_create_api_key`).
+  - Option 1: paid x402 flow (`wallet_create_local` in current directory -> share wallet + backup file path -> user chooses SOL amount and funds agent wallet -> if no key exists use `x402_create_api_key_quote` -> `wallet_transfer_sol` -> `x402_create_api_key`).
   - Option 2: user gets a free key at `https://dritan.dev`.
 - `x402_create_api_key` auto-activates returned keys for the current MCP session.
 - `token_get_ohlcv_chart` returns a shareable chart URL plus a ready-to-send markdown image snippet.
 - `token_get_ohlcv_chart` supports `chartType: "line-volume" | "candlestick"` (default is `candlestick`).
+- `ths_get_top_wallets` returns a paginated leaderboard of THS-ranked wallets (`page`, `limit`) for smart-wallet discovery workflows.
 - Ticker workflow for chart requests: `token_search` -> extract mint -> `token_get_ohlcv` or `token_get_ohlcv_chart`.
 - If users ask for `$WIF` style symbols, always resolve mint with `token_search` first.
 - If Solana CLI is missing, run `system_check_prereqs` and follow returned install steps.

package/dist/index.js

@@ -1,6 +1,5 @@
 #!/usr/bin/env node
 import { mkdirSync, readFileSync, existsSync } from "node:fs";
-import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -9,7 +8,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextpro
 import { DritanClient, MeteoraThsClient, } from "dritan-sdk";
 import { Connection, Keypair, PublicKey, SystemProgram, Transaction, VersionedTransaction, clusterApiUrl, } from "@solana/web3.js";
 import { z } from "zod";
-const DEFAULT_WALLET_DIR = join(homedir(), ".config", "dritan-mcp", "wallets");
+const DEFAULT_WALLET_DIR = process.cwd();
 const LAMPORTS_PER_SOL = 1_000_000_000;
 function normalizeApiKey(value) {
     const trimmed = value?.trim();
@@ -68,7 +67,10 @@ const server = new Server({
     },
     instructions: [
         "This server supports two API-key onboarding options when DRITAN_API_KEY is missing:",
-        "1) x402 pay-per-use key flow: create wallet, receive SOL, create quote, forward payment, claim key.",
+        "1) x402 pay-per-use key flow:",
+        "   a) Create a local agent wallet with wallet_create_local (saved in current working directory by default).",
+        "   b) Ask user how much SOL they want to allocate and provide both wallet address and backup file path.",
+        "   c) If no active key exists, create quote -> pay from agent wallet -> claim key.",
         "2) Free key flow: user creates a free API key at https://dritan.dev.",
         "After key is obtained, set it with auth_set_api_key (no restart needed), or restart with DRITAN_API_KEY configured.",
         "Suggested setup command:",
@@ -82,10 +84,24 @@ function missingApiKeyError() {
     return new Error([
         "Missing DRITAN_API_KEY in environment.",
         "Option 1 (paid): use x402 tools (x402_get_pricing, x402_create_api_key_quote, x402_create_api_key) and wallet tools.",
+        "Paid flow order: create wallet in current directory -> tell user funding amount + backup file path -> if no key exists then create/claim x402 key.",
         "Option 2 (free): create a free key at https://dritan.dev and set DRITAN_API_KEY.",
         "You can activate a key immediately with auth_set_api_key without restarting MCP.",
     ].join(" "));
 }
+const postAuthCapabilities = [
+    "Token intelligence: token search, price, metadata, risk, first buyers, deployer stats.",
+    "Charts: OHLCV data and shareable line-volume/candlestick chart URLs.",
+    "Wallet analytics: summary, holdings, trade history, performance, and portfolio charts.",
+    "Trader discovery: Meteora THS wallet score lookups plus top-wallet leaderboard.",
+    "Execution: build/sign/broadcast swaps and monitor wallet/DEX streams.",
+];
+function buildPostAuthGuidance() {
+    return {
+        capabilities: postAuthCapabilities,
+        suggestedNextPrompt: "Tell me your goal and I can proceed: token research, smart-wallet discovery, chart generation, or swap execution.",
+    };
+}
 function getDritanClient() {
     const apiKey = getActiveApiKey();
     if (!apiKey) {
@@ -112,6 +128,24 @@ function getThsClient() {
         baseUrl: process.env.METEORA_THS_BASE_URL,
     });
 }
+async function getThsTopWallets(ths, options = {}) {
+    const sdkMethod = ths.getTopWalletsByScore;
+    if (typeof sdkMethod === "function") {
+        return await sdkMethod.call(ths, options);
+    }
+    const baseUrl = ths.baseUrl ?? "https://ths.dritan.dev";
+    const url = new URL("/ths/top-wallets", baseUrl);
+    if (options.page !== undefined)
+        url.searchParams.set("page", String(options.page));
+    if (options.limit !== undefined)
+        url.searchParams.set("limit", String(options.limit));
+    const res = await fetch(url.toString(), { method: "GET" });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`Meteora THS request failed (${res.status}): ${text || res.statusText}`);
+    }
+    return (await res.json());
+}
 async function searchTokens(client, query, options) {
     const sdkSearch = client.searchTokens;
     if (typeof sdkSearch === "function") {
@@ -440,7 +474,12 @@ function createLocalWalletFile(walletPath) {
         throw new Error(`solana-keygen failed (${cmd.status}): ${cmd.stderr || cmd.stdout}`);
     }
     const keypair = loadKeypairFromPath(walletPath);
-    return { walletPath, address: keypair.publicKey.toBase58() };
+    return {
+        walletPath,
+        backupFilePath: walletPath,
+        walletDir: dir,
+        address: keypair.publicKey.toBase58(),
+    };
 }
 function loadKeypairFromPath(walletPath) {
     const bytes = JSON.parse(readFileSync(walletPath, "utf8"));
@@ -558,6 +597,10 @@ const thsScoreSchema = z.object({
 const thsScoreTokensSchema = thsScoreSchema.extend({
     tokenMints: z.array(z.string().min(1)).min(1).max(200),
 });
+const thsTopWalletsSchema = z.object({
+    page: z.number().int().min(1).optional(),
+    limit: z.number().int().min(1).max(100).optional(),
+});
 const swapBuildSchema = z.object({
     walletPath: z.string().min(1).optional(),
     userPublicKey: z.string().min(1).optional(),
@@ -988,6 +1031,17 @@ const tools = [
             },
         },
     },
+    {
+        name: "ths_get_top_wallets",
+        description: "Fetch paginated top wallets ranked by THS score.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                page: { type: "number" },
+                limit: { type: "number" },
+            },
+        },
+    },
     {
         name: "swap_build",
         description: "Build an unsigned swap transaction with Dritan.",
@@ -1061,11 +1115,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                             preview: apiKeyPreview(activeApiKey),
                             hint: apiKeySet
                                 ? "API key is configured."
-                                : "Missing DRITAN_API_KEY. You can either use x402 onboarding tools or get a free key at https://dritan.dev.",
+                                : "Missing DRITAN_API_KEY. Use x402 flow (wallet in current directory, user funds it, then claim key) or get a free key at https://dritan.dev.",
                         },
                     ],
                     nextAction: !apiKeySet
-                        ? "Choose one: (1) x402 paid onboarding flow with wallet tools, or (2) get a free key at https://dritan.dev and set DRITAN_API_KEY."
+                        ? "Choose one: (1) x402 paid onboarding flow: wallet_create_local -> share wallet + backup file path -> user funds -> x402 quote/claim, or (2) get a free key at https://dritan.dev and set DRITAN_API_KEY."
                         : !solanaCli.ok
                             ? "Install Solana CLI using installHint, then retry wallet_create_local."
                             : "Environment ready.",
@@ -1079,9 +1133,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     preview: apiKeyPreview(activeApiKey),
                     controlBaseUrl: getControlBaseUrl(),
                     onboardingOptions: [
-                        "Option 1 (paid x402): create wallet -> receive user SOL -> x402 quote -> transfer -> claim key.",
+                        "Option 1 (paid x402): create wallet in current directory -> share wallet address and backup file path -> user funds wallet -> if no key exists, quote/transfer/claim key.",
                         "Option 2 (free): create key at https://dritan.dev and set it with auth_set_api_key.",
                     ],
+                    ...(activeApiKey ? buildPostAuthGuidance() : {}),
                 });
             }
             case "auth_set_api_key": {
@@ -1092,6 +1147,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     message: "API key activated for this MCP session without restart.",
                     source: runtimeApiKeySource,
                     preview: apiKeyPreview(activated),
+                    ...buildPostAuthGuidance(),
                 });
             }
             case "dritan_health": {
@@ -1101,7 +1157,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 const input = walletCreateSchema.parse(args);
                 const walletPath = toWalletPath(input.name, input.walletDir);
                 const created = createLocalWalletFile(walletPath);
-                return ok(created);
+                return ok({
+                    ...created,
+                    fundingInstruction: "Ask the user how much SOL they want to allocate to this wallet, and tell them this backup file path.",
+                });
             }
             case "wallet_get_address": {
                 const input = walletPathSchema.parse(args);
@@ -1172,7 +1231,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return ok({
                     ...(pricing ?? {}),
                     onboardingOptions: [
-                        "Option 1 (paid x402): create wallet -> receive user SOL -> x402 quote -> forward payment -> claim key.",
+                        "Option 1 (paid x402): create wallet in current directory -> share wallet + backup path -> user funds wallet -> if no key exists, quote/payment/claim.",
                         "Option 2 (free): user gets API key at https://dritan.dev and provides it as DRITAN_API_KEY.",
                     ],
                 });
@@ -1180,12 +1239,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "x402_create_api_key_quote": {
                 const input = x402QuoteSchema.parse(args);
                 const client = getX402Client();
+                const activeApiKey = getActiveApiKey();
                 const quote = await x402CreateQuote(client, input);
                 return ok({
                     ...(quote ?? {}),
+                    apiKeyAlreadyConfigured: !!activeApiKey,
+                    keyPreview: apiKeyPreview(activeApiKey),
                     nextSteps: [
-                        "If user picked paid flow, ensure agent has a local wallet (wallet_create_local + wallet_get_address).",
-                        "User funds the agent wallet.",
+                        "Ensure agent has a local wallet in current directory (wallet_create_local + wallet_get_address) and tell user the backup file path.",
+                        "Ask user how much SOL they want to allocate; user funds the agent wallet.",
+                        "Only proceed if no API key is active; otherwise skip paid key creation.",
                         "Transfer quoted SOL amount to receiver wallet using wallet_transfer_sol.",
                         "Claim key with x402_create_api_key using returned tx signature (MCP auto-activates returned apiKey).",
                     ],
@@ -1206,6 +1269,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         preview: apiKeyPreview(activated),
                         message: "x402-created API key is active for this MCP session (no restart needed).",
                     };
+                    Object.assign(payload, buildPostAuthGuidance());
                 }
                 return ok(payload);
             }
@@ -1433,6 +1497,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     breakdown: input.breakdown,
                 }));
             }
+            case "ths_get_top_wallets": {
+                const input = thsTopWalletsSchema.parse(args);
+                const ths = getThsClient();
+                return ok(await getThsTopWallets(ths, input));
+            }
             case "swap_build": {
                 const input = swapBuildSchema.parse(args);
                 const client = getDritanClient();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dritan/mcp",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "license": "MIT",
   "type": "module",
   "description": "MCP server for Dritan SDK market data and local Solana wallet swap execution",