helius-mcp 0.5.3 → 1.2.0

package/dist/tools/accounts.js

@@ -1,7 +1,8 @@
 import { z } from 'zod';
-import { getHeliusClient, hasApiKey, getRpcUrl } from '../utils/helius.js';
+import { getHeliusClient, hasApiKey } from '../utils/helius.js';
 import { formatAddress, formatSol } from '../utils/formatters.js';
 import { noApiKeyResponse } from './shared.js';
+import { mcpText, validateEnum, handleToolError, addressError, paginationError } from '../utils/errors.js';
 function formatParsedAccountData(account) {
     const lines = [];
     const parsedData = account.data;
@@ -20,145 +21,88 @@ function formatParsedAccountData(account) {
     return lines;
 }
 export function registerAccountTools(server) {
-    // Get Account Info (single or batch) — uses direct JSON-RPC
-    server.tool('getAccountInfo', 'Get detailed Solana account information for one or more accounts. For a single account: returns owner program, lamport balance, data size, executable status, and rent epoch. For batch: pass up to 100 addresses in "addresses" for fast bulk lookups. Use jsonParsed encoding (default) on token mint addresses to see Token-2022 extensions, authorities, and supply data. Use this to inspect any on-chain account.', {
+    // Get Account Info (single or batch) — uses SDK standard Solana RPC (Kit, bigint)
+    server.tool('getAccountInfo', 'BEST FOR: raw on-chain account inspection (owner program, data size, executable status, Token-2022 extensions). PREFER getAsset for token/NFT metadata. PREFER getBalance for SOL balance. Get detailed Solana account information for one or more accounts. For a single account: returns owner program, lamport balance, data size, executable status, and rent epoch. For batch: pass up to 100 addresses in "addresses" for fast bulk lookups. Use jsonParsed encoding (default) on token mint addresses to see Token-2022 extensions, authorities, and supply data. Use this to inspect any on-chain account. Credit cost: 1 credit (standard RPC).', {
         address: z.string().optional().describe('Single account address (base58 encoded). Use this OR addresses, not both.'),
-        addresses: z.array(z.string()).optional().describe('Array of account addresses for batch lookup (up to 100). Use this OR address, not both.'),
-        encoding: z.enum(['base58', 'base64', 'jsonParsed']).optional().default('jsonParsed').describe('Data encoding format')
+        addresses: z.array(z.string()).optional().describe('Array of account addresses for batch lookup (base58 encoded, up to 100). Use this OR address, not both.'),
+        encoding: z.string().optional().default('jsonParsed').describe('Data encoding format')
     }, async ({ address, addresses, encoding }) => {
         if (!hasApiKey())
             return noApiKeyResponse();
-        const url = getRpcUrl();
+        const err = validateEnum(encoding, ['base58', 'base64', 'jsonParsed'], 'Account Info Error', 'encoding');
+        if (err)
+            return err;
         // Validate: must provide exactly one of address or addresses
         if (!address && (!addresses || addresses.length === 0)) {
-            return {
-                content: [{
-                        type: 'text',
-                        text: `**Error:** Provide either \`address\` (single account) or \`addresses\` (batch of up to 100).`
-                    }]
-            };
+            return mcpText(`**Error:** Provide either \`address\` (single account) or \`addresses\` (batch of up to 100).`);
         }
         if (address && addresses && addresses.length > 0) {
-            return {
-                content: [{
-                        type: 'text',
-                        text: `**Error:** Provide either \`address\` or \`addresses\`, not both.`
-                    }]
-            };
+            return mcpText(`**Error:** Provide either \`address\` or \`addresses\`, not both.`);
         }
-        // --- Batch mode ---
-        if (addresses && addresses.length > 0) {
-            if (addresses.length > 100) {
-                return {
-                    content: [{
-                            type: 'text',
-                            text: `**Error:** Maximum 100 accounts per request. You provided ${addresses.length}.`
-                        }]
-                };
-            }
-            const response = await fetch(url, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({
-                    jsonrpc: '2.0',
-                    id: 'get-multiple-accounts',
-                    method: 'getMultipleAccounts',
-                    params: [addresses, { encoding }]
-                })
-            });
-            const data = await response.json();
-            if (data.error) {
-                return {
-                    content: [{
-                            type: 'text',
-                            text: `**Error**\n\n${data.error.message}`
-                        }]
-                };
-            }
-            const accounts = data.result?.value || [];
-            const lines = [`**Multiple Accounts** (${addresses.length} requested)`, ''];
-            addresses.forEach((addr, i) => {
-                const account = accounts[i];
-                if (!account) {
-                    lines.push(`**${formatAddress(addr)}:** Not found`);
+        try {
+            const helius = getHeliusClient();
+            // --- Batch mode ---
+            if (addresses && addresses.length > 0) {
+                if (addresses.length > 100) {
+                    return mcpText(`**Error:** Maximum 100 accounts per request. You provided ${addresses.length}.`);
                 }
-                else {
-                    lines.push(`**${formatAddress(addr)}**`);
-                    lines.push(`  Balance: ${formatSol(account.lamports)}`);
-                    lines.push(`  Owner: ${account.owner}`);
-                    lines.push(`  Executable: ${account.executable ? 'Yes' : 'No'}`);
-                    if (account.space !== undefined) {
-                        lines.push(`  Data Size: ${account.space} bytes`);
+                const result = await helius.getMultipleAccounts(addresses, { encoding });
+                const accounts = result?.value || [];
+                const lines = [`**Multiple Accounts** (${addresses.length} requested)`, ''];
+                addresses.forEach((addr, i) => {
+                    const account = accounts[i];
+                    if (!account) {
+                        lines.push(`**${formatAddress(addr)}:** Not found`);
                     }
-                    // Show parsed data (Token-2022 extensions, mint info, etc.)
-                    const parsedLines = formatParsedAccountData(account);
-                    lines.push(...parsedLines);
-                }
-                lines.push('');
-            });
-            return {
-                content: [{
-                        type: 'text',
-                        text: lines.join('\n')
-                    }]
-            };
-        }
-        // --- Single account mode ---
-        const response = await fetch(url, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({
-                jsonrpc: '2.0',
-                id: 'get-account-info',
-                method: 'getAccountInfo',
-                params: [address, { encoding }]
-            })
-        });
-        const data = await response.json();
-        if (data.error) {
-            return {
-                content: [{
-                        type: 'text',
-                        text: `**Error**\n\n${data.error.message}`
-                    }]
-            };
-        }
-        const account = data.result?.value;
-        if (!account) {
-            return {
-                content: [{
-                        type: 'text',
-                        text: `**Account ${formatAddress(address)}**\n\nAccount not found or has no data.`
-                    }]
-            };
-        }
-        const lines = [
-            `**Account ${formatAddress(address)}**`,
-            '',
-            `**Balance:** ${formatSol(account.lamports)} (${account.lamports.toLocaleString()} lamports)`,
-            `**Owner:** ${account.owner}`,
-            `**Executable:** ${account.executable ? 'Yes' : 'No'}`,
-        ];
-        if (account.space !== undefined) {
-            lines.push(`**Data Size:** ${account.space} bytes`);
+                    else {
+                        lines.push(`**${formatAddress(addr)}**`);
+                        lines.push(`  Balance: ${formatSol(Number(account.lamports))}`);
+                        lines.push(`  Owner: ${account.owner}`);
+                        lines.push(`  Executable: ${account.executable ? 'Yes' : 'No'}`);
+                        if (account.space !== undefined) {
+                            lines.push(`  Data Size: ${Number(account.space)} bytes`);
+                        }
+                        const parsedLines = formatParsedAccountData({ ...account, lamports: Number(account.lamports) });
+                        lines.push(...parsedLines);
+                    }
+                    lines.push('');
+                });
+                return mcpText(lines.join('\n'));
+            }
+            // --- Single account mode ---
+            const result = await helius.getAccountInfo(address, { encoding });
+            const account = result?.value;
+            if (!account) {
+                return mcpText(`**Account ${formatAddress(address)}**\n\nAccount not found or has no data.`);
+            }
+            const lamports = Number(account.lamports);
+            const lines = [
+                `**Account ${formatAddress(address)}**`,
+                '',
+                `**Balance:** ${formatSol(lamports)} (${lamports.toLocaleString()} lamports)`,
+                `**Owner:** ${account.owner}`,
+                `**Executable:** ${account.executable ? 'Yes' : 'No'}`,
+            ];
+            if (account.space !== undefined) {
+                lines.push(`**Data Size:** ${Number(account.space)} bytes`);
+            }
+            const parsedLines = formatParsedAccountData({ ...account, lamports });
+            if (parsedLines.length > 0) {
+                lines.push('', '**Parsed Data:**');
+                lines.push(...parsedLines);
+            }
+            return mcpText(lines.join('\n'));
         }
-        // Show parsed data details when using jsonParsed
-        const parsedLines = formatParsedAccountData(account);
-        if (parsedLines.length > 0) {
-            lines.push('', '**Parsed Data:**');
-            lines.push(...parsedLines);
+        catch (err) {
+            return handleToolError(err, 'Error fetching account info', [
+                addressError('Account Info'),
+            ]);
         }
-        return {
-            content: [{
-                    type: 'text',
-                    text: lines.join('\n')
-                }]
-        };
     });
     // Get Token Accounts
-    server.tool('getTokenAccounts', 'Query token accounts with advanced filters. Can filter by mint address, owner address, or both. Returns token account addresses and balances.', {
-        owner: z.string().optional().describe('Filter by owner wallet address'),
-        mint: z.string().optional().describe('Filter by token mint address'),
+    server.tool('getTokenAccounts', 'BEST FOR: advanced token account queries with flexible filters (by mint, owner, or both). PREFER getTokenHolders for a quick top-holders list. PREFER getTokenBalances for a wallet\'s token holdings with prices. Query token accounts with advanced filters. Can filter by mint address, owner address, or both. Returns token account addresses and balances. Credit cost: 10 credits/call (DAS API).', {
+        owner: z.string().optional().describe('Filter by owner wallet address (base58 encoded)'),
+        mint: z.string().optional().describe('Filter by token mint address (base58 encoded)'),
         page: z.number().optional().default(1).describe('Page number (starts at 1)'),
         limit: z.number().optional().default(20).describe('Results per page (max 1000)')
     }, async ({ owner, mint, page, limit }) => {
@@ -166,19 +110,23 @@ export function registerAccountTools(server) {
             return noApiKeyResponse();
         const helius = getHeliusClient();
         if (!owner && !mint) {
-            return {
-                content: [{
-                        type: 'text',
-                        text: `**Error:** You must provide at least one of: owner or mint address.`
-                    }]
-            };
+            return mcpText(`**Error:** You must provide at least one of: owner or mint address.`);
         }
         const params = { page, limit };
         if (owner)
             params.owner = owner;
         if (mint)
             params.mint = mint;
-        const response = await helius.getTokenAccounts(params);
+        let response;
+        try {
+            response = await helius.getTokenAccounts(params);
+        }
+        catch (err) {
+            return handleToolError(err, 'Error fetching token accounts', [
+                addressError('Token Accounts', 'Invalid Solana address. Please provide valid base58-encoded addresses for owner and/or mint.'),
+                paginationError('Token Accounts'),
+            ]);
+        }
         const items = (response.token_accounts || []);
         if (items.length === 0) {
             const filterDesc = owner && mint
@@ -186,12 +134,7 @@ export function registerAccountTools(server) {
                 : owner
                     ? `owner=${formatAddress(owner)}`
                     : `mint=${formatAddress(mint)}`;
-            return {
-                content: [{
-                        type: 'text',
-                        text: `**Token Accounts** (${filterDesc})\n\nNo token accounts found.`
-                    }]
-            };
+            return mcpText(`**Token Accounts** (${filterDesc})\n\nNo token accounts found.`);
         }
         const lines = [`**Token Accounts** (${response.total || items.length} total, page ${page})`, ''];
         items.forEach((account) => {
@@ -210,24 +153,22 @@ export function registerAccountTools(server) {
             }
             lines.push('');
         });
-        return {
-            content: [{
-                    type: 'text',
-                    text: lines.join('\n')
-                }]
-        };
+        return mcpText(lines.join('\n'));
     });
-    // Get Program Accounts (V2 with pagination)
-    server.tool('getProgramAccounts', 'Get all accounts owned by a specific program. Returns account addresses, balances, and data sizes. Use dataSize to filter by account data length (e.g. 165 for token accounts). Useful for finding all accounts created by a program like a DEX, lending protocol, or custom program.', {
+    // Get Program Accounts (V2 with pagination) — uses SDK RpcCaller (no bigint)
+    server.tool('getProgramAccounts', 'BEST FOR: investigating protocol state — finding DEX pools, lending positions, or all accounts created by a specific program. PREFER searchAssets for NFT/token asset searches by creator or authority. Get all accounts owned by a specific program. Returns account addresses, balances, and data sizes. Use dataSize to filter by account data length (e.g. 165 for token accounts). Useful for finding all accounts created by a program like a DEX, lending protocol, or custom program. Credit cost: 10 credits/call.', {
         programId: z.string().describe('Program ID (base58 encoded) — the owner program of the accounts to find'),
         limit: z.number().optional().default(20).describe('Maximum accounts to return (default 20, max 100)'),
-        encoding: z.enum(['base58', 'base64', 'jsonParsed']).optional().default('base64').describe('Data encoding format'),
+        encoding: z.string().optional().default('base64').describe('Data encoding format'),
         dataSize: z.number().optional().describe('Filter by exact account data size in bytes (e.g. 165 for SPL token accounts)'),
         paginationKey: z.string().optional().describe('Pagination cursor from a previous response to fetch the next page')
     }, async ({ programId, limit, encoding, dataSize, paginationKey }) => {
         if (!hasApiKey())
             return noApiKeyResponse();
-        const url = getRpcUrl();
+        const encErr = validateEnum(encoding, ['base58', 'base64', 'jsonParsed'], 'Program Accounts Error', 'encoding');
+        if (encErr)
+            return encErr;
+        const helius = getHeliusClient();
         const cappedLimit = Math.min(limit, 10_000);
         const filters = [];
         if (dataSize !== undefined) {
@@ -242,66 +183,35 @@ export function registerAccountTools(server) {
             rpcParams.filters = filters;
         if (paginationKey)
             rpcParams.paginationKey = paginationKey;
-        const requestBody = {
-            jsonrpc: '2.0',
-            id: 'get-program-accounts-v2',
-            method: 'getProgramAccountsV2',
-            params: [programId, rpcParams]
-        };
-        let data;
         try {
-            const response = await fetch(url, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify(requestBody)
+            const data = await helius.getProgramAccountsV2([programId, rpcParams]);
+            // SDK returns result directly (or may wrap in RpcResponse with context/value)
+            const result = data.value ?? data;
+            const accounts = result?.accounts || [];
+            if (accounts.length === 0) {
+                return mcpText(`**Program Accounts for ${formatAddress(programId)}**\n\nNo accounts found.`);
+            }
+            const totalLabel = result?.totalResults
+                ? `${result.totalResults.toLocaleString()} total`
+                : `${accounts.length} returned`;
+            const lines = [`**Program Accounts for ${formatAddress(programId)}** (${totalLabel})`, ''];
+            accounts.forEach((item) => {
+                lines.push(`- **${formatAddress(item.pubkey)}**`);
+                lines.push(`  Balance: ${formatSol(item.account.lamports)}`);
+                if (item.account.space !== undefined) {
+                    lines.push(`  Data Size: ${item.account.space} bytes`);
+                }
+                lines.push(`  Executable: ${item.account.executable ? 'Yes' : 'No'}`);
             });
-            data = await response.json();
+            if (result?.paginationKey) {
+                lines.push('', `**Next Page:** Pass \`paginationKey: "${result.paginationKey}"\` to fetch the next page.`);
+            }
+            return mcpText(lines.join('\n'));
         }
         catch (err) {
-            return {
-                content: [{
-                        type: 'text',
-                        text: `**Error fetching program accounts:** ${err instanceof Error ? err.message : String(err)}`
-                    }]
-            };
-        }
-        if (data.error) {
-            return {
-                content: [{
-                        type: 'text',
-                        text: `**Error**\n\n${data.error.message}`
-                    }]
-            };
-        }
-        const accounts = data.result?.accounts || [];
-        if (accounts.length === 0) {
-            return {
-                content: [{
-                        type: 'text',
-                        text: `**Program Accounts for ${formatAddress(programId)}**\n\nNo accounts found.`
-                    }]
-            };
+            return handleToolError(err, 'Error fetching program accounts', [
+                addressError('Program Accounts'),
+            ]);
         }
-        const totalLabel = data.result?.totalResults
-            ? `${data.result.totalResults.toLocaleString()} total`
-            : `${accounts.length} returned`;
-        const lines = [`**Program Accounts for ${formatAddress(programId)}** (${totalLabel})`, ''];
-        accounts.forEach((item) => {
-            lines.push(`- **${formatAddress(item.pubkey)}**`);
-            lines.push(`  Balance: ${formatSol(item.account.lamports)}`);
-            if (item.account.space !== undefined) {
-                lines.push(`  Data Size: ${item.account.space} bytes`);
-            }
-            lines.push(`  Executable: ${item.account.executable ? 'Yes' : 'No'}`);
-        });
-        if (data.result?.paginationKey) {
-            lines.push('', `**Next Page:** Pass \`paginationKey: "${data.result.paginationKey}"\` to fetch the next page.`);
-        }
-        return {
-            content: [{
-                    type: 'text',
-                    text: lines.join('\n')
-                }]
-        };
     });
 }