@dritan/mcp 0.8.0 → 0.10.0

package/.env.example

@@ -1,4 +1,5 @@
 DRITAN_API_KEY=
+DRITAN_MCP_AUTH_FILE=
 DRITAN_BASE_URL=https://us-east.dritan.dev
 DRITAN_CONTROL_BASE_URL=https://api.dritan.dev
 DRITAN_WS_BASE_URL=wss://us-east.dritan.dev

package/README.md

@@ -41,6 +41,7 @@ npm run build && npm start
 - `system_check_prereqs`
 - `auth_status`
 - `auth_set_api_key`
+- `auth_clear_api_key`
 - `wallet_create_local`
 - `wallet_get_address`
 - `wallet_get_balance`
@@ -82,12 +83,13 @@ npm run build && npm start
 - 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` activates a key for the running MCP process without restart and persists it to a local auth store.
 - `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 (`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.
+- Agent onboarding without an active API key should use x402-first 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`).
+- Free key at `https://dritan.dev` is fallback only if the user declines funding or x402 cannot proceed.
+- `x402_create_api_key` auto-activates returned keys and persists them locally for restart recovery.
+- Default auth store path is `.dritan-mcp/auth.json` under current working directory; override with `DRITAN_MCP_AUTH_FILE`.
+- Use `auth_clear_api_key` to remove in-memory + persisted key state (and optionally clear process env key).
 - `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.

package/dist/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { mkdirSync, readFileSync, existsSync } from "node:fs";
+import { mkdirSync, readFileSync, existsSync, writeFileSync, rmSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -9,6 +9,7 @@ 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 = process.cwd();
+const DEFAULT_API_KEY_STORE_PATH = resolve(process.cwd(), ".dritan-mcp", "auth.json");
 const LAMPORTS_PER_SOL = 1_000_000_000;
 function normalizeApiKey(value) {
     const trimmed = value?.trim();
@@ -21,8 +22,57 @@ function apiKeyPreview(apiKey) {
         return `${apiKey.slice(0, 4)}...`;
     return `${apiKey.slice(0, 8)}...${apiKey.slice(-4)}`;
 }
-let runtimeApiKey = normalizeApiKey(process.env.DRITAN_API_KEY);
-let runtimeApiKeySource = runtimeApiKey ? "env" : "none";
+function getApiKeyStorePath() {
+    const configured = process.env.DRITAN_MCP_AUTH_FILE?.trim();
+    return configured ? resolve(configured) : DEFAULT_API_KEY_STORE_PATH;
+}
+const API_KEY_STORE_PATH = getApiKeyStorePath();
+function loadPersistedApiKey() {
+    if (!existsSync(API_KEY_STORE_PATH))
+        return null;
+    try {
+        const raw = readFileSync(API_KEY_STORE_PATH, "utf8");
+        const parsed = JSON.parse(raw);
+        return normalizeApiKey(parsed.apiKey);
+    }
+    catch (error) {
+        console.warn(`[dritan-mcp] Failed to read persisted API key from ${API_KEY_STORE_PATH}: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}
+function persistApiKey(apiKey, source) {
+    const payload = {
+        apiKey,
+        source,
+        updatedAt: new Date().toISOString(),
+    };
+    try {
+        mkdirSync(dirname(API_KEY_STORE_PATH), { recursive: true, mode: 0o700 });
+        writeFileSync(API_KEY_STORE_PATH, JSON.stringify(payload, null, 2), { encoding: "utf8", mode: 0o600 });
+    }
+    catch (error) {
+        console.warn(`[dritan-mcp] Failed to persist API key to ${API_KEY_STORE_PATH}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function clearPersistedApiKey() {
+    if (!existsSync(API_KEY_STORE_PATH))
+        return false;
+    try {
+        rmSync(API_KEY_STORE_PATH, { force: true });
+        return true;
+    }
+    catch (error) {
+        console.warn(`[dritan-mcp] Failed to remove persisted API key file ${API_KEY_STORE_PATH}: ${error instanceof Error ? error.message : String(error)}`);
+        return false;
+    }
+}
+const persistedStartupKey = loadPersistedApiKey();
+const envStartupKey = normalizeApiKey(process.env.DRITAN_API_KEY);
+let runtimeApiKey = persistedStartupKey ?? envStartupKey;
+let runtimeApiKeySource = persistedStartupKey ? "persisted" : envStartupKey ? "env" : "none";
+if (runtimeApiKey) {
+    process.env.DRITAN_API_KEY = runtimeApiKey;
+}
 function setRuntimeApiKey(apiKey, source) {
     const normalized = normalizeApiKey(apiKey);
     if (!normalized) {
@@ -30,12 +80,20 @@ function setRuntimeApiKey(apiKey, source) {
     }
     runtimeApiKey = normalized;
     runtimeApiKeySource = source;
+    persistApiKey(normalized, source);
     process.env.DRITAN_API_KEY = normalized;
     return normalized;
 }
 function getActiveApiKey() {
     if (runtimeApiKey)
         return runtimeApiKey;
+    const fromPersisted = loadPersistedApiKey();
+    if (fromPersisted) {
+        runtimeApiKey = fromPersisted;
+        runtimeApiKeySource = "persisted";
+        process.env.DRITAN_API_KEY = fromPersisted;
+        return fromPersisted;
+    }
     const fromEnv = normalizeApiKey(process.env.DRITAN_API_KEY);
     if (fromEnv) {
         runtimeApiKey = fromEnv;
@@ -66,13 +124,14 @@ const server = new Server({
         tools: {},
     },
     instructions: [
-        "This server supports two API-key onboarding options when DRITAN_API_KEY is missing:",
-        "1) x402 pay-per-use key flow:",
+        "API-key onboarding policy when DRITAN_API_KEY is missing:",
+        "Default path is x402-first. Do not ask user for an API key first.",
+        "1) x402 pay-per-use key flow (default):",
         "   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.",
+        "2) Fallback only: if user explicitly declines funding or x402 cannot proceed, then offer free key flow at https://dritan.dev.",
+        `After key is obtained, set it with auth_set_api_key (no restart needed); MCP persists it at ${API_KEY_STORE_PATH} for restart recovery.`,
         "Suggested setup command:",
         "  claude mcp add dritan-mcp -e DRITAN_API_KEY=<your-key> -- npx @dritan/mcp@latest",
     ].join("\n"),
@@ -83,10 +142,11 @@ function getControlBaseUrl() {
 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.",
+        `No active key found in persisted auth store (${API_KEY_STORE_PATH}).`,
+        "Onboarding is x402-first by default: use wallet and x402 tools before asking user for an API key.",
         "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.",
+        "Fallback only if user declines funding or x402 is not possible: user can 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; key is persisted locally for restart recovery.",
     ].join(" "));
 }
 const postAuthCapabilities = [
@@ -503,6 +563,9 @@ const walletCreateSchema = z.object({
 const authSetApiKeySchema = z.object({
     apiKey: z.string().min(8),
 });
+const authClearApiKeySchema = z.object({
+    clearEnv: z.boolean().optional(),
+});
 const walletPathSchema = z.object({
     walletPath: z.string().min(1),
 });
@@ -636,7 +699,7 @@ const tools = [
     },
     {
         name: "auth_set_api_key",
-        description: "Set the active Dritan API key for this running MCP process without restart (runtime session scope).",
+        description: "Set the active Dritan API key for this running MCP process and persist it locally for restart recovery.",
         inputSchema: {
             type: "object",
             required: ["apiKey"],
@@ -645,6 +708,16 @@ const tools = [
             },
         },
     },
+    {
+        name: "auth_clear_api_key",
+        description: "Clear the active in-memory API key and delete the persisted auth file. Optionally clear DRITAN_API_KEY in this process env.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                clearEnv: { type: "boolean", description: "Also remove DRITAN_API_KEY from this process environment." },
+            },
+        },
+    },
     {
         name: "wallet_create_local",
         description: "Create a local Solana wallet using solana-keygen and return path + public address.",
@@ -1103,9 +1176,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 const solanaCli = checkSolanaCli();
                 const activeApiKey = getActiveApiKey();
                 const apiKeySet = !!activeApiKey;
+                const persistedApiKeyPresent = existsSync(API_KEY_STORE_PATH);
                 return ok({
                     ready: solanaCli.ok && apiKeySet,
                     readyForX402Onboarding: solanaCli.ok,
+                    apiKeyStorePath: API_KEY_STORE_PATH,
+                    persistedApiKeyPresent,
                     checks: [
                         solanaCli,
                         {
@@ -1115,11 +1191,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                             preview: apiKeyPreview(activeApiKey),
                             hint: apiKeySet
                                 ? "API key is configured."
-                                : "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.",
+                                : "Missing active API key. Start x402 flow first (wallet_create_local -> fund wallet -> quote/claim). Use free key only as fallback.",
                         },
                     ],
                     nextAction: !apiKeySet
-                        ? "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."
+                        ? "Run x402-first onboarding now: wallet_create_local -> share wallet + backup file path -> ask funding amount -> x402_create_api_key_quote -> wallet_transfer_sol -> x402_create_api_key. Offer free key only if user declines or x402 cannot proceed."
                         : !solanaCli.ok
                             ? "Install Solana CLI using installHint, then retry wallet_create_local."
                             : "Environment ready.",
@@ -1132,9 +1208,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     source: runtimeApiKeySource,
                     preview: apiKeyPreview(activeApiKey),
                     controlBaseUrl: getControlBaseUrl(),
+                    apiKeyStorePath: API_KEY_STORE_PATH,
+                    persistedApiKeyPresent: existsSync(API_KEY_STORE_PATH),
                     onboardingOptions: [
-                        "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.",
+                        "Default (x402-first): create wallet in current directory -> share wallet + backup file path -> user funds wallet -> if no key exists, quote/transfer/claim key.",
+                        "Fallback only: if user declines funding or x402 cannot proceed, user can create key at https://dritan.dev and set it with auth_set_api_key.",
                     ],
                     ...(activeApiKey ? buildPostAuthGuidance() : {}),
                 });
@@ -1144,12 +1222,31 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 const activated = setRuntimeApiKey(input.apiKey, "runtime");
                 return ok({
                     ok: true,
-                    message: "API key activated for this MCP session without restart.",
+                    message: "API key activated and persisted for this MCP session without restart.",
                     source: runtimeApiKeySource,
                     preview: apiKeyPreview(activated),
+                    apiKeyStorePath: API_KEY_STORE_PATH,
                     ...buildPostAuthGuidance(),
                 });
             }
+            case "auth_clear_api_key": {
+                const input = authClearApiKeySchema.parse(args);
+                runtimeApiKey = null;
+                runtimeApiKeySource = "none";
+                const persistedApiKeyRemoved = clearPersistedApiKey();
+                const envCleared = !!input.clearEnv;
+                if (envCleared) {
+                    delete process.env.DRITAN_API_KEY;
+                }
+                return ok({
+                    ok: true,
+                    source: runtimeApiKeySource,
+                    persistedApiKeyRemoved,
+                    envCleared,
+                    apiKeyStorePath: API_KEY_STORE_PATH,
+                    message: "Active key cleared from memory and persisted store. If clearEnv=false and env still has DRITAN_API_KEY, restarting may load that env key.",
+                });
+            }
             case "dritan_health": {
                 return ok(await checkDritanHealth());
             }
@@ -1231,8 +1328,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return ok({
                     ...(pricing ?? {}),
                     onboardingOptions: [
-                        "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.",
+                        "Default (x402-first): create wallet in current directory -> share wallet + backup path -> user funds wallet -> if no key exists, quote/payment/claim.",
+                        "Fallback only: user gets API key at https://dritan.dev and provides it as DRITAN_API_KEY if x402 cannot proceed.",
                     ],
                 });
             }
@@ -1267,7 +1364,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         activated: true,
                         source: runtimeApiKeySource,
                         preview: apiKeyPreview(activated),
-                        message: "x402-created API key is active for this MCP session (no restart needed).",
+                        apiKeyStorePath: API_KEY_STORE_PATH,
+                        message: "x402-created API key is active for this MCP session and persisted locally for restart recovery (no restart needed).",
                     };
                     Object.assign(payload, buildPostAuthGuidance());
                 }

package/package.json

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