helius-mcp 0.5.3 → 1.2.0

package/dist/tools/enhanced-websockets.js

@@ -1,19 +1,54 @@
 import { z } from 'zod';
 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', '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.', {
+    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.', {
         vote: z.boolean().optional().describe('Include vote transactions'),
         failed: z.boolean().optional().describe('Include failed transactions'),
-        signature: z.string().optional().describe('Filter to specific signature'),
-        accountInclude: z.array(z.string()).optional().describe('Accounts to include (OR logic)'),
-        accountExclude: z.array(z.string()).optional().describe('Accounts to exclude'),
-        accountRequired: z.array(z.string()).optional().describe('Accounts required (AND logic)'),
-        commitment: z.enum(['processed', 'confirmed', 'finalized']).optional().default('confirmed'),
-        encoding: z.enum(['base58', 'base64', 'jsonParsed']).optional().default('jsonParsed'),
-        transactionDetails: z.enum(['full', 'signatures', 'accounts', 'none']).optional().default('full'),
+        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)
     }, async (params) => {
+        let err;
+        err = validateEnum(params.commitment, ['processed', 'confirmed', 'finalized'], 'Transaction Subscribe Error', 'commitment');
+        if (err)
+            return err;
+        err = validateEnum(params.encoding, ['base58', 'base64', 'jsonParsed'], 'Transaction Subscribe Error', 'encoding');
+        if (err)
+            return err;
+        err = validateEnum(params.transactionDetails, ['full', 'signatures', 'accounts', 'none'], 'Transaction Subscribe Error', 'transactionDetails');
+        if (err)
+            return err;
+        // Collect warnings for config issues that would fail at runtime
+        const warnings = [];
+        const addressArrays = [
+            ['accountInclude', params.accountInclude],
+            ['accountExclude', params.accountExclude],
+            ['accountRequired', params.accountRequired],
+        ];
+        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('accountInclude', params.accountInclude, 'accountExclude', params.accountExclude);
+        if (conflict)
+            warnings.push(conflict);
+        if (!params.accountInclude && !params.accountExclude && !params.accountRequired && !params.signature) {
+            warnings.push('No account filters or signature specified. This will stream ALL transactions on the network, which produces very high volume. Consider adding filters to reduce traffic.');
+        }
         try {
             const wsUrl = getEnhancedWebSocketUrl();
             const filter = {};
@@ -46,38 +81,36 @@ export function registerEnhancedWebSocketTools(server) {
                 '',
                 `**URL:** \`${wsUrl}\``,
                 '',
-                '**Subscription Request:**',
-                '```json',
-                JSON.stringify(subscriptionRequest, null, 2),
-                '```',
-                '',
-                '**Example Code:**',
-                '```typescript',
-                `const ws = new WebSocket('${wsUrl}');`,
-                'ws.on("open", () => {',
-                '  ws.send(JSON.stringify(' + JSON.stringify(subscriptionRequest) + '));',
-                '  setInterval(() => ws.ping(), 30000);',
-                '});',
-                'ws.on("message", (data) => {',
-                '  const msg = JSON.parse(data.toString());',
-                '  if (msg.method === "transactionNotification") {',
-                '    console.log("Transaction:", msg.params);',
-                '  }',
-                '});',
-                '```',
             ];
-            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('**Subscription Request:**', '```json', JSON.stringify(subscriptionRequest, null, 2), '```', '', '**Example Code:**', '```typescript', `const ws = new WebSocket('${wsUrl}');`, 'ws.on("open", () => {', '  ws.send(JSON.stringify(' + JSON.stringify(subscriptionRequest) + '));', '  setInterval(() => ws.ping(), 30000);', '});', 'ws.on("message", (data) => {', '  const msg = JSON.parse(data.toString());', '  if (msg.method === "transactionNotification") {', '    console.log("Transaction:", msg.params);', '  }', '});', '```');
+            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('accountSubscribe', '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.', {
-        account: z.string().describe('Account public key (base58)'),
-        encoding: z.enum(['base58', 'base64', 'base64+zstd', 'jsonParsed']).optional().default('base58'),
-        commitment: z.enum(['finalized', 'confirmed', 'processed']).optional().default('finalized')
+    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.', {
+        account: z.string().describe('Account address (base58 encoded)'),
+        encoding: z.string().optional().default('base58'),
+        commitment: z.string().optional().default('finalized')
     }, async ({ account, encoding, commitment }) => {
+        let err;
+        err = validateEnum(encoding, ['base58', 'base64', 'base64+zstd', 'jsonParsed'], 'Account Subscribe Error', 'encoding');
+        if (err)
+            return err;
+        err = validateEnum(commitment, ['finalized', 'confirmed', 'processed'], 'Account Subscribe Error', 'commitment');
+        if (err)
+            return err;
+        // Collect warnings for config issues that would fail at runtime
+        const warnings = [];
+        const addrWarning = warnInvalidAddress('account', account);
+        if (addrWarning)
+            warnings.push(addrWarning);
         try {
             const wsUrl = getEnhancedWebSocketUrl();
             const subscriptionRequest = {
@@ -91,54 +124,51 @@ export function registerEnhancedWebSocketTools(server) {
                 `**Account:** \`${account}\``,
                 `**URL:** \`${wsUrl}\``,
                 '',
-                '**Subscription Request:**',
-                '```json',
-                JSON.stringify(subscriptionRequest, null, 2),
-                '```',
-                '',
-                '**Example Code:**',
-                '```typescript',
-                `const ws = new WebSocket('${wsUrl}');`,
-                'ws.on("open", () => {',
-                '  ws.send(JSON.stringify(' + JSON.stringify(subscriptionRequest) + '));',
-                '  setInterval(() => ws.ping(), 30000);',
-                '});',
-                'ws.on("message", (data) => {',
-                '  const msg = JSON.parse(data.toString());',
-                '  if (msg.method === "accountNotification") {',
-                '    console.log("Account updated:", msg.params.result.value);',
-                '  }',
-                '});',
-                '```',
             ];
-            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('**Subscription Request:**', '```json', JSON.stringify(subscriptionRequest, null, 2), '```', '', '**Example Code:**', '```typescript', `const ws = new WebSocket('${wsUrl}');`, 'ws.on("open", () => {', '  ws.send(JSON.stringify(' + JSON.stringify(subscriptionRequest) + '));', '  setInterval(() => ws.ping(), 30000);', '});', 'ws.on("message", (data) => {', '  const msg = JSON.parse(data.toString());', '  if (msg.method === "accountNotification") {', '    console.log("Account updated:", msg.params.result.value);', '  }', '});', '```');
+            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('getEnhancedWebSocketInfo', 'Get Helius Enhanced WebSocket capabilities, endpoints, and plan requirements. 1.5-2x faster than standard WebSockets.', {}, async () => {
+    server.tool('getEnhancedWebSocketInfo', 'Get Helius Enhanced WebSocket capabilities, endpoints, and plan requirements. 1.5-2x faster than standard WebSockets. Fetches live from official documentation.', {}, async () => {
+        let wsUrl;
         try {
-            const wsUrl = getEnhancedWebSocketUrl();
-            const lines = [
-                '**Helius Enhanced WebSocket Service**',
-                '',
-                `**Endpoint:** \`${wsUrl}\``,
-                '',
-                '**Subscriptions:** transactionSubscribe, accountSubscribe',
-                '**Speed:** 1.5-2x faster than standard WebSockets',
-                '**Filtering:** Up to 50,000 addresses per filter',
-                '**Plans:** Business or Professional tier',
-                '**Timeout:** 10 min inactivity, ping every 30-60s',
-                '',
-                '**Docs:** https://www.helius.dev/docs/enhanced-websockets',
-            ];
-            return { content: [{ type: 'text', text: lines.join('\n') }] };
+            wsUrl = getEnhancedWebSocketUrl();
         }
         catch (err) {
-            const errorMsg = err instanceof Error ? err.message : String(err);
-            return { content: [{ type: 'text', text: `Error: ${errorMsg}` }], isError: true };
+            return handleToolError(err, 'Enhanced WebSocket Error');
+        }
+        let content;
+        try {
+            content = await fetchDoc('enhanced-websockets');
+        }
+        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');
         }
+        const capabilities = extractSections(content, ['capabilities', 'features'], { includeLooseMatches: false });
+        const subscriptions = extractSections(content, ['subscriptions', 'endpoints'], { includeLooseMatches: false });
+        const plans = extractSections(content, ['plan requirements', 'plans'], { includeLooseMatches: false });
+        const sections = [capabilities, subscriptions, plans].filter(Boolean).join('\n\n');
+        const body = sections || truncateDoc(content);
+        const result = [
+            '# Helius Enhanced WebSockets (Official)',
+            '',
+            `**Endpoint:** \`${wsUrl}\``,
+            '',
+            body,
+            '',
+            '---',
+            'Source: https://www.helius.dev/docs/enhanced-websockets (fetched live)',
+        ].join('\n');
+        return mcpText(result);
     });
 }

package/dist/tools/fees.js

@@ -1,74 +1,55 @@
 import { z } from 'zod';
-import { hasApiKey, getRpcUrl } from '../utils/helius.js';
+import { getHeliusClient, hasApiKey } from '../utils/helius.js';
 import { noApiKeyResponse } from './shared.js';
+import { mcpText, validateEnum, handleToolError } from '../utils/errors.js';
 export function registerFeeTools(server) {
     // Get Priority Fee Estimate
-    server.tool('getPriorityFeeEstimate', '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.', {
-        accountKeys: z.array(z.string()).optional().describe('Account addresses involved in transaction for more accurate estimates'),
-        priorityLevel: z.enum(['Min', 'Low', 'Medium', 'High', 'VeryHigh', 'UnsafeMax']).optional().describe('Desired priority level'),
+    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'),
         includeAllLevels: z.boolean().optional().default(true).describe('Return fees for all priority levels')
     }, async ({ accountKeys, priorityLevel, includeAllLevels }) => {
         if (!hasApiKey())
             return noApiKeyResponse();
-        const url = getRpcUrl();
-        const requestBody = {
-            jsonrpc: '2.0',
-            id: 'priority-fee-estimate',
-            method: 'getPriorityFeeEstimate',
-            params: [{
-                    ...(accountKeys && { accountKeys }),
-                    options: {
-                        ...(priorityLevel && { priorityLevel }),
-                        includeAllPriorityFeeLevels: includeAllLevels
-                    }
-                }]
-        };
-        const response = await fetch(url, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify(requestBody)
-        });
-        const data = await response.json();
-        if (data.error) {
-            return {
-                content: [{
-                        type: 'text',
-                        text: `**Priority Fee Estimate Error**\n\n${data.error.message}`
-                    }]
-            };
+        if (priorityLevel) {
+            const err = validateEnum(priorityLevel, ['Min', 'Low', 'Medium', 'High', 'VeryHigh', 'UnsafeMax'], 'Priority Fee Estimate', 'priority level');
+            if (err)
+                return err;
         }
-        const result = data.result;
-        if (!result) {
-            return {
-                content: [{
-                        type: 'text',
-                        text: `**Priority Fee Estimate**\n\nNo fee data available.`
-                    }]
-            };
+        try {
+            const helius = getHeliusClient();
+            const result = await helius.getPriorityFeeEstimate({
+                ...(accountKeys && { accountKeys }),
+                options: {
+                    ...(priorityLevel && { priorityLevel: priorityLevel }),
+                    includeAllPriorityFeeLevels: includeAllLevels
+                }
+            });
+            if (!result) {
+                return mcpText(`**Priority Fee Estimate**\n\nNo fee data available.`);
+            }
+            const lines = ['**Priority Fee Estimate**', ''];
+            if (result.priorityFeeLevels) {
+                const levels = result.priorityFeeLevels;
+                lines.push('| Level | Fee (microlamports) |');
+                lines.push('|-------|-------------------|');
+                lines.push(`| Min | ${levels.min.toLocaleString()} |`);
+                lines.push(`| Low | ${levels.low.toLocaleString()} |`);
+                lines.push(`| Medium | ${levels.medium.toLocaleString()} |`);
+                lines.push(`| High | ${levels.high.toLocaleString()} |`);
+                lines.push(`| Very High | ${levels.veryHigh.toLocaleString()} |`);
+                lines.push(`| Unsafe Max | ${levels.unsafeMax.toLocaleString()} |`);
+            }
+            else if (result.priorityFeeEstimate !== undefined) {
+                lines.push(`**Estimated Fee:** ${result.priorityFeeEstimate.toLocaleString()} microlamports`);
+            }
+            if (accountKeys && accountKeys.length > 0) {
+                lines.push('', `*Estimate based on ${accountKeys.length} account(s)*`);
+            }
+            return mcpText(lines.join('\n'));
         }
-        const lines = ['**Priority Fee Estimate**', ''];
-        if (result.priorityFeeLevels) {
-            const levels = result.priorityFeeLevels;
-            lines.push('| Level | Fee (microlamports) |');
-            lines.push('|-------|-------------------|');
-            lines.push(`| Min | ${levels.min.toLocaleString()} |`);
-            lines.push(`| Low | ${levels.low.toLocaleString()} |`);
-            lines.push(`| Medium | ${levels.medium.toLocaleString()} |`);
-            lines.push(`| High | ${levels.high.toLocaleString()} |`);
-            lines.push(`| Very High | ${levels.veryHigh.toLocaleString()} |`);
-            lines.push(`| Unsafe Max | ${levels.unsafeMax.toLocaleString()} |`);
+        catch (err) {
+            return handleToolError(err, 'Error fetching priority fee estimate');
         }
-        else if (result.priorityFeeEstimate !== undefined) {
-            lines.push(`**Estimated Fee:** ${result.priorityFeeEstimate.toLocaleString()} microlamports`);
-        }
-        if (accountKeys && accountKeys.length > 0) {
-            lines.push('', `*Estimate based on ${accountKeys.length} account(s)*`);
-        }
-        return {
-            content: [{
-                    type: 'text',
-                    text: lines.join('\n')
-                }]
-        };
     });
 }