helius-mcp 0.5.3 → 1.2.0

package/dist/utils/errors.js

@@ -0,0 +1,157 @@
+// ─── MCP Response Builders ───
+export function mcpText(text) {
+    return { content: [{ type: 'text', text }] };
+}
+export function mcpError(text) {
+    return { content: [{ type: 'text', text }], isError: true };
+}
+// ─── Error Message Extraction ───
+export function getErrorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+// ─── Error Classifiers ───
+export function isAddressError(msg) {
+    return msg.includes('Pubkey Validation Err')
+        || msg.includes('Invalid param')
+        || msg.includes('Invalid pubkey')
+        || msg.includes('Validation Error');
+}
+export function isPaginationError(msg) {
+    return msg.includes('Pagination Error')
+        || msg.includes('invalid value')
+        || msg.includes('expected u32')
+        || msg.includes('expected u64');
+}
+export function isNotFoundError(msg) {
+    return msg.includes('RecordNotFound')
+        || msg.includes('Asset Not Found')
+        || msg.includes('Asset Proof Not Found');
+}
+export function isHttp404Error(msg) {
+    return msg.includes('404')
+        || msg.includes('not found')
+        || msg.includes('Method not found');
+}
+export function isHttp400Error(msg) {
+    return msg.includes('400');
+}
+export function parseHttp400Messages(msg) {
+    try {
+        const json = JSON.parse(msg.replace(/^HTTP 400:\s*/, ''));
+        const messages = Array.isArray(json.message) ? json.message : [json.message];
+        return messages;
+    }
+    catch {
+        return null;
+    }
+}
+// ─── Enum Validation ───
+export function validateEnum(value, validOptions, context, fieldName) {
+    if (!validOptions.includes(value)) {
+        return mcpText(`**${context}**\n\nInvalid ${fieldName} "${value}". Valid options: ${validOptions.join(', ')}`);
+    }
+    return null;
+}
+// ─── HTTP Status Guidance ───
+const HTTP_GUIDANCE = {
+    '401': 'API key is invalid or expired. Call `setHeliusApiKey` with a valid key, or call `getAccountStatus` to check your current auth state.',
+    '403': 'This endpoint is restricted on your current plan. Call `getAccountStatus` to check your plan tier and remaining credits. Some endpoints (Enhanced Transactions, Token API) require Developer plan or higher. Call `getHeliusPlanInfo` to compare plans, or `previewUpgrade` to see upgrade pricing.',
+    '429': 'Rate limited. Call `getAccountStatus` to check your remaining credits and rate limits. Back off and retry, or call `previewUpgrade` to see upgrade options for higher limits.',
+    '502': 'Backend temporarily unavailable. Retry after a few seconds.',
+    '504': 'Gateway timeout — the request took too long. Try reducing the query scope (fewer addresses, smaller limit, narrower time range).',
+};
+function extractHttpGuidance(msg) {
+    for (const [status, guidance] of Object.entries(HTTP_GUIDANCE)) {
+        if (msg.includes(`HTTP ${status}`) || msg.includes(`status: ${status}`) || msg.includes(`(${status})`)) {
+            return guidance;
+        }
+    }
+    return null;
+}
+export function handleToolError(err, fallbackPrefix, handlers) {
+    const msg = getErrorMessage(err);
+    if (handlers) {
+        for (const handler of handlers) {
+            if (handler.match(msg))
+                return handler.respond(msg);
+        }
+    }
+    const guidance = extractHttpGuidance(msg);
+    if (guidance) {
+        return mcpError(`**${fallbackPrefix}:** ${msg}\n\n${guidance}`);
+    }
+    return mcpError(`**${fallbackPrefix}:** ${msg}`);
+}
+// ─── Pre-built Handler Factories ───
+export function addressError(header, detail) {
+    return {
+        match: isAddressError,
+        respond: () => mcpText(`**${header}**\n\n${detail || 'Invalid Solana address. Please provide a valid base58-encoded address.'}`),
+    };
+}
+export function paginationError(header, detail) {
+    return {
+        match: isPaginationError,
+        respond: () => mcpText(`**${header}**\n\n${detail || 'Invalid pagination parameters. Page must be at least 1 and limit must be between 1 and 1000.'}`),
+    };
+}
+export function notFoundError(header, detail) {
+    return {
+        match: isNotFoundError,
+        respond: () => mcpText(`**${header}**\n\n${detail || 'Asset not found. This mint address does not exist or has not been indexed.'}`),
+    };
+}
+export function http404Error(header, detail) {
+    return {
+        match: isHttp404Error,
+        respond: () => header ? mcpText(`**${header}**\n\n${detail}`) : mcpText(detail),
+    };
+}
+export function http400Error(header) {
+    return {
+        match: isHttp400Error,
+        respond: (msg) => {
+            const messages = parseHttp400Messages(msg);
+            if (messages) {
+                return mcpText(`**${header}**\n\n${messages.map((m) => `- ${m}`).join('\n')}`);
+            }
+            return mcpError(`**${header}:** ${msg}`);
+        },
+    };
+}
+// ─── Address Format Validation (for config-generation warnings) ───
+const SOLANA_ADDRESS_REGEX = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+export function isValidAddressFormat(address) {
+    return SOLANA_ADDRESS_REGEX.test(address);
+}
+export function warnInvalidAddresses(paramName, addresses) {
+    const warnings = [];
+    const empty = addresses.filter(a => !a || !a.trim());
+    if (empty.length > 0) {
+        warnings.push(`${paramName} contains ${empty.length} empty/blank address(es). These will be rejected by the endpoint.`);
+    }
+    const invalid = addresses.filter(a => a && a.trim() && !isValidAddressFormat(a.trim()));
+    if (invalid.length > 0) {
+        warnings.push(`${paramName} contains ${invalid.length} address(es) with invalid format: ${invalid.slice(0, 3).map(a => `"${a}"`).join(', ')}${invalid.length > 3 ? `, ... (${invalid.length} total)` : ''}. Solana addresses are 32-44 base58 characters.`);
+    }
+    return warnings;
+}
+export function warnInvalidAddress(paramName, address) {
+    if (!address || !address.trim()) {
+        return `${paramName} is empty/blank. A valid Solana address is required.`;
+    }
+    if (!isValidAddressFormat(address.trim())) {
+        return `${paramName} "${address}" does not look like a valid Solana address (expected 32-44 base58 characters).`;
+    }
+    return null;
+}
+export function warnAddressConflicts(includeName, includeAddresses, excludeName, excludeAddresses) {
+    if (!includeAddresses || !excludeAddresses)
+        return null;
+    const includeSet = new Set(includeAddresses.map(a => a.trim()));
+    const overlap = excludeAddresses.filter(a => includeSet.has(a.trim()));
+    if (overlap.length > 0) {
+        return `${overlap.length} address(es) appear in both ${includeName} and ${excludeName}: ${overlap.slice(0, 3).map(a => `"${a}"`).join(', ')}${overlap.length > 3 ? `, ... (${overlap.length} total)` : ''}. These addresses will be included and excluded simultaneously, which may cause unexpected behavior.`;
+    }
+    return null;
+}

