helius-mcp 0.5.3 → 1.2.0

package/dist/tools/assets.js

@@ -2,9 +2,10 @@ import { z } from 'zod';
 import { getHeliusClient, hasApiKey } from '../utils/helius.js';
 import { formatAddress } from '../utils/formatters.js';
 import { noApiKeyResponse } from './shared.js';
+import { mcpText, handleToolError, addressError, paginationError, notFoundError } from '../utils/errors.js';
 export function registerAssetTools(server) {
     // Get Assets by Owner (NFTs and tokens via DAS)
-    server.tool('getAssetsByOwner', 'Get all NFTs and digital assets owned by a Solana wallet using the DAS (Digital Asset Standard) API. Returns asset names, types (NFT, cNFT, Fungible, etc.), and mint addresses. Supports both regular NFTs and compressed NFTs (cNFTs). Use this to see what NFTs/collectibles a wallet owns. For fungible token balances, use getTokenBalances instead.', {
+    server.tool('getAssetsByOwner', 'BEST FOR: listing NFTs/digital assets owned by a wallet. PREFER getTokenBalances for fungible tokens, getAsset for a specific mint. Get all NFTs and digital assets owned by a wallet. Returns asset names, types, and mint addresses. Supports regular NFTs and cNFTs. Credit cost: 10 credits (DAS API).', {
         address: z.string().describe('Solana wallet address (base58 encoded)'),
         limit: z.number().optional().default(20).describe('Number of assets to return (default 20). Increase for wallets with many NFTs.'),
         page: z.number().optional().default(1).describe('Page number (starts at 1)')
@@ -12,18 +13,23 @@ export function registerAssetTools(server) {
         if (!hasApiKey())
             return noApiKeyResponse();
         const helius = getHeliusClient();
-        const response = await helius.getAssetsByOwner({
-            ownerAddress: address,
-            page,
-            limit
-        });
+        let response;
+        try {
+            response = await helius.getAssetsByOwner({
+                ownerAddress: address,
+                page,
+                limit
+            });
+        }
+        catch (err) {
+            const header = `Assets for ${formatAddress(address)}`;
+            return handleToolError(err, 'Error fetching assets', [
+                addressError(header, 'Invalid Solana address. Please provide a valid base58-encoded wallet address.'),
+                paginationError(header),
+            ]);
+        }
         if (!response.items || response.items.length === 0) {
-            return {
-                content: [{
-                        type: 'text',
-                        text: `**Assets for ${formatAddress(address)}**\n\nNo assets found.`
-                    }]
-            };
+            return mcpText(`**Assets for ${formatAddress(address)}**\n\nNo assets found.`);
         }
         const items = response.items;
         // Enrich assets missing name/symbol
@@ -51,57 +57,41 @@ export function registerAssetTools(server) {
             lines.push(`- **${name}** (${asset.interface})`);
             lines.push(`  ID: ${formatAddress(asset.id)}`);
         });
-        return {
-            content: [{
-                    type: 'text',
-                    text: lines.join('\n')
-                }]
-        };
+        return mcpText(lines.join('\n'));
     });
     // Get Asset (single or batch)
-    server.tool('getAsset', 'Get detailed information about one or more NFTs/tokens by mint address. For a single asset: returns name, symbol, description, image, owner, creators, authorities, supply, decimals, royalties, mutability. For batch: pass an array of up to 1000 mint addresses in "ids" for fast bulk lookups. Use this to find who created/deployed a token, verify token details, or get full NFT metadata.', {
+    server.tool('getAsset', 'Get detailed information about one or more NFTs/tokens by mint address. For a single asset: returns name, symbol, description, image, owner, creators, authorities, supply, decimals, royalties, mutability. For batch: pass an array of up to 1000 mint addresses in "ids" for fast bulk lookups. Use this to find who created/deployed a token, verify token details, or get full NFT metadata. DAS API (10 credits/call).', {
         id: z.string().optional().describe('Single asset mint address (base58 encoded). Use this OR ids, not both.'),
-        ids: z.array(z.string()).optional().describe('Array of asset mint addresses for batch lookup (up to 1000). Use this OR id, not both.')
+        ids: z.array(z.string()).optional().describe('Array of asset mint addresses for batch lookup (base58 encoded, up to 1000). Use this OR id, not both.')
     }, async ({ id, ids }) => {
         if (!hasApiKey())
             return noApiKeyResponse();
         const helius = getHeliusClient();
         // Validate: must provide exactly one of id or ids
         if (!id && (!ids || ids.length === 0)) {
-            return {
-                content: [{
-                        type: 'text',
-                        text: `**Error:** Provide either "id" (single asset) or "ids" (batch of up to 1000).`
-                    }]
-            };
+            return mcpText(`**Error:** Provide either "id" (single asset) or "ids" (batch of up to 1000).`);
         }
         if (id && ids && ids.length > 0) {
-            return {
-                content: [{
-                        type: 'text',
-                        text: `**Error:** Provide either "id" or "ids", not both.`
-                    }]
-            };
+            return mcpText(`**Error:** Provide either "id" or "ids", not both.`);
         }
         // --- Batch mode ---
         if (ids && ids.length > 0) {
             if (ids.length > 1000) {
-                return {
-                    content: [{
-                            type: 'text',
-                            text: `**Error:** Maximum 1000 assets per batch. You provided ${ids.length}.`
-                        }]
-                };
+                return mcpText(`**Error:** Maximum 1000 assets per batch. You provided ${ids.length}.`);
+            }
+            let assets;
+            try {
+                assets = await helius.getAssetBatch({ ids });
+            }
+            catch (err) {
+                return handleToolError(err, 'Error fetching assets', [
+                    addressError('Asset Batch Error', 'One or more provided IDs are not valid Solana addresses. Please check the mint addresses and try again.'),
+                    notFoundError('Asset Batch Results', 'One or more assets were not found. Please check the mint addresses and try again.'),
+                ]);
             }
-            const assets = await helius.getAssetBatch({ ids });
             const items = (assets || []);
             if (items.length === 0) {
-                return {
-                    content: [{
-                            type: 'text',
-                            text: `**Asset Batch Results**\n\nNo assets found.`
-                        }]
-                };
+                return mcpText(`**Asset Batch Results**\n\nNo assets found.`);
             }
             const lines = [`**Asset Batch Results** (${items.length} assets)`, ''];
             items.forEach((asset) => {
@@ -114,22 +104,22 @@ export function registerAssetTools(server) {
                     lines.push(`  Owner: ${formatAddress(asset.ownership.owner)}`);
                 }
             });
-            return {
-                content: [{
-                        type: 'text',
-                        text: lines.join('\n')
-                    }]
-            };
+            return mcpText(lines.join('\n'));
         }
         // --- Single asset mode ---
-        const asset = await helius.getAsset({ id: id });
+        let asset;
+        try {
+            asset = await helius.getAsset({ id: id });
+        }
+        catch (err) {
+            const header = `Asset ${formatAddress(id)}`;
+            return handleToolError(err, 'Error fetching asset', [
+                addressError(header, 'Invalid Solana address. Please provide a valid base58-encoded mint address.'),
+                notFoundError(header, 'Asset not found. This mint address does not exist or has not been indexed.'),
+            ]);
+        }
         if (!asset) {
-            return {
-                content: [{
-                        type: 'text',
-                        text: `Asset ${formatAddress(id)} not found.`
-                    }]
-            };
+            return mcpText(`Asset ${formatAddress(id)} not found.`);
         }
         const metadata = asset.content?.metadata;
         const tokenInfo = asset.token_info;
@@ -204,18 +194,13 @@ export function registerAssetTools(server) {
         if (flags.length > 0) {
             lines.push(`**Status:** ${flags.join(', ')}`);
         }
-        return {
-            content: [{
-                    type: 'text',
-                    text: lines.join('\n')
-                }]
-        };
+        return mcpText(lines.join('\n'));
     });
     // Search Assets — unified search with smart routing for creator/authority/general queries
-    server.tool('searchAssets', 'Advanced search for digital assets (NFTs, tokens) with multiple filters. Search by owner, creator, authority, name, compression status, burnt status, or frozen status. Also replaces getAssetsByCreator and getAssetsByAuthority — pass creatorAddress (with optional onlyVerified) to find assets by creator, or authorityAddress to find assets controlled by an authority.', {
-        ownerAddress: z.string().optional().describe('Filter by owner wallet address'),
-        creatorAddress: z.string().optional().describe('Filter by creator address'),
-        authorityAddress: z.string().optional().describe('Filter by authority address (finds assets this address has update/freeze control over)'),
+    server.tool('searchAssets', 'BEST FOR: filtered multi-criteria asset search. PREFER getAssetsByOwner for simple wallet NFT listing, getAssetsByGroup for collection browsing. Search digital assets by owner, creator, authority, name, compression, burnt, or frozen status. Also supports getAssetsByCreator and getAssetsByAuthority queries. Credit cost: 10 credits (DAS API).', {
+        ownerAddress: z.string().optional().describe('Filter by owner wallet address (base58 encoded)'),
+        creatorAddress: z.string().optional().describe('Filter by creator address (base58 encoded)'),
+        authorityAddress: z.string().optional().describe('Filter by authority address (base58 encoded, finds assets this address has update/freeze control over)'),
         onlyVerified: z.boolean().optional().default(false).describe('Only return assets where the creator is verified (used with creatorAddress)'),
         name: z.string().optional().describe('Search by asset name (partial match). Requires ownerAddress to be provided.'),
         compressed: z.boolean().optional().describe('Filter for compressed NFTs (cNFTs) only'),
@@ -231,32 +216,45 @@ export function registerAssetTools(server) {
         let headerLabel;
         // Smart routing: authority-only → getAssetsByAuthority
         if (authorityAddress && !creatorAddress && !ownerAddress && !name && compressed === undefined && burnt === undefined && frozen === undefined) {
-            response = await helius.getAssetsByAuthority({
-                authorityAddress,
-                page,
-                limit
-            });
+            try {
+                response = await helius.getAssetsByAuthority({
+                    authorityAddress,
+                    page,
+                    limit
+                });
+            }
+            catch (err) {
+                const header = `Assets by Authority ${formatAddress(authorityAddress)}`;
+                return handleToolError(err, 'Error searching assets', [
+                    addressError(header, 'Invalid Solana address. Please provide a valid base58-encoded address.'),
+                    paginationError(header),
+                ]);
+            }
             headerLabel = `Assets by Authority ${formatAddress(authorityAddress)}`;
         }
         // Smart routing: creator (with optional onlyVerified) → getAssetsByCreator
         else if (creatorAddress && !authorityAddress && !ownerAddress && !name && compressed === undefined && burnt === undefined && frozen === undefined) {
-            response = await helius.getAssetsByCreator({
-                creatorAddress,
-                onlyVerified,
-                page,
-                limit
-            });
+            try {
+                response = await helius.getAssetsByCreator({
+                    creatorAddress,
+                    onlyVerified,
+                    page,
+                    limit
+                });
+            }
+            catch (err) {
+                const header = `Assets by Creator ${formatAddress(creatorAddress)}`;
+                return handleToolError(err, 'Error searching assets', [
+                    addressError(header, 'Invalid Solana address. Please provide a valid base58-encoded address.'),
+                    paginationError(header),
+                ]);
+            }
             headerLabel = `Assets by Creator ${formatAddress(creatorAddress)}`;
         }
         // General search → searchAssets
         else {
             if (name && !ownerAddress) {
-                return {
-                    content: [{
-                            type: 'text',
-                            text: `**Search Error:** Searching by name requires an owner address. Please also provide \`ownerAddress\` to search for assets named "${name}".`
-                        }]
-                };
+                return mcpText(`**Search Error:** Searching by name requires an owner address. Please also provide \`ownerAddress\` to search for assets named "${name}".`);
             }
             const params = { page, limit };
             if (ownerAddress)
@@ -275,23 +273,16 @@ export function registerAssetTools(server) {
                 response = await helius.searchAssets(params);
             }
             catch (err) {
-                return {
-                    content: [{
-                            type: 'text',
-                            text: `Error searching assets: ${err instanceof Error ? err.message : String(err)}`
-                        }]
-                };
+                return handleToolError(err, 'Error searching assets', [
+                    addressError('Asset Search'),
+                    paginationError('Asset Search'),
+                ]);
             }
             headerLabel = 'Asset Search Results';
         }
         const items = (response.items || []);
         if (items.length === 0) {
-            return {
-                content: [{
-                        type: 'text',
-                        text: `**${headerLabel}**\n\nNo assets found matching the criteria.`
-                    }]
-            };
+            return mcpText(`**${headerLabel}**\n\nNo assets found matching the criteria.`);
         }
         const lines = [`**${headerLabel}** (${response.total || items.length} total, page ${page})`, ''];
         items.forEach((asset) => {
@@ -310,37 +301,37 @@ export function registerAssetTools(server) {
                 lines.push(`  Owner: ${formatAddress(asset.ownership.owner)}`);
             }
         });
-        return {
-            content: [{
-                    type: 'text',
-                    text: lines.join('\n')
-                }]
-        };
+        return mcpText(lines.join('\n'));
     });
     // Get Assets by Group (Collection)
-    server.tool('getAssetsByGroup', 'Get all NFTs in a collection by group key/value. The groupKey is usually "collection" and groupValue is the collection mint address. Use this to browse all NFTs in a specific collection.', {
+    server.tool('getAssetsByGroup', 'Get all NFTs in a collection by group key/value. The groupKey is usually "collection" and groupValue is the collection mint address. Use this to browse all NFTs in a specific collection. DAS API (10 credits/call).', {
         groupKey: z.string().describe('Group key - usually "collection"'),
-        groupValue: z.string().describe('Group value - usually the collection mint address'),
+        groupValue: z.string().describe('Group value - usually the collection 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 ({ groupKey, groupValue, page, limit }) => {
         if (!hasApiKey())
             return noApiKeyResponse();
         const helius = getHeliusClient();
-        const response = await helius.getAssetsByGroup({
-            groupKey,
-            groupValue,
-            page,
-            limit
-        });
+        let response;
+        try {
+            response = await helius.getAssetsByGroup({
+                groupKey,
+                groupValue,
+                page,
+                limit
+            });
+        }
+        catch (err) {
+            const header = `Assets in Group ${groupKey}=${formatAddress(groupValue)}`;
+            return handleToolError(err, 'Error fetching group assets', [
+                addressError(header, 'Invalid Solana address. Please provide a valid base58-encoded address.'),
+                paginationError(header),
+            ]);
+        }
         const items = (response.items || []);
         if (items.length === 0) {
-            return {
-                content: [{
-                        type: 'text',
-                        text: `**Assets in Group ${groupKey}=${formatAddress(groupValue)}**\n\nNo assets found.`
-                    }]
-            };
+            return mcpText(`**Assets in Group ${groupKey}=${formatAddress(groupValue)}**\n\nNo assets found.`);
         }
         const lines = [`**Assets in Group ${groupKey}=${formatAddress(groupValue)}** (${response.total || items.length} total, page ${page})`, ''];
         items.forEach((asset) => {
@@ -351,11 +342,6 @@ export function registerAssetTools(server) {
                 lines.push(`  Owner: ${formatAddress(asset.ownership.owner)}`);
             }
         });
-        return {
-            content: [{
-                    type: 'text',
-                    text: lines.join('\n')
-                }]
-        };
+        return mcpText(lines.join('\n'));
     });
 }

package/dist/tools/auth.d.ts

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