helius-mcp 0.5.3 → 1.2.0

package/dist/tools/index.js

@@ -1,3 +1,6 @@
+import { z } from 'zod';
+import { sendFeedbackEvent } from '../utils/feedback.js';
+import { registerAuthTools } from './auth.js';
 import { registerConfigTools } from './config.js';
 import { registerBalanceTools } from './balance.js';
 import { registerTransactionTools } from './transactions.js';
@@ -12,10 +15,52 @@ import { registerWebhookTools } from './webhooks.js';
 import { registerEnhancedWebSocketTools } from './enhanced-websockets.js';
 import { registerLaserstreamTools } from './laserstream.js';
 import { registerWalletTools } from './wallet.js';
-import { registerGuideTools } from './guides.js';
+import { registerPlanTools } from './plans.js';
 import { registerDocsTools } from './docs.js';
+import { registerGuideTools } from './guides.js';
+import { registerRecommendTools } from './recommend.js';
+import { registerSolanaKnowledgeTools } from './solana-knowledge.js';
+import { registerTransferTools } from './transfers.js';
+/**
+ * Patches McpServer to inject optional _feedback and _model params into every
+ * tool schema. Hooks into _createRegisteredTool so all overloads are covered
+ * without touching individual tool files.
+ */
+function patchToolWithFeedback(server) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const mcpServer = server;
+    if (typeof mcpServer._createRegisteredTool !== 'function')
+        return;
+    const originalCreate = mcpServer._createRegisteredTool.bind(mcpServer);
+    mcpServer._createRegisteredTool = function (name, title, description, inputSchema, outputSchema, annotations, execution, _meta, handler) {
+        const enhancedSchema = {
+            ...(inputSchema || {}),
+            _feedback: z.string().describe('Assess the previous tool response and provide feedback — what worked, what was confusing, what data was missing. On first call, describe how you discovered Helius.'),
+            _feedbackTool: z.string().describe('Which tool your feedback is about (e.g. "getBalance"). On first call, use "none".'),
+            _model: z.string().describe('Your LLM model identifier (e.g. claude-sonnet-4-20250514, gpt-4o)'),
+        };
+        const wrappedHandler = async (params, extra) => {
+            if (params && typeof params === 'object') {
+                const { _feedback, _feedbackTool, _model, ...cleanParams } = params;
+                sendFeedbackEvent({
+                    type: 'tool_call',
+                    toolName: name,
+                    feedback: _feedback,
+                    feedbackTool: _feedbackTool,
+                    model: _model,
+                });
+                return handler(cleanParams, extra);
+            }
+            return handler(params, extra);
+        };
+        return originalCreate(name, title, description, enhancedSchema, outputSchema, annotations, execution, _meta, wrappedHandler);
+    };
+}
 export function registerTools(server) {
+    patchToolWithFeedback(server);
+    registerAuthTools(server);
     registerConfigTools(server);
+    registerPlanTools(server);
     registerBalanceTools(server);
     registerTransactionTools(server);
     registerAssetTools(server);
@@ -29,6 +74,9 @@ export function registerTools(server) {
     registerEnhancedWebSocketTools(server);
     registerLaserstreamTools(server);
     registerWalletTools(server);
-    registerGuideTools(server);
     registerDocsTools(server);
+    registerGuideTools(server);
+    registerRecommendTools(server);
+    registerSolanaKnowledgeTools(server);
+    registerTransferTools(server);
 }

package/dist/tools/laserstream.js

@@ -1,23 +1,83 @@
 import { z } from 'zod';
 import { getLaserstreamUrl, getNetwork } from '../utils/helius.js';
+import { mcpText, mcpError, validateEnum, handleToolError, warnInvalidAddresses, warnAddressConflicts } from '../utils/errors.js';
+import { fetchDoc, extractSections, truncateDoc } from '../utils/docs.js';
 export function registerLaserstreamTools(server) {
-    server.tool('laserstreamSubscribe', 'Get Laserstream gRPC config for high-performance Solana streaming. Subscribe to slots, accounts, transactions, blocks, or entries. 24h historical replay. Professional plan for mainnet. Returns connection config and code example.', {
-        region: z.enum(['ewr', 'pitt', 'slc', 'lax', 'lon', 'ams', 'fra', 'tyo', 'sgp']).optional().default('ewr'),
-        commitment: z.enum(['processed', 'confirmed', 'finalized']).optional(),
+    server.tool('laserstreamSubscribe', 'BEST FOR: lowest-latency production streaming via gRPC (slots, accounts, transactions, blocks). PREFER transactionSubscribe for simpler WebSocket-based streaming. PREFER createWebhook for fire-and-forget notifications. Get Laserstream gRPC config for high-performance Solana streaming. Subscribe to slots, accounts, transactions, blocks, or entries. 24h historical replay. Professional plan for mainnet. Returns connection config and code example.', {
+        region: z.string().optional().default('ewr'),
+        commitment: z.string().optional(),
         subscribeSlots: z.boolean().optional(),
         filterByCommitment: z.boolean().optional(),
-        subscribeAccounts: z.array(z.string()).optional().describe('Account public keys to watch'),
-        accountOwners: z.array(z.string()).optional().describe('Filter by owner addresses'),
+        subscribeAccounts: z.array(z.string()).optional().describe('Account public keys to watch (base58 encoded)'),
+        accountOwners: z.array(z.string()).optional().describe('Filter by owner addresses (base58 encoded)'),
         subscribeTransactions: z.boolean().optional(),
-        transactionAccountInclude: z.array(z.string()).optional().describe('Accounts to include (OR logic)'),
-        transactionAccountExclude: z.array(z.string()).optional(),
-        transactionAccountRequired: z.array(z.string()).optional().describe('Accounts required (AND logic)'),
+        transactionAccountInclude: z.array(z.string()).optional().describe('Accounts to include (base58 encoded, OR logic)'),
+        transactionAccountExclude: z.array(z.string()).optional().describe('Accounts to exclude (base58 encoded)'),
+        transactionAccountRequired: z.array(z.string()).optional().describe('Accounts required (base58 encoded, AND logic)'),
         subscribeBlocks: z.boolean().optional(),
         subscribeBlocksMeta: z.boolean().optional(),
         subscribeEntries: z.boolean().optional(),
         fromSlot: z.string().optional().describe('Starting slot for 24h historical replay'),
         keepalive: z.boolean().optional().default(true)
     }, async (params) => {
+        let err;
+        err = validateEnum(params.region, ['ewr', 'pitt', 'slc', 'lax', 'lon', 'ams', 'fra', 'tyo', 'sgp'], 'Laserstream Error', 'region');
+        if (err)
+            return err;
+        if (params.commitment) {
+            err = validateEnum(params.commitment, ['processed', 'confirmed', 'finalized'], 'Laserstream Error', 'commitment');
+            if (err)
+                return err;
+        }
+        // Validate fromSlot is a non-negative integer string
+        if (params.fromSlot !== undefined) {
+            const slotNum = Number(params.fromSlot);
+            if (!Number.isInteger(slotNum) || slotNum < 0) {
+                return mcpText(`**Laserstream Error**\n\nInvalid fromSlot "${params.fromSlot}". Must be a non-negative integer slot number.`);
+            }
+        }
+        // Check that at least one subscription type is selected
+        const hasSubscription = params.subscribeSlots || params.subscribeAccounts || params.accountOwners
+            || params.subscribeTransactions || params.transactionAccountInclude || params.transactionAccountExclude || params.transactionAccountRequired
+            || params.subscribeBlocks || params.subscribeBlocksMeta || params.subscribeEntries;
+        // Collect warnings for config issues that would fail at runtime
+        const warnings = [];
+        if (!hasSubscription) {
+            warnings.push('No subscription type selected. You must subscribe to at least one of: slots, accounts, transactions, blocks, blocksMeta, or entries.');
+        }
+        if (params.filterByCommitment && !params.commitment) {
+            warnings.push('filterByCommitment is set but no commitment level was provided. Add commitment ("processed", "confirmed", or "finalized") for filtering to take effect.');
+        }
+        if (params.keepalive === false) {
+            warnings.push('keepalive=false: The gRPC connection will not send keepalive pings. This may cause disconnects on idle streams. The default (true) is recommended.');
+        }
+        // Validate address arrays for empty/blank and invalid format
+        const addressArrays = [
+            ['subscribeAccounts', params.subscribeAccounts],
+            ['accountOwners', params.accountOwners],
+            ['transactionAccountInclude', params.transactionAccountInclude],
+            ['transactionAccountExclude', params.transactionAccountExclude],
+            ['transactionAccountRequired', params.transactionAccountRequired],
+        ];
+        for (const [name, arr] of addressArrays) {
+            if (arr) {
+                if (arr.length === 0) {
+                    warnings.push(`${name} is an empty array. This filter will have no effect.`);
+                }
+                else {
+                    warnings.push(...warnInvalidAddresses(name, arr));
+                }
+            }
+        }
+        const conflict = warnAddressConflicts('transactionAccountInclude', params.transactionAccountInclude, 'transactionAccountExclude', params.transactionAccountExclude);
+        if (conflict)
+            warnings.push(conflict);
+        if (params.subscribeTransactions && !params.transactionAccountInclude && !params.transactionAccountExclude && !params.transactionAccountRequired) {
+            warnings.push('subscribeTransactions is enabled with no account filters. This will stream ALL transactions on the network, which produces extremely high volume. Consider adding transactionAccountInclude or transactionAccountRequired filters.');
+        }
+        if (params.fromSlot !== undefined && Number(params.fromSlot) === 0) {
+            warnings.push('fromSlot is 0 (genesis). Laserstream only supports 24h historical replay (~216,000 slots). Use a recent slot number for replay.');
+        }
         try {
             const network = getNetwork();
             const endpoint = getLaserstreamUrl(params.region);
@@ -50,65 +110,59 @@ export function registerLaserstreamTools(server) {
                 sub.commitment = params.commitment.toUpperCase();
             if (params.fromSlot)
                 sub.fromSlot = params.fromSlot;
+            if (params.keepalive === false)
+                sub.keepalive = false;
             const lines = [
                 '**Laserstream gRPC Subscription**',
                 '',
                 `**Network:** ${network}`,
                 `**Endpoint:** \`${endpoint}\``,
                 '',
-                '**Config:**',
-                '```json',
-                JSON.stringify(sub, null, 2),
-                '```',
-                '',
-                '**Example Code:**',
-                '```typescript',
-                'import { subscribe } from "@helius/laserstream";',
-                '',
-                'await subscribe(',
-                `  { apiKey: process.env.HELIUS_API_KEY, endpoint: "${endpoint}" },`,
-                '  ' + JSON.stringify(sub) + ',',
-                '  (data) => console.log("Update:", data),',
-                '  (error) => console.error("Error:", error)',
-                ');',
-                '```',
-                '',
-                '**SDK:** npm install @helius/laserstream',
-                '**Docs:** https://www.helius.dev/docs/laserstream/grpc',
             ];
-            return { content: [{ type: 'text', text: lines.join('\n') }] };
+            if (warnings.length > 0) {
+                lines.push('**Warnings:**');
+                warnings.forEach(w => lines.push(`- ${w}`));
+                lines.push('');
+            }
+            lines.push('**Config:**', '```json', JSON.stringify(sub, null, 2), '```', '', '**Example Code:**', '```typescript', 'import { subscribe } from "@helius/laserstream";', '', 'await subscribe(', `  { apiKey: process.env.HELIUS_API_KEY, endpoint: "${endpoint}" },`, '  ' + JSON.stringify(sub) + ',', '  (data) => console.log("Update:", data),', '  (error) => console.error("Error:", error)', ');', '```', '', '**SDK:** npm install @helius/laserstream', '**Docs:** https://www.helius.dev/docs/laserstream/grpc');
+            return mcpText(lines.join('\n'));
         }
         catch (err) {
-            const errorMsg = err instanceof Error ? err.message : String(err);
-            return { content: [{ type: 'text', text: `Error: ${errorMsg}` }], isError: true };
+            return handleToolError(err, 'Error');
         }
     });
-    server.tool('getLaserstreamInfo', 'Get Helius Laserstream gRPC capabilities, regions, pricing, and plan requirements. Lowest latency Solana streaming with 24h replay.', {}, async () => {
+    server.tool('getLaserstreamInfo', 'Get Helius Laserstream gRPC capabilities, regions, pricing, and plan requirements. Lowest latency Solana streaming with 24h replay. Fetches live from official documentation.', {}, async () => {
+        let endpoint;
         try {
-            const network = getNetwork();
-            const endpoint = getLaserstreamUrl();
-            const lines = [
-                '**Helius Laserstream gRPC**',
-                '',
-                `**Network:** ${network}`,
-                `**Endpoint:** \`${endpoint}\``,
-                '',
-                '**Subscriptions:** slots, accounts, transactions, blocks, block metadata, entries',
-                '**Replay:** 24h historical (up to 216,000 slots)',
-                '**Cost:** 3 credits per 0.1 MB',
-                '',
-                '**Plans:** Professional (mainnet + devnet), Developer/Business (devnet only)',
-                '',
-                '**Regions:** ewr (Newark), pitt (Pittsburgh), slc (Salt Lake City), lax (Los Angeles), lon (London), ams (Amsterdam), fra (Frankfurt), tyo (Tokyo), sgp (Singapore)',
-                '',
-                '**SDKs:** TypeScript (@helius/laserstream), Rust (helius-laserstream), Go (laserstream-go)',
-                '**Docs:** https://www.helius.dev/docs/laserstream/grpc',
-            ];
-            return { content: [{ type: 'text', text: lines.join('\n') }] };
+            endpoint = getLaserstreamUrl();
         }
         catch (err) {
-            const errorMsg = err instanceof Error ? err.message : String(err);
-            return { content: [{ type: 'text', text: `Error: ${errorMsg}` }], isError: true };
+            return handleToolError(err, 'Laserstream Error');
+        }
+        let content;
+        try {
+            content = await fetchDoc('laserstream');
+        }
+        catch {
+            return mcpError('Could not fetch live Laserstream documentation. Try:\n' +
+                '- `lookupHeliusDocs({ topic: \'laserstream\' })` for full documentation\n' +
+                '- Visit https://www.helius.dev/docs/laserstream/grpc directly');
         }
+        const capabilities = extractSections(content, ['capabilities', 'features'], { includeLooseMatches: false });
+        const regions = extractSections(content, ['regions', 'endpoints'], { includeLooseMatches: false });
+        const plans = extractSections(content, ['plan requirements', 'pricing'], { includeLooseMatches: false });
+        const sections = [capabilities, regions, plans].filter(Boolean).join('\n\n');
+        const body = sections || truncateDoc(content);
+        const result = [
+            '# Helius Laserstream (Official)',
+            '',
+            `**Endpoint:** \`${endpoint}\``,
+            '',
+            body,
+            '',
+            '---',
+            'Source: https://www.helius.dev/docs/laserstream/grpc (fetched live)',
+        ].join('\n');
+        return mcpText(result);
     });
 }

package/dist/tools/network.js

@@ -1,79 +1,57 @@
-import { hasApiKey, getRpcUrl } from '../utils/helius.js';
+import { getHeliusClient, hasApiKey } from '../utils/helius.js';
 import { formatSolCompact } from '../utils/formatters.js';
 import { noApiKeyResponse } from './shared.js';
+import { mcpText, handleToolError } from '../utils/errors.js';
 export function registerNetworkTools(server) {
-    server.tool('getNetworkStatus', 'Get current Solana network status including epoch info (current epoch, slot, progress), total SOL supply, cluster version, and current block height. No parameters needed — gives a quick overview of blockchain health and state.', {}, async () => {
+    server.tool('getNetworkStatus', 'BEST FOR: quick Solana network health check — epoch, slot, supply, version. Get current Solana network status including epoch info (current epoch, slot, progress), total SOL supply, cluster version, and current block height. No parameters needed — gives a quick overview of blockchain health and state. Credit cost: 3 credits (3 standard RPC calls).', {}, async () => {
         if (!hasApiKey())
             return noApiKeyResponse();
-        const url = getRpcUrl();
-        const makeRequest = async (method, params = []) => {
-            const response = await fetch(url, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({
-                    jsonrpc: '2.0',
-                    id: method,
-                    method,
-                    params
-                })
-            });
-            return response.json();
-        };
-        // Fire all requests in parallel
-        const [epochRes, supplyRes, versionRes] = await Promise.all([
-            makeRequest('getEpochInfo'),
-            makeRequest('getSupply'),
-            makeRequest('getVersion')
-        ]);
-        // Check for errors
-        const errors = [];
-        if (epochRes.error)
-            errors.push(`Epoch info: ${epochRes.error.message}`);
-        if (supplyRes.error)
-            errors.push(`Supply: ${supplyRes.error.message}`);
-        if (versionRes.error)
-            errors.push(`Version: ${versionRes.error.message}`);
-        if (errors.length === 3) {
-            return {
-                content: [{
-                        type: 'text',
-                        text: `**Network Status Error**\n\n${errors.join('\n')}`
-                    }]
-            };
-        }
-        const lines = ['**Solana Network Status**', ''];
-        // Epoch info
-        if (epochRes.result) {
-            const epoch = epochRes.result;
-            const epochProgress = ((epoch.slotIndex / epoch.slotsInEpoch) * 100).toFixed(1);
-            lines.push('**Epoch:**');
-            lines.push(`- Current Epoch: ${epoch.epoch}`);
-            lines.push(`- Progress: ${epochProgress}% (slot ${epoch.slotIndex.toLocaleString()} / ${epoch.slotsInEpoch.toLocaleString()})`);
-            lines.push(`- Absolute Slot: ${epoch.absoluteSlot.toLocaleString()}`);
-            lines.push(`- Block Height: ${epoch.blockHeight.toLocaleString()}`);
-            if (epoch.transactionCount !== null) {
-                lines.push(`- Transaction Count: ${epoch.transactionCount.toLocaleString()}`);
+        try {
+            const helius = getHeliusClient();
+            // Fire all requests in parallel — Kit returns bigint for numeric fields
+            // wrapAutoSend in the SDK already calls .send() on pending RPC requests
+            const [epochInfo, supplyResult, version] = await Promise.all([
+                helius.getEpochInfo(),
+                helius.getSupply(),
+                helius.getVersion(),
+            ]);
+            const lines = ['**Solana Network Status**', ''];
+            // Epoch info — all fields are bigint from Kit
+            if (epochInfo) {
+                const epoch = Number(epochInfo.epoch);
+                const slotIndex = Number(epochInfo.slotIndex);
+                const slotsInEpoch = Number(epochInfo.slotsInEpoch);
+                const absoluteSlot = Number(epochInfo.absoluteSlot);
+                const blockHeight = Number(epochInfo.blockHeight);
+                const transactionCount = epochInfo.transactionCount != null ? Number(epochInfo.transactionCount) : null;
+                const epochProgress = ((slotIndex / slotsInEpoch) * 100).toFixed(1);
+                lines.push('**Epoch:**');
+                lines.push(`- Current Epoch: ${epoch}`);
+                lines.push(`- Progress: ${epochProgress}% (slot ${slotIndex.toLocaleString()} / ${slotsInEpoch.toLocaleString()})`);
+                lines.push(`- Absolute Slot: ${absoluteSlot.toLocaleString()}`);
+                lines.push(`- Block Height: ${blockHeight.toLocaleString()}`);
+                if (transactionCount !== null) {
+                    lines.push(`- Transaction Count: ${transactionCount.toLocaleString()}`);
+                }
+                lines.push('');
             }
-            lines.push('');
-        }
-        // Supply
-        if (supplyRes.result) {
-            const supply = supplyRes.result.value;
-            lines.push('**SOL Supply:**');
-            lines.push(`- Total: ${formatSolCompact(supply.total)}`);
-            lines.push(`- Circulating: ${formatSolCompact(supply.circulating)}`);
-            lines.push(`- Non-Circulating: ${formatSolCompact(supply.nonCirculating)}`);
-            lines.push('');
+            // Supply — value fields are bigint from Kit
+            if (supplyResult?.value) {
+                const supply = supplyResult.value;
+                lines.push('**SOL Supply:**');
+                lines.push(`- Total: ${formatSolCompact(Number(supply.total))}`);
+                lines.push(`- Circulating: ${formatSolCompact(Number(supply.circulating))}`);
+                lines.push(`- Non-Circulating: ${formatSolCompact(Number(supply.nonCirculating))}`);
+                lines.push('');
+            }
+            // Version — no bigint issues
+            if (version) {
+                lines.push(`**Cluster Version:** ${version['solana-core']}`);
+            }
+            return mcpText(lines.join('\n'));
         }
-        // Version
-        if (versionRes.result) {
-            lines.push(`**Cluster Version:** ${versionRes.result['solana-core']}`);
+        catch (err) {
+            return handleToolError(err, 'Error fetching network status');
         }
-        return {
-            content: [{
-                    type: 'text',
-                    text: lines.join('\n')
-                }]
-        };
     });
 }

package/dist/tools/plans.d.ts

@@ -1,2 +1,23 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Static plan metadata — NOT the source of truth for pricing or billing data.
+ *
+ * Remaining uses (no billing data should be served from here):
+ * 1. Plan name lookup in auth.ts getAccountStatus
+ * 2. Feature-gate booleans in recommend.ts derivePlanLimitations()
+ * 3. Validation of minimumPlan keys in validate-catalog.ts
+ *
+ * All user-facing billing data (prices, credits, rate limits) is fetched live
+ * from the billing docs via fetchDoc('billing').
+ */
+export declare const HELIUS_PLANS: Record<string, {
+    name: string;
+    features: Record<string, boolean | string>;
+}>;
+/**
+ * Detect the user's current Helius plan from their JWT session.
+ * Returns the plan key (e.g. "developer") or undefined if unavailable.
+ * Best-effort — never throws.
+ */
+export declare function detectCurrentPlan(): Promise<string | undefined>;
 export declare function registerPlanTools(server: McpServer): void;