helius-mcp 1.3.0 → 2.0.0

package/dist/tools/config.js

@@ -1,12 +1,12 @@
 import { z } from 'zod';
 import { setApiKey, setNetwork, hasApiKey, getHeliusClient } from '../utils/helius.js';
-import { mcpText, validateEnum, getErrorMessage } from '../utils/errors.js';
+import { mcpText, mcpError, validateEnum, getErrorMessage } from '../utils/errors.js';
 import { setSharedApiKey, SHARED_CONFIG_PATH } from '../utils/config.js';
 export function registerConfigTools(server) {
     const keyFromEnv = hasApiKey();
     server.tool('setHeliusApiKey', keyFromEnv
         ? 'API key is already configured via environment. You do NOT need to call this tool - just use the other Helius tools directly.'
-        : 'Set an existing Helius API key for the current session. If the user does not have a key, use the agentic signup flow instead: generateKeypair → fund wallet → agenticSignup. Get a key at https://dashboard.helius.dev/api-keys', {
+        : 'Set an existing Helius API key for the current session. If the user does not have a key, use the signup flow instead: generateKeypair → signup (link mode prints a payment URL). Get a key at https://dashboard.helius.dev/api-keys', {
         apiKey: z.string().describe('Your Helius API key from https://dashboard.helius.dev/api-keys'),
         network: z.string().optional().default('mainnet-beta').describe('Network to use (default: mainnet-beta)')
     }, async ({ apiKey, network }) => {
@@ -28,7 +28,7 @@ export function registerConfigTools(server) {
             const errorMsg = getErrorMessage(e);
             if (errorMsg.includes('invalid api key') || errorMsg.includes('401') || errorMsg.includes('Unauthorized')) {
                 setApiKey('');
-                return mcpText(`❌ Invalid API key. Please check your key and try again.\n\nGet your key at https://dashboard.helius.dev/api-keys`);
+                return mcpError(`❌ Invalid API key. Please check your key and try again.\n\nGet your key at https://dashboard.helius.dev/api-keys`, { type: 'AUTH', code: 'INVALID_API_KEY', retryable: false, recovery: 'Check your API key at https://dashboard.helius.dev/api-keys and call setHeliusApiKey with a valid key.' });
             }
         }
         setSharedApiKey(apiKey);

package/dist/tools/das-extras.js

@@ -29,7 +29,7 @@ export function registerDasExtraTools(server) {
             return noApiKeyResponse();
         try {
             if (ids.length > 1000) {
-                return mcpError('Max 1000 proofs per batch');
+                return mcpError('Max 1000 proofs per batch', { type: 'VALIDATION', code: 'TOO_MANY_ITEMS', retryable: false, recovery: 'Reduce batch to 1000 or fewer.' });
             }
             const helius = getHeliusClient();
             const result = await helius.getAssetProofBatch({ ids });
@@ -45,8 +45,8 @@ export function registerDasExtraTools(server) {
     });
     server.tool('getSignaturesForAsset', 'BEST FOR: transaction history for a specific asset by mint address. PREFER getTransactionHistory for wallet-level transaction history. Get transaction history for any DAS asset. DAS API (10 credits/call).', {
         id: z.string().describe('Asset mint address (base58 encoded, any DAS asset)'),
-        page: z.number().optional().default(1),
-        limit: z.number().optional().default(20)
+        page: z.number().optional().default(1).describe('Page number for pagination (default: 1)'),
+        limit: z.number().optional().default(20).describe('Results per page, max 1000 (default: 20)')
     }, async ({ id, page, limit }) => {
         if (!hasApiKey())
             return noApiKeyResponse();
@@ -75,8 +75,8 @@ export function registerDasExtraTools(server) {
     });
     server.tool('getNftEditions', 'BEST FOR: finding numbered edition prints of a master NFT. Get all edition NFTs for a master NFT. DAS API (10 credits/call).', {
         mint: z.string().describe('Master NFT mint address (base58 encoded)'),
-        page: z.number().optional().default(1),
-        limit: z.number().optional().default(20)
+        page: z.number().optional().default(1).describe('Page number for pagination (default: 1)'),
+        limit: z.number().optional().default(20).describe('Results per page, max 1000 (default: 20)')
     }, async ({ mint, page, limit }) => {
         if (!hasApiKey())
             return noApiKeyResponse();
@@ -98,7 +98,7 @@ export function registerDasExtraTools(server) {
         catch (err) {
             const header = `Editions for ${formatAddress(mint)}`;
             return handleToolError(err, 'Error fetching editions', [
-                { match: (m) => m.includes('null value was encountered'), respond: () => mcpText(`**${header}**\n\nThis mint is not a master edition NFT. getNftEditions only works with master edition mints.`) },
+                { match: (m) => m.includes('null value was encountered'), respond: () => mcpError(`**${header}**\n\nThis mint is not a master edition NFT. getNftEditions only works with master edition mints.`, { type: 'VALIDATION', code: 'INVALID_PARAM', retryable: false, recovery: 'Provide a master edition mint address. getNftEditions only works with master edition NFTs.' }) },
                 notFoundError(header, 'Asset not found. This mint address does not exist or has not been indexed.'),
                 addressError(header, 'Invalid Solana address. Please provide a valid base58-encoded mint address.'),
                 paginationError(header),

package/dist/tools/docs.js

@@ -1,5 +1,11 @@
 import { z } from 'zod';
 import { fetchDoc, getDocsIndex, extractSections, truncateDoc } from '../utils/docs.js';
+function getDocHeadings(content) {
+    return Array.from(content.matchAll(/^#{1,3}\s+(.+)$/gm))
+        .map((match) => match[1].trim())
+        .filter(Boolean)
+        .slice(0, 12);
+}
 export function registerDocsTools(server) {
     /**
      * Lookup Helius documentation - fetches official docs for accurate information
@@ -24,12 +30,48 @@ export function registerDocsTools(server) {
             'dedicated-nodes',
             'shred-delivery',
         ])
+            .optional()
             .describe('Documentation topic to fetch'),
         section: z
             .string()
             .optional()
             .describe('Optional: specific section to extract (e.g., "credits", "rate limits", "parameters"). If provided, returns only matching sections.'),
-    }, async ({ topic, section }) => {
+        query: z
+            .string()
+            .optional()
+            .describe('Freeform query — used to infer topic if topic is not provided'),
+    }, async ({ topic: rawTopic, section, query }) => {
+        const VALID_TOPICS = [
+            'overview', 'agents', 'billing', 'das', 'rpc', 'websocket',
+            'enhanced-websockets', 'webhooks', 'enhanced-transactions', 'sender',
+            'priority-fee', 'laserstream', 'wallet-api', 'zk-compression',
+            'dedicated-nodes', 'shred-delivery',
+        ];
+        let topic = rawTopic;
+        if (!topic && query) {
+            const q = query.toLowerCase();
+            topic = VALID_TOPICS.find((t) => q.includes(t))
+                ?? (q.includes('grpc') || q.includes('shred') && q.includes('stream') ? 'laserstream'
+                    : q.includes('nft') || q.includes('asset') ? 'das'
+                        : q.includes('webhook') ? 'webhooks'
+                            : q.includes('fee') || q.includes('priority') ? 'priority-fee'
+                                : q.includes('wallet') ? 'wallet-api'
+                                    : q.includes('compress') ? 'zk-compression'
+                                        : q.includes('websocket') || q.includes('ws') ? 'enhanced-websockets'
+                                            : q.includes('transaction') || q.includes('parsed') ? 'enhanced-transactions'
+                                                : q.includes('send') || q.includes('submit') ? 'sender'
+                                                    : undefined);
+        }
+        if (!topic) {
+            const topicList = VALID_TOPICS.map((t) => `\`${t}\``).join(', ');
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Missing required parameter: topic. Valid topics: ${topicList}`,
+                    }],
+                isError: true,
+            };
+        }
         try {
             const content = await fetchDoc(topic);
             // If a section filter is provided, extract relevant parts
@@ -51,7 +93,14 @@ export function registerDocsTools(server) {
                         content: [
                             {
                                 type: 'text',
-                                text: `No sections matching "${section}" found in ${topic} docs. Returning full documentation:\n\n${content}`,
+                                text: [
+                                    `No sections matching "${section}" were found in \`${topic}\` docs.`,
+                                    '',
+                                    'Available sections:',
+                                    ...getDocHeadings(content).map((heading) => `- ${heading}`),
+                                    '',
+                                    'Tip: retry with a more specific section filter or omit `section` to receive the default truncated document summary.',
+                                ].join('\n'),
                             },
                         ],
                     };
@@ -104,49 +153,14 @@ export function registerDocsTools(server) {
      */
     server.tool('getHeliusCreditsInfo', 'BEST FOR: credit cost lookup table. PREFER getRateLimitInfo for per-method rate limits, getHeliusPlanInfo for plan pricing. Get official Helius credit costs from documentation.', {}, async () => {
         try {
-            const content = await fetchDoc('overview');
-            // Extract credits section
-            const lines = content.split('\n');
-            const creditsLines = [];
-            let inCreditsSection = false;
-            for (let i = 0; i < lines.length; i++) {
-                const line = lines[i];
-                // Look for Credits section
-                if (line.includes('## Credits') || line.includes('| Credits |')) {
-                    inCreditsSection = true;
-                }
-                if (inCreditsSection) {
-                    creditsLines.push(line);
-                    // Stop at next major section
-                    if (creditsLines.length > 2 && line.startsWith('## ') && !line.includes('Credits')) {
-                        creditsLines.pop(); // Remove the next section header
-                        break;
-                    }
-                }
-            }
-            // Also look for the credits table
-            const tableLines = [];
-            for (let i = 0; i < lines.length; i++) {
-                if (lines[i].includes('| Credits |') || lines[i].includes('| 0 |') || lines[i].includes('| 1 |') || lines[i].includes('| 3 |') || lines[i].includes('| 10 |') || lines[i].includes('| 100 |')) {
-                    // Collect table lines
-                    let j = i;
-                    while (j < lines.length && (lines[j].includes('|') || lines[j].trim() === '')) {
-                        if (lines[j].includes('|')) {
-                            tableLines.push(lines[j]);
-                        }
-                        j++;
-                        if (j - i > 20)
-                            break; // Safety limit
-                    }
-                    break;
-                }
-            }
+            const content = await fetchDoc('billing');
+            const credits = extractSections(content, 'credits', { includeLooseMatches: true });
             const result = [
                 '# Helius Credit Costs (Official)',
                 '',
-                'Source: https://www.helius.dev/docs (fetched live)',
+                'Source: https://www.helius.dev/docs/billing (fetched live)',
                 '',
-                ...tableLines,
+                credits || 'Credits section not found in billing docs.',
             ].join('\n');
             return { content: [{ type: 'text', text: result }] };
         }

package/dist/tools/enhanced-websockets.js

@@ -3,18 +3,18 @@ import { getEnhancedWebSocketUrl } from '../utils/helius.js';
 import { mcpText, mcpError, validateEnum, handleToolError, warnInvalidAddresses, warnInvalidAddress, warnAddressConflicts } from '../utils/errors.js';
 import { fetchDoc, extractSections, truncateDoc } from '../utils/docs.js';
 export function registerEnhancedWebSocketTools(server) {
-    server.tool('transactionSubscribe', 'BEST FOR: real-time transaction streaming for live UI updates (WebSocket). PREFER createWebhook for fire-and-forget server-to-server notifications. PREFER laserstreamSubscribe for lowest-latency production streaming. Get Enhanced WebSocket config for real-time Solana transaction streaming. Filter by accounts, vote/failed txns, or signatures. Up to 50,000 addresses per filter. Business+ plans only. Returns connection config and code example. Data streaming cost: 3 credits per 0.1 MB received.', {
+    server.tool('transactionSubscribe', 'BEST FOR: real-time transaction streaming for live UI updates (WebSocket). PREFER createWebhook for fire-and-forget server-to-server notifications. PREFER laserstreamSubscribe for lowest-latency production streaming. Get Enhanced WebSocket config for real-time Solana transaction streaming. Filter by accounts, vote/failed txns, or signatures. Up to 50,000 addresses per filter. Developer+ plans only. Returns connection config and code example. Data streaming cost: 2 credits per 0.1 MB received.', {
         vote: z.boolean().optional().describe('Include vote transactions'),
         failed: z.boolean().optional().describe('Include failed transactions'),
         signature: z.string().optional().describe('Transaction signature (base58 encoded, 86-88 characters) to filter to'),
-        accountInclude: z.array(z.string()).optional().describe('Accounts to include (base58 encoded, up to 50,000, OR logic)'),
-        accountExclude: z.array(z.string()).optional().describe('Accounts to exclude (base58 encoded)'),
-        accountRequired: z.array(z.string()).optional().describe('Accounts required (base58 encoded, AND logic)'),
-        commitment: z.string().optional().default('confirmed'),
-        encoding: z.string().optional().default('jsonParsed'),
-        transactionDetails: z.string().optional().default('full'),
-        showRewards: z.boolean().optional().default(false),
-        maxSupportedTransactionVersion: z.number().optional().default(0)
+        accountInclude: z.array(z.string()).optional().describe('Accounts to include in filter (base58 encoded, up to 50,000). OR logic: tx matches if it involves ANY of these accounts. Use accountRequired for AND logic.'),
+        accountExclude: z.array(z.string()).optional().describe('Accounts to exclude from results (base58 encoded). Transactions involving ANY of these accounts are filtered out, even if they match accountInclude.'),
+        accountRequired: z.array(z.string()).optional().describe('Accounts required in every matched transaction (base58 encoded). AND logic: tx must involve ALL of these accounts. Use accountInclude for OR logic.'),
+        commitment: z.string().optional().default('confirmed').describe('Commitment level for transaction confirmation. Values: "processed", "confirmed" (default), "finalized"'),
+        encoding: z.string().optional().default('jsonParsed').describe('Response encoding format. Values: "base58", "base64", "jsonParsed" (default — recommended, returns decoded instruction data)'),
+        transactionDetails: z.string().optional().default('full').describe('Level of transaction detail in response. Values: "full" (default — complete data), "signatures" (just sigs), "accounts" (account keys only), "none"'),
+        showRewards: z.boolean().optional().default(false).describe('Include block rewards in transaction results (default: false)'),
+        maxSupportedTransactionVersion: z.number().optional().default(0).describe('Max transaction version to return. Defaults to 0, which includes versioned transactions (v0).')
     }, async (params) => {
         let err;
         err = validateEnum(params.commitment, ['processed', 'confirmed', 'finalized'], 'Transaction Subscribe Error', 'commitment');
@@ -94,10 +94,10 @@ export function registerEnhancedWebSocketTools(server) {
             return handleToolError(err, 'Error');
         }
     });
-    server.tool('accountSubscribe', 'BEST FOR: real-time account change monitoring for live UI updates (WebSocket). PREFER createWebhook for fire-and-forget notifications on account changes. PREFER laserstreamSubscribe for lowest-latency production streaming. Get Enhanced WebSocket config for real-time Solana account monitoring. Track balance changes and data updates. Business+ plans only. Returns connection config and code example. Data streaming cost: 3 credits per 0.1 MB received.', {
+    server.tool('accountSubscribe', 'BEST FOR: real-time account change monitoring for live UI updates (WebSocket). PREFER createWebhook for fire-and-forget notifications on account changes. PREFER laserstreamSubscribe for lowest-latency production streaming. Get Enhanced WebSocket config for real-time Solana account monitoring. Track balance changes and data updates. Developer+ plans only. Returns connection config and code example. Data streaming cost: 2 credits per 0.1 MB received.', {
         account: z.string().describe('Account address (base58 encoded)'),
-        encoding: z.string().optional().default('base58'),
-        commitment: z.string().optional().default('finalized')
+        encoding: z.string().optional().default('base58').describe('Account data encoding format. Values: "base58" (default), "base64", "base64+zstd" (compressed), "jsonParsed" (decoded if known program)'),
+        commitment: z.string().optional().default('finalized').describe('Commitment level for change notifications. Values: "processed", "confirmed", "finalized" (default — most reliable)')
     }, async ({ account, encoding, commitment }) => {
         let err;
         err = validateEnum(encoding, ['base58', 'base64', 'base64+zstd', 'jsonParsed'], 'Account Subscribe Error', 'encoding');
@@ -152,7 +152,7 @@ export function registerEnhancedWebSocketTools(server) {
         catch {
             return mcpError('Could not fetch live Enhanced WebSocket documentation. Try:\n' +
                 '- `lookupHeliusDocs({ topic: \'enhanced-websockets\' })` for full documentation\n' +
-                '- Visit https://www.helius.dev/docs/enhanced-websockets directly');
+                '- Visit https://www.helius.dev/docs/enhanced-websockets directly', { type: 'API', code: 'FETCH_FAILED', retryable: true, recovery: 'Try lookupHeliusDocs({ topic: "enhanced-websockets" }) or visit https://www.helius.dev/docs/enhanced-websockets directly' });
         }
         const capabilities = extractSections(content, ['capabilities', 'features'], { includeLooseMatches: false });
         const subscriptions = extractSections(content, ['subscriptions', 'endpoints'], { includeLooseMatches: false });

package/dist/tools/fees.js

@@ -6,7 +6,7 @@ export function registerFeeTools(server) {
     // Get Priority Fee Estimate
     server.tool('getPriorityFeeEstimate', 'BEST FOR: determining optimal priority fees before sending a transaction. Get optimal priority fee estimates for Solana transactions. Returns recommended fees in microlamports for different priority levels (Min, Low, Medium, High, VeryHigh, UnsafeMax). Essential for ensuring transaction confirmation during network congestion. Credit cost: 1 credit (Priority Fee API).', {
         accountKeys: z.array(z.string()).optional().describe('Account addresses (base58 encoded) involved in transaction for more accurate estimates'),
-        priorityLevel: z.string().optional().describe('Desired priority level'),
+        priorityLevel: z.string().optional().describe('Desired priority level. Values: "Min", "Low", "Medium", "High", "VeryHigh", "UnsafeMax". Returns the estimated fee in microlamports/compute unit for that level. Used when includeAllLevels is false.'),
         includeAllLevels: z.boolean().optional().default(true).describe('Return fees for all priority levels')
     }, async ({ accountKeys, priorityLevel, includeAllLevels }) => {
         if (!hasApiKey())
@@ -31,8 +31,8 @@ export function registerFeeTools(server) {
             const lines = ['**Priority Fee Estimate**', ''];
             if (result.priorityFeeLevels) {
                 const levels = result.priorityFeeLevels;
-                lines.push('| Level | Fee (microlamports) |');
-                lines.push('|-------|-------------------|');
+                lines.push('| Level | Fee (microlamports/CU) |');
+                lines.push('|-------|------------------------|');
                 lines.push(`| Min | ${levels.min.toLocaleString()} |`);
                 lines.push(`| Low | ${levels.low.toLocaleString()} |`);
                 lines.push(`| Medium | ${levels.medium.toLocaleString()} |`);

package/dist/tools/index.d.ts

@@ -1,2 +1,2 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export declare function registerTools(server: McpServer): void;

package/dist/tools/index.js

@@ -1,82 +1,4 @@
-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';
-import { registerAssetTools } from './assets.js';
-import { registerAccountTools } from './accounts.js';
-import { registerFeeTools } from './fees.js';
-import { registerNetworkTools } from './network.js';
-import { registerBlockTools } from './blocks.js';
-import { registerTokenTools } from './tokens.js';
-import { registerDasExtraTools } from './das-extras.js';
-import { registerWebhookTools } from './webhooks.js';
-import { registerEnhancedWebSocketTools } from './enhanced-websockets.js';
-import { registerLaserstreamTools } from './laserstream.js';
-import { registerWalletTools } from './wallet.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);
-    };
-}
+import { registerRouterTools } from '../router/register.js';
 export function registerTools(server) {
-    patchToolWithFeedback(server);
-    registerAuthTools(server);
-    registerConfigTools(server);
-    registerPlanTools(server);
-    registerBalanceTools(server);
-    registerTransactionTools(server);
-    registerAssetTools(server);
-    registerAccountTools(server);
-    registerFeeTools(server);
-    registerNetworkTools(server);
-    registerBlockTools(server);
-    registerTokenTools(server);
-    registerDasExtraTools(server);
-    registerWebhookTools(server);
-    registerEnhancedWebSocketTools(server);
-    registerLaserstreamTools(server);
-    registerWalletTools(server);
-    registerDocsTools(server);
-    registerGuideTools(server);
-    registerRecommendTools(server);
-    registerSolanaKnowledgeTools(server);
-    registerTransferTools(server);
+    registerRouterTools(server);
 }

package/dist/tools/laserstream.js

@@ -1,25 +1,28 @@
 import { z } from 'zod';
-import { getLaserstreamUrl, getNetwork } from '../utils/helius.js';
+import { getLaserstreamUrl, getNetwork, hasApiKey } from '../utils/helius.js';
 import { mcpText, mcpError, validateEnum, handleToolError, warnInvalidAddresses, warnAddressConflicts } from '../utils/errors.js';
+import { noApiKeyResponse } from './shared.js';
 import { fetchDoc, extractSections, truncateDoc } from '../utils/docs.js';
 export function registerLaserstreamTools(server) {
-    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(),
+    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. Business+ plan for mainnet. Returns connection config and code example.', {
+        region: z.string().optional().default('ewr').describe('Closest gRPC region for lowest latency. Values: "ewr" (default, Newark), "pitt" (Pittsburgh), "slc" (Salt Lake City), "lax" (Los Angeles), "lon" (London), "ams" (Amsterdam), "fra" (Frankfurt), "tyo" (Tokyo), "sgp" (Singapore)'),
+        commitment: z.string().optional().describe('Commitment level filter. Values: "processed", "confirmed", "finalized". Used with filterByCommitment to limit slot/block updates to a specific level.'),
+        subscribeSlots: z.boolean().optional().describe('Subscribe to slot updates (notifications on each new slot the validator processes)'),
+        filterByCommitment: z.boolean().optional().describe('When true, only emit slot updates matching the specified commitment level. Requires commitment to be set.'),
         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 (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(),
+        subscribeTransactions: z.boolean().optional().describe('Subscribe to all transactions. Produces very high volume without account filters — prefer using transactionAccountInclude or transactionAccountRequired.'),
+        transactionAccountInclude: z.array(z.string()).optional().describe('Accounts to include in filter (base58 encoded). OR logic: tx matches if it involves ANY of these accounts. Use transactionAccountRequired for AND logic.'),
+        transactionAccountExclude: z.array(z.string()).optional().describe('Accounts to exclude from results (base58 encoded). Transactions involving ANY of these accounts are filtered out, even if they match transactionAccountInclude.'),
+        transactionAccountRequired: z.array(z.string()).optional().describe('Accounts required in every matched transaction (base58 encoded). AND logic: tx must involve ALL of these accounts. Use transactionAccountInclude for OR logic.'),
+        subscribeBlocks: z.boolean().optional().describe('Subscribe to full block data (includes all transactions in each block)'),
+        subscribeBlocksMeta: z.boolean().optional().describe('Subscribe to block metadata only (slot, blockhash, rewards — without full transaction data)'),
+        subscribeEntries: z.boolean().optional().describe('Subscribe to ledger entries (shred-level data — the lowest-level stream available)'),
         fromSlot: z.string().optional().describe('Starting slot for 24h historical replay'),
-        keepalive: z.boolean().optional().default(true)
+        keepalive: z.boolean().optional().default(true).describe('Send gRPC keepalive pings to maintain the connection (default: true). Set to false only if your client handles its own keepalive.')
     }, async (params) => {
+        if (!hasApiKey())
+            return noApiKeyResponse();
         let err;
         err = validateEnum(params.region, ['ewr', 'pitt', 'slc', 'lax', 'lon', 'ams', 'fra', 'tyo', 'sgp'], 'Laserstream Error', 'region');
         if (err)
@@ -33,7 +36,7 @@ export function registerLaserstreamTools(server) {
         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.`);
+                return mcpError(`**Laserstream Error**\n\nInvalid fromSlot "${params.fromSlot}". Must be a non-negative integer slot number.`, { type: 'VALIDATION', code: 'INVALID_PARAM', retryable: false, recovery: 'Provide a non-negative integer slot number for fromSlot.' });
             }
         }
         // Check that at least one subscription type is selected
@@ -132,13 +135,7 @@ export function registerLaserstreamTools(server) {
         }
     });
     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 {
-            endpoint = getLaserstreamUrl();
-        }
-        catch (err) {
-            return handleToolError(err, 'Laserstream Error');
-        }
+        const endpoint = getLaserstreamUrl();
         let content;
         try {
             content = await fetchDoc('laserstream');
@@ -146,7 +143,7 @@ export function registerLaserstreamTools(server) {
         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');
+                '- Visit https://www.helius.dev/docs/laserstream/grpc directly', { type: 'API', code: 'FETCH_FAILED', retryable: true, recovery: 'Try lookupHeliusDocs({ topic: "laserstream" }) or 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 });

package/dist/tools/network.js

@@ -1,9 +1,12 @@
+import { z } from 'zod';
 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', 'BEST FOR: quick Solana network health check — epoch, slot, TPS, supply, version. Get current Solana network status including epoch info (current epoch, slot, progress), current TPS (transactions per second), total SOL supply, cluster version, and current block height. No parameters needed — gives a quick overview of blockchain health and state. Credit cost: 4 credits (4 standard RPC calls).', {}, async () => {
+    server.tool('getNetworkStatus', 'BEST FOR: quick Solana network health check — epoch, slot, TPS, supply, version. Get current Solana network status including epoch info (current epoch, slot, progress), current TPS (transactions per second), total SOL supply, cluster version, and current block height. Optionally pass "samples" to control the TPS averaging window (each sample ≈ 60s; default 4 ≈ 4 min, max 720 ≈ 12 hours). Credit cost: 4 credits (4 standard RPC calls).', {
+        samples: z.number().optional().default(4).describe('Number of recent performance samples for TPS calculation (each sample ≈ 60s). Default 4 (~4 min). Max 720 (~12 hours).'),
+    }, async ({ samples }) => {
         if (!hasApiKey())
             return noApiKeyResponse();
         try {
@@ -14,7 +17,7 @@ export function registerNetworkTools(server) {
                 helius.getEpochInfo(),
                 helius.getSupply(),
                 helius.getVersion(),
-                helius.getRecentPerformanceSamples(4),
+                helius.getRecentPerformanceSamples(Math.max(1, Math.min(samples, 720))),
             ]);
             const lines = ['**Solana Network Status**', ''];
             // Epoch info — all fields are bigint from Kit
@@ -36,7 +39,7 @@ export function registerNetworkTools(server) {
                 }
                 lines.push('');
             }
-            // TPS — averaged from 4 recent performance samples (~60s each, ~4 min window)
+            // TPS — averaged from recent performance samples (~60s each)
             // numTransactions includes vote + non-vote; numNonVoteTransactions is real user TPS
             if (Array.isArray(perfSamples) && perfSamples.length > 0) {
                 let totalTx = 0;
@@ -56,7 +59,10 @@ export function registerNetworkTools(server) {
                 }
                 if (totalSeconds > 0) {
                     const totalTps = Math.round(totalTx / totalSeconds);
-                    lines.push('**TPS (avg. last ~4 min):**');
+                    const window = totalSeconds >= 3600
+                        ? `~${(totalSeconds / 3600).toFixed(1)} hr`
+                        : `~${Math.round(totalSeconds / 60)} min`;
+                    lines.push(`**TPS (avg. last ${window}):**`);
                     if (hasNonVoteData) {
                         const nonVoteTps = Math.round(totalNonVoteTx / totalSeconds);
                         lines.push(`- Real (non-vote): ~${nonVoteTps.toLocaleString()} tx/sec`);

package/dist/tools/plans.d.ts

@@ -14,10 +14,5 @@ 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;