package/dist/utils/feedback.d.ts

@@ -0,0 +1,16 @@
+interface FeedbackEvent {
+    type: 'tool_call' | 'discovery';
+    toolName?: string;
+    feedback?: string;
+    feedbackTool?: string;
+    model?: string;
+    discoveryPath?: string;
+    frictionPoints?: string;
+}
+export declare function captureClientInfo(info: {
+    name: string;
+    version: string;
+}): void;
+export declare function captureWalletAddress(address: string): void;
+export declare function sendFeedbackEvent(event: FeedbackEvent): void;
+export {};

package/dist/utils/feedback.js

@@ -0,0 +1,87 @@
+import { version } from '../version.js';
+import crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+const POSTHOG_ENDPOINT = 'https://www.helius.dev/relay-RMqE/capture/';
+const POSTHOG_API_KEY = 'phc_aLmID5mMwUZi3pVhG4HomDeZaWZ1PqAEkWTempDogzi';
+const HELIUS_DIR = path.join(os.homedir(), '.helius');
+const ANON_ID_PATH = path.join(HELIUS_DIR, 'anon-id');
+let clientInfo = null;
+let feedbackEnabled = true;
+let walletAddress = null;
+let identifySent = false;
+// Persistent anonymous ID shared with helius-cli.
+let sessionId;
+try {
+    if (fs.existsSync(ANON_ID_PATH)) {
+        sessionId = fs.readFileSync(ANON_ID_PATH, 'utf-8').trim();
+    }
+    else {
+        sessionId = crypto.randomUUID();
+        try {
+            fs.mkdirSync(HELIUS_DIR, { recursive: true });
+            fs.writeFileSync(ANON_ID_PATH, sessionId, 'utf-8');
+        }
+        catch { }
+    }
+}
+catch {
+    sessionId = crypto.randomUUID();
+}
+export function captureClientInfo(info) {
+    clientInfo = info;
+}
+export function captureWalletAddress(address) {
+    const previousId = walletAddress ? null : sessionId;
+    walletAddress = address;
+    if (previousId && !identifySent) {
+        identifySent = true;
+        posthogCapture('$identify', {
+            distinct_id: address,
+            $anon_distinct_id: previousId,
+        });
+    }
+}
+function getDistinctId() {
+    return walletAddress || sessionId;
+}
+function posthogCapture(event, properties) {
+    if (!feedbackEnabled)
+        return;
+    fetch(POSTHOG_ENDPOINT, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            api_key: POSTHOG_API_KEY,
+            event,
+            properties,
+        }),
+    }).catch(() => {
+        feedbackEnabled = false;
+    });
+}
+export function sendFeedbackEvent(event) {
+    const eventName = event.type === 'discovery' ? 'agent_discovery' : 'agent_invocation';
+    const properties = {
+        distinct_id: getDistinctId(),
+        helius_client: 'helius-mcp',
+        helius_version: version,
+    };
+    if (clientInfo) {
+        properties.mcp_client = `${clientInfo.name}/${clientInfo.version}`;
+    }
+    if (event.toolName)
+        properties.current_tool = event.toolName;
+    if (event.feedback)
+        properties.feedback = event.feedback;
+    if (event.feedbackTool)
+        properties.feedback_tool = event.feedbackTool;
+    if (event.model)
+        properties.llm_model = event.model;
+    if (event.discoveryPath)
+        properties.discovery_path = event.discoveryPath;
+    if (event.frictionPoints)
+        properties.friction_points = event.frictionPoints;
+    posthogCapture(eventName, properties);
+}

package/dist/utils/formatters.d.ts

@@ -4,4 +4,3 @@ export declare function formatAddress(address: string): string;
 export declare function formatTimestamp(unixTime: number): string;
 export declare function formatTokenAmount(amount: number, decimals: number): string;
 export declare function formatSolCompact(lamports: number): string;
-export declare function getOrbExplorerUrl(addressOrSignature: string, type?: 'address' | 'tx'): string;

package/dist/utils/formatters.js

@@ -18,6 +18,3 @@ export function formatTokenAmount(amount, decimals) {
 export function formatSolCompact(lamports) {
     return `${(lamports / LAMPORTS_PER_SOL).toLocaleString(undefined, { maximumFractionDigits: 0 })} SOL`;
 }
-export function getOrbExplorerUrl(addressOrSignature, type = 'address') {
-    return `https://orbmarkets.io/${type}/${addressOrSignature}`;
-}

package/dist/utils/helius.d.ts

@@ -1,13 +1,23 @@
 import { type HeliusClient } from 'helius-sdk';
+export declare function setSessionSecretKey(key: Uint8Array): void;
+export declare function getSessionSecretKey(): Uint8Array | null;
+export declare function setSessionWalletAddress(address: string): void;
+export declare function getSessionWalletAddress(): string | null;
 export declare function setApiKey(apiKey: string): void;
 export declare function getApiKey(): string;
 export declare function hasApiKey(): boolean;
 export declare function getHeliusClient(): HeliusClient;
-export declare function setNetwork(network: 'mainnet' | 'devnet'): void;
-export declare function getNetwork(): 'mainnet' | 'devnet';
-export declare function getRpcUrl(): string;
+export declare function setNetwork(network: 'mainnet-beta' | 'devnet'): void;
+export declare function getNetwork(): 'mainnet-beta' | 'devnet';
 export declare function getEnhancedWebSocketUrl(): string;
 export declare function getLaserstreamUrl(region?: 'ewr' | 'pitt' | 'slc' | 'lax' | 'lon' | 'ams' | 'fra' | 'tyo' | 'sgp'): string;
-export declare function rpcRequest(method: string, params?: any[]): Promise<any>;
-export declare function dasRequest(method: string, params?: any): Promise<any>;
+/**
+ * Load the signer keypair from session or disk.
+ * Returns the raw secret key bytes and the wallet address string.
+ * Throws with message 'NO_KEYPAIR' if no keypair is available.
+ */
+export declare function loadSignerOrFail(): Promise<{
+    secretKey: Uint8Array;
+    walletAddress: string;
+}>;
 export declare function restRequest(endpoint: string, options?: RequestInit): Promise<any>;

package/dist/utils/helius.js

@@ -1,28 +1,42 @@
 import { createHelius } from 'helius-sdk';
+import { MCP_USER_AGENT } from '../http.js';
+import { getSharedApiKey } from './config.js';
 let sessionApiKey = null;
-let sessionNetwork = 'mainnet';
+let sessionNetwork = 'mainnet-beta';
 let heliusClient = null;
+// Session keypair storage for auth flow
+let sessionSecretKey = null;
+let sessionWalletAddress = null;
+export function setSessionSecretKey(key) {
+    sessionSecretKey = key;
+}
+export function getSessionSecretKey() {
+    return sessionSecretKey;
+}
+export function setSessionWalletAddress(address) {
+    sessionWalletAddress = address;
+}
+export function getSessionWalletAddress() {
+    return sessionWalletAddress;
+}
 export function setApiKey(apiKey) {
     sessionApiKey = apiKey;
     heliusClient = null; // Reset client so it picks up new key
 }
 export function getApiKey() {
-    const apiKey = sessionApiKey || process.env.HELIUS_API_KEY;
+    const apiKey = sessionApiKey || process.env.HELIUS_API_KEY || getSharedApiKey();
     if (!apiKey) {
-        throw new Error('API key not set. Please use the setHeliusApiKey tool first:\n\n' +
-            '  Tool: setHeliusApiKey\n' +
-            '  Arguments: { "apiKey": "your-helius-api-key" }\n\n' +
-            'Get your free API key at: https://dashboard.helius.dev/api-keys');
+        throw new Error('NO_API_KEY: Set HELIUS_API_KEY environment variable or use setHeliusApiKey tool');
     }
     return apiKey;
 }
 export function hasApiKey() {
-    return !!(sessionApiKey || process.env.HELIUS_API_KEY);
+    return !!(sessionApiKey || process.env.HELIUS_API_KEY || getSharedApiKey());
 }
 export function getHeliusClient() {
     if (!heliusClient) {
         const apiKey = getApiKey();
-        heliusClient = createHelius({ apiKey });
+        heliusClient = createHelius({ apiKey, userAgent: MCP_USER_AGENT });
     }
     return heliusClient;
 }
@@ -31,19 +45,11 @@ export function setNetwork(network) {
 }
 export function getNetwork() {
     const envNetwork = process.env.HELIUS_NETWORK;
-    if (envNetwork === 'devnet' || envNetwork === 'mainnet') {
+    if (envNetwork === 'devnet' || envNetwork === 'mainnet-beta') {
         return envNetwork;
     }
     return sessionNetwork;
 }
-export function getRpcUrl() {
-    const apiKey = getApiKey();
-    const network = getNetwork();
-    if (network === 'devnet') {
-        return `https://devnet.helius-rpc.com/?api-key=${apiKey}`;
-    }
-    return `https://mainnet.helius-rpc.com/?api-key=${apiKey}`;
-}
 export function getEnhancedWebSocketUrl() {
     const apiKey = getApiKey();
     const network = getNetwork();
@@ -61,43 +67,44 @@ export function getLaserstreamUrl(region) {
     const selectedRegion = region || 'ewr';
     return `https://laserstream-mainnet-${selectedRegion}.helius-rpc.com`;
 }
-export async function rpcRequest(method, params = []) {
-    const url = getRpcUrl();
-    const response = await fetch(url, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ jsonrpc: '2.0', id: Date.now(), method, params }),
-    });
-    if (!response.ok) {
-        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-    }
-    const data = await response.json();
-    if (data.error) {
-        throw new Error(`RPC Error: ${data.error.message || JSON.stringify(data.error)}`);
+/**
+ * Load the signer keypair from session or disk.
+ * Returns the raw secret key bytes and the wallet address string.
+ * Throws with message 'NO_KEYPAIR' if no keypair is available.
+ */
+export async function loadSignerOrFail() {
+    // Lazy-import to avoid circular deps (config → helius → config)
+    const { loadKeypairFromDisk } = await import('./config.js');
+    const { loadKeypair } = await import('helius-sdk/auth/loadKeypair');
+    const { getAddress } = await import('helius-sdk/auth/getAddress');
+    let secretKey = getSessionSecretKey();
+    if (!secretKey) {
+        secretKey = loadKeypairFromDisk();
+        if (secretKey) {
+            const walletKeypair = loadKeypair(secretKey);
+            const addr = await getAddress(walletKeypair);
+            setSessionSecretKey(secretKey);
+            setSessionWalletAddress(addr);
+        }
     }
-    return data.result;
-}
-export async function dasRequest(method, params = {}) {
-    const url = getRpcUrl();
-    const response = await fetch(url, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ jsonrpc: '2.0', id: Date.now(), method, params }),
-    });
-    if (!response.ok) {
-        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    if (!secretKey) {
+        throw new Error('NO_KEYPAIR');
     }
-    const data = await response.json();
-    if (data.error) {
-        throw new Error(`DAS Error: ${data.error.message || JSON.stringify(data.error)}`);
+    // Derive the address from the key if not already cached in session
+    let walletAddress = getSessionWalletAddress();
+    if (!walletAddress) {
+        const walletKeypair = loadKeypair(secretKey);
+        walletAddress = await getAddress(walletKeypair);
+        setSessionWalletAddress(walletAddress);
     }
-    return data.result;
+    return { secretKey, walletAddress };
 }
 export async function restRequest(endpoint, options = {}) {
     const apiKey = getApiKey();
     const separator = endpoint.includes('?') ? '&' : '?';
     const url = `https://api.helius.xyz${endpoint}${separator}api-key=${apiKey}`;
     const headers = { ...options.headers };
+    headers['User-Agent'] = MCP_USER_AGENT;
     if (options.body) {
         headers['Content-Type'] ??= 'application/json';
     }

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const version = "1.2.0";

package/dist/version.js

@@ -0,0 +1 @@
+export const version = '1.2.0';

package/package.json

@@ -1,26 +1,31 @@
 {
   "name": "helius-mcp",
-  "version": "0.5.3",
-  "description": "Official Helius MCP Server - Complete Solana blockchain data access for Claude",
+  "version": "1.2.0",
+  "description": "Official Helius MCP Server - Complete Solana blockchain data access for AI assistants",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
     "helius-mcp": "dist/index.js"
   },
   "scripts": {
+    "prebuild": "node -p \"'export const version = \\'' + require('./package.json').version + '\\';'\" > src/version.ts",
     "build": "tsc",
     "dev": "tsc --watch",
     "start": "node dist/index.js",
-    "prepublishOnly": "pnpm build",
-    "test": "vitest run"
+    "validate": "node dist/scripts/validate-catalog.js",
+    "test": "pnpm build && pnpm validate && vitest run",
+    "changelog": "auto-changelog --tag-prefix helius-mcp@",
+    "prepublishOnly": "pnpm build"
   },
   "keywords": [
     "helius",
     "solana",
     "blockchain",
     "mcp",
-    "claude",
+    "model-context-protocol",
     "ai",
+    "llm",
+    "claude",
     "web3",
     "nft",
     "defi",
@@ -36,18 +41,23 @@
   "homepage": "https://github.com/helius-labs/core-ai#readme",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
+    "@solana-program/system": "^0.10.0",
+    "@solana-program/token": "^0.9.0",
+    "@solana/kit": "^5.0.0",
     "bs58": "^6.0.0",
-    "helius-sdk": "^2.0.5",
+    "helius-sdk": "^2.2.2",
     "zod": "^3.23.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
-    "@vitest/coverage-v8": "^2.0.0",
+    "auto-changelog": "^2.5.0",
     "typescript": "^5.4.0",
     "vitest": "^2.0.0"
   },
   "files": [
     "dist",
+    "system-prompts",
+    "CHANGELOG.md",
     "README.md",
     "LICENSE"
   ]