helius-mcp 1.3.0 → 2.0.0

package/dist/tools/transfers.js

@@ -1,10 +1,11 @@
 import { z } from 'zod';
-import { createKeyPairSignerFromBytes, address } from '@solana/kit';
+import { address } from '@solana/kit';
 import { getTransferSolInstruction } from '@solana-program/system';
 import { findAssociatedTokenPda, getCloseAccountInstruction, getCreateAssociatedTokenIdempotentInstruction, getTransferCheckedInstruction, TOKEN_PROGRAM_ADDRESS, } from '@solana-program/token';
-import { getHeliusClient, hasApiKey, loadSignerOrFail } from '../utils/helius.js';
+import { getHeliusClient, hasApiKey } from '../utils/helius.js';
 import { mcpText, mcpError, handleToolError, isValidAddressFormat } from '../utils/errors.js';
 import { noApiKeyResponse } from './shared.js';
+import { resolveOwsOrKeypairSigner } from '../utils/ows.js';
 const TOKEN_2022_PROGRAM_ID = 'TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb';
 // ── Tool Registration ──
 export function registerTransferTools(server) {
@@ -19,24 +20,22 @@ export function registerTransferTools(server) {
         recipientAddress: z.string().describe('Recipient Solana wallet address (base58 encoded)'),
         amount: z.number().positive().optional().describe('Amount of SOL to send (e.g., 0.5 for half a SOL). Required unless sendMax is true.'),
         sendMax: z.boolean().optional().default(false).describe('Send the maximum possible amount (entire balance minus transaction fees). When true, amount is ignored.'),
-    }, async ({ recipientAddress, amount, sendMax }) => {
+        owsWallet: z.string().optional().describe('OWS wallet name for policy-gated signing (requires `ows` CLI installed). When provided, signs via Open Wallet Standard instead of the local keypair.'),
+    }, async ({ recipientAddress, amount, sendMax, owsWallet }) => {
         if (!hasApiKey())
             return noApiKeyResponse();
         try {
-            // Load keypair
-            let signerData;
-            try {
-                signerData = await loadSignerOrFail();
-            }
-            catch {
-                return mcpError('No keypair found. Call `generateKeypair` first to create a wallet, then fund it before sending.');
-            }
+            // Load signer — OWS wallet or local keypair
+            const resolved = await resolveOwsOrKeypairSigner(owsWallet);
+            if (!resolved.ok)
+                return resolved.error;
+            const { signer, walletAddress } = resolved;
             // Validate recipient address
             if (!isValidAddressFormat(recipientAddress)) {
-                return mcpError(`Invalid recipient address "${recipientAddress}". Expected a valid Solana address (32-44 base58 characters).`);
+                return mcpError(`Invalid recipient address "${recipientAddress}". Expected a valid Solana address (32-44 base58 characters).`, { type: 'VALIDATION', code: 'INVALID_ADDRESS', retryable: false, recovery: 'Provide a valid base58-encoded Solana address (32-44 characters).' });
             }
             const helius = getHeliusClient();
-            const balanceResult = await helius.getBalance(signerData.walletAddress);
+            const balanceResult = await helius.getBalance(walletAddress);
             const balanceLamports = BigInt(balanceResult.value);
             let lamports;
             let sendAmount;
@@ -56,13 +55,13 @@ export function registerTransferTools(server) {
                 if (lamports <= 0n) {
                     const available = Number(balanceLamports) / 1_000_000_000;
                     return mcpError(`Balance too low to cover the transaction fee. You have ${available} SOL.\n\n` +
-                        `Wallet: \`${signerData.walletAddress}\``);
+                        `Wallet: \`${walletAddress}\``, { type: 'INSUFFICIENT_FUNDS', code: 'LOW_SOL', retryable: false, recovery: `Fund the wallet with more SOL. Current balance: ${available} SOL.` });
                 }
                 sendAmount = Number(lamports) / 1_000_000_000;
             }
             else {
                 if (amount === undefined) {
-                    return mcpError('Either `amount` must be specified or `sendMax` must be true.');
+                    return mcpError('Either `amount` must be specified or `sendMax` must be true.', { type: 'VALIDATION', code: 'MISSING_PARAM', retryable: false, recovery: 'Provide `amount` or set `sendMax` to true.' });
                 }
                 lamports = BigInt(Math.round(amount * 1_000_000_000));
                 sendAmount = amount;
@@ -71,11 +70,9 @@ export function registerTransferTools(server) {
                 if (balanceLamports < lamports + reserveLamports) {
                     const available = Number(balanceLamports) / 1_000_000_000;
                     return mcpError(`Insufficient SOL balance. You have ${available} SOL but need ${sendAmount} SOL plus ~0.005 SOL for transaction fees.\n\n` +
-                        `Wallet: \`${signerData.walletAddress}\``);
+                        `Wallet: \`${walletAddress}\``, { type: 'INSUFFICIENT_FUNDS', code: 'LOW_SOL', retryable: false, recovery: `Fund the wallet with at least ${sendAmount + 0.005} SOL.` });
                 }
             }
-            // Create signer from keypair bytes
-            const signer = await createKeyPairSignerFromBytes(signerData.secretKey);
             // Build transfer instruction
             const ix = getTransferSolInstruction({
                 source: signer,
@@ -100,8 +97,9 @@ export function registerTransferTools(server) {
                     region: 'Default',
                 });
             }
+            const signerLabel = owsWallet ? `\`${walletAddress}\` (OWS: ${owsWallet})` : `\`${walletAddress}\``;
             return mcpText(`**SOL Transfer Sent**\n\n` +
-                `- **From:** \`${signerData.walletAddress}\`\n` +
+                `- **From:** ${signerLabel}\n` +
                 `- **To:** \`${recipientAddress}\`\n` +
                 `- **Amount:** ${sendAmount} SOL${sendMax ? ' (max)' : ''}\n` +
                 `- **Signature:** \`${signature}\`\n` +
@@ -124,24 +122,22 @@ export function registerTransferTools(server) {
         mintAddress: z.string().describe('Token mint address (base58 encoded, e.g., EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v for USDC)'),
         amount: z.number().positive().optional().describe('Amount of tokens to send in human-readable units (e.g., 10 for 10 USDC). Required unless sendMax is true.'),
         sendMax: z.boolean().optional().default(false).describe('Send the entire token balance and close the sender token account to reclaim rent. When true, amount is ignored.'),
-    }, async ({ recipientAddress, mintAddress, amount, sendMax }) => {
+        owsWallet: z.string().optional().describe('OWS wallet name for policy-gated signing (requires `ows` CLI installed). When provided, signs via Open Wallet Standard instead of the local keypair.'),
+    }, async ({ recipientAddress, mintAddress, amount, sendMax, owsWallet }) => {
         if (!hasApiKey())
             return noApiKeyResponse();
         try {
-            // Load keypair
-            let signerData;
-            try {
-                signerData = await loadSignerOrFail();
-            }
-            catch {
-                return mcpError('No keypair found. Call `generateKeypair` first to create a wallet, then fund it before sending.');
-            }
+            // Load signer — OWS wallet or local keypair
+            const resolved = await resolveOwsOrKeypairSigner(owsWallet);
+            if (!resolved.ok)
+                return resolved.error;
+            const { signer, walletAddress } = resolved;
             // Validate addresses
             if (!isValidAddressFormat(recipientAddress)) {
-                return mcpError(`Invalid recipient address "${recipientAddress}". Expected a valid Solana address (32-44 base58 characters).`);
+                return mcpError(`Invalid recipient address "${recipientAddress}". Expected a valid Solana address (32-44 base58 characters).`, { type: 'VALIDATION', code: 'INVALID_ADDRESS', retryable: false, recovery: 'Provide a valid base58-encoded Solana address (32-44 characters).' });
             }
             if (!isValidAddressFormat(mintAddress)) {
-                return mcpError(`Invalid mint address "${mintAddress}". Expected a valid Solana address (32-44 base58 characters).`);
+                return mcpError(`Invalid mint address "${mintAddress}". Expected a valid Solana address (32-44 base58 characters).`, { type: 'VALIDATION', code: 'INVALID_ADDRESS', retryable: false, recovery: 'Provide a valid base58-encoded token mint address (32-44 characters).' });
             }
             // Fetch token metadata via DAS to get decimals and token program
             const helius = getHeliusClient();
@@ -150,10 +146,10 @@ export function registerTransferTools(server) {
                 asset = await helius.getAsset({ id: mintAddress });
             }
             catch {
-                return mcpError(`Could not fetch token metadata for mint \`${mintAddress}\`. Verify the mint address is correct.`);
+                return mcpError(`Could not fetch token metadata for mint \`${mintAddress}\`. Verify the mint address is correct.`, { type: 'NOT_FOUND', code: 'RESOURCE_NOT_FOUND', retryable: false, recovery: 'Verify the mint address is correct. Use `getAsset` to check if the mint exists.' });
             }
             if (!asset?.token_info?.decimals && asset?.token_info?.decimals !== 0) {
-                return mcpError(`Mint \`${mintAddress}\` does not appear to be a fungible token (no decimals info found). Use \`getAsset\` to inspect it.`);
+                return mcpError(`Mint \`${mintAddress}\` does not appear to be a fungible token (no decimals info found). Use \`getAsset\` to inspect it.`, { type: 'NOT_FOUND', code: 'RESOURCE_NOT_FOUND', retryable: false, recovery: 'This mint may not be a fungible token. Use `getAsset` to inspect it.' });
             }
             const decimals = asset.token_info.decimals;
             const tokenProgram = asset.token_info.token_program;
@@ -161,10 +157,8 @@ export function registerTransferTools(server) {
             const tokenSymbol = asset.content?.metadata?.symbol || '';
             // Token-2022 check
             if (tokenProgram === TOKEN_2022_PROGRAM_ID) {
-                return mcpError(`Token-2022 transfers are not yet supported. This token (\`${tokenName}\`${tokenSymbol ? ` / ${tokenSymbol}` : ''}) uses the Token-2022 program. Standard SPL Token transfers are supported.`);
+                return mcpError(`Token-2022 transfers are not yet supported. This token (\`${tokenName}\`${tokenSymbol ? ` / ${tokenSymbol}` : ''}) uses the Token-2022 program. Standard SPL Token transfers are supported.`, { type: 'UNSUPPORTED', code: 'TOKEN_2022', retryable: false, recovery: 'Token-2022 transfers are not yet supported. Only standard SPL Token transfers are available.' });
             }
-            // Create signer from keypair bytes
-            const signer = await createKeyPairSignerFromBytes(signerData.secretKey);
             const mint = address(mintAddress);
             const recipient = address(recipientAddress);
             // Derive ATAs
@@ -188,20 +182,20 @@ export function registerTransferTools(server) {
                 }
                 catch {
                     return mcpError(`No token account found for ${tokenSymbol || tokenName}. You may not hold this token.\n\n` +
-                        `Wallet: \`${signerData.walletAddress}\`\n` +
-                        `Mint: \`${mintAddress}\``);
+                        `Wallet: \`${walletAddress}\`\n` +
+                        `Mint: \`${mintAddress}\``, { type: 'INSUFFICIENT_FUNDS', code: 'LOW_TOKEN', retryable: false, recovery: `You may not hold ${tokenSymbol || tokenName}. Check your token balances with getTokenBalances.` });
                 }
                 rawAmount = BigInt(tokenBalance.value.amount);
                 if (rawAmount === 0n) {
                     return mcpError(`${tokenSymbol || tokenName} balance is 0. Nothing to send.\n\n` +
-                        `Wallet: \`${signerData.walletAddress}\`\n` +
-                        `Mint: \`${mintAddress}\``);
+                        `Wallet: \`${walletAddress}\`\n` +
+                        `Mint: \`${mintAddress}\``, { type: 'INSUFFICIENT_FUNDS', code: 'ZERO_BALANCE', retryable: false, recovery: `${tokenSymbol || tokenName} balance is zero. Fund the wallet with tokens before sending.` });
                 }
                 sendAmount = Number(rawAmount) / 10 ** decimals;
             }
             else {
                 if (amount === undefined) {
-                    return mcpError('Either `amount` must be specified or `sendMax` must be true.');
+                    return mcpError('Either `amount` must be specified or `sendMax` must be true.', { type: 'VALIDATION', code: 'MISSING_PARAM', retryable: false, recovery: 'Provide `amount` or set `sendMax` to true.' });
                 }
                 rawAmount = BigInt(Math.round(amount * 10 ** decimals));
                 sendAmount = amount;
@@ -212,8 +206,8 @@ export function registerTransferTools(server) {
                     if (currentRaw < rawAmount) {
                         const currentHuman = Number(currentRaw) / 10 ** decimals;
                         return mcpError(`Insufficient ${tokenSymbol || tokenName} balance. You have ${currentHuman} but are trying to send ${sendAmount}.\n\n` +
-                            `Wallet: \`${signerData.walletAddress}\`\n` +
-                            `Mint: \`${mintAddress}\``);
+                            `Wallet: \`${walletAddress}\`\n` +
+                            `Mint: \`${mintAddress}\``, { type: 'INSUFFICIENT_FUNDS', code: 'LOW_TOKEN', retryable: false, recovery: `You have ${currentHuman} ${tokenSymbol || tokenName} but need ${sendAmount}. Fund the wallet with more tokens.` });
                     }
                 }
                 catch {
@@ -255,8 +249,9 @@ export function registerTransferTools(server) {
             const displayName = tokenSymbol
                 ? `${sendAmount} ${tokenSymbol} (${tokenName})`
                 : `${sendAmount} ${tokenName}`;
+            const signerLabel = owsWallet ? `\`${walletAddress}\` (OWS: ${owsWallet})` : `\`${walletAddress}\``;
             return mcpText(`**Token Transfer Sent**\n\n` +
-                `- **From:** \`${signerData.walletAddress}\`\n` +
+                `- **From:** ${signerLabel}\n` +
                 `- **To:** \`${recipientAddress}\`\n` +
                 `- **Amount:** ${displayName}${sendMax ? ' (max)' : ''}\n` +
                 `- **Mint:** \`${mintAddress}\`\n` +

package/dist/tools/wallet.js

@@ -1,20 +1,23 @@
 import { z } from 'zod';
 import { getHeliusClient, hasApiKey } from '../utils/helius.js';
-import { formatAddress, formatSol, formatTimestamp } from '../utils/formatters.js';
+import { formatAddress, formatTimestamp } from '../utils/formatters.js';
 import { noApiKeyResponse } from './shared.js';
 import { mcpText, mcpError, validateEnum, handleToolError, http404Error, addressError } from '../utils/errors.js';
 export function registerWalletTools(server) {
     // ─── Get Wallet Identity ───
-    server.tool('getWalletIdentity', 'BEST FOR: identifying a single known wallet. PREFER batchWalletIdentity for multiple addresses. Identify known wallets (exchanges, protocols, institutions). Returns name, type, category, tags. Credit cost: 100 credits.', {
-        address: z.string().describe('Solana wallet address (base58 encoded)')
+    server.tool('getWalletIdentity', 'BEST FOR: identifying a single known wallet. PREFER batchWalletIdentity for multiple addresses. Identify known wallets (exchanges, protocols, institutions). Returns name, type, category, tags. Also accepts SNS/ANS domains (e.g., `toly.sol`, `helius.bonk`) — mainnet only. Credit cost: 100 credits.', {
+        address: z.string().describe('Solana wallet address (base58) or SNS/ANS domain (e.g., toly.sol, helius.bonk — mainnet only)')
     }, async ({ address }) => {
         if (!hasApiKey())
             return noApiKeyResponse();
         try {
             const client = getHeliusClient();
+            // TODO: drop `any` once helius-sdk types include inputDomain on the identity response
             const data = await client.wallet.getIdentity({ wallet: address });
             const lines = ['**Wallet Identity**', ''];
-            lines.push(`**Address:** ${formatAddress(address)}`);
+            if (data.inputDomain)
+                lines.push(`**Input:** ${data.inputDomain}`);
+            lines.push(`**Address:** ${formatAddress(data.address || address)}`);
             if (data.name)
                 lines.push(`**Name:** ${data.name}`);
             if (data.type)
@@ -32,25 +35,33 @@ export function registerWalletTools(server) {
         }
     });
     // ─── Batch Wallet Identity ───
-    server.tool('batchWalletIdentity', 'BEST FOR: identifying multiple wallets at once (up to 100). PREFER getWalletIdentity for a single address. Look up identities for up to 100 Solana addresses. Returns names, types, and categories. Credit cost: 100 credits.', {
-        addresses: z.array(z.string()).describe('Array of Solana wallet addresses (base58 encoded, max 100)')
-    }, async ({ addresses }) => {
+    server.tool('batchWalletIdentity', 'BEST FOR: identifying multiple wallets at once (up to 100). PREFER getWalletIdentity for a single address. Look up identities for up to 100 entries. Returns names, types, and categories. Entries may be addresses or SNS/ANS domains (mainnet only); unresolved domains are returned with `unresolved: true`. Credit cost: 100 credits.', {
+        entries: z.array(z.string()).describe('Array of up to 100 entries — each a base58 address or SNS/ANS domain')
+    }, async ({ entries }) => {
         if (!hasApiKey())
             return noApiKeyResponse();
-        if (addresses.length > 100) {
-            return mcpError('Error: Maximum 100 addresses per batch request.');
+        if (entries.length > 100) {
+            return mcpError('Maximum 100 entries per batch request.', { type: 'VALIDATION', code: 'TOO_MANY_ITEMS', retryable: false, recovery: 'Reduce batch to 100 or fewer entries.' });
         }
         try {
             const client = getHeliusClient();
-            const results = await client.wallet.getBatchIdentity({ addresses });
+            const results = await client.wallet.getBatchIdentity({ addresses: entries });
             if (results.length === 0) {
-                return mcpText(`**Batch Identity Lookup** (${addresses.length} addresses)\n\nNo identities found.`);
+                return mcpText(`**Batch Identity Lookup** (${entries.length} entries)\n\nNo identities found.`);
             }
             const lines = [`**Batch Identity Lookup** (${results.length} results)`, ''];
+            // TODO: drop `Array<any>` once helius-sdk types include inputDomain/unresolved on the batch response
             for (const entry of results) {
+                if (entry.unresolved) {
+                    lines.push(`- \`${entry.inputDomain || '?'}\` — Unresolved domain`);
+                    continue;
+                }
                 const addr = formatAddress(entry.address || '');
+                const subject = entry.inputDomain && entry.address
+                    ? `\`${entry.inputDomain}\` → ${addr}`
+                    : addr;
                 if (entry.name) {
-                    lines.push(`- **${entry.name}** — ${addr}`);
+                    lines.push(`- **${entry.name}** — ${subject}`);
                     const details = [];
                     if (entry.type)
                         details.push(entry.type);
@@ -60,14 +71,14 @@ export function registerWalletTools(server) {
                         lines.push(`  ${details.join(' | ')}`);
                 }
                 else {
-                    lines.push(`- ${addr} — Unknown`);
+                    lines.push(`- ${subject} — Unknown`);
                 }
             }
             return mcpText(lines.join('\n'));
         }
         catch (err) {
             return handleToolError(err, 'Error fetching batch identities', [
-                addressError('Batch Identity'),
+                addressError('Batch Identity', 'Entries must be base58 addresses or SNS/ANS domains.'),
             ]);
         }
     });
@@ -164,7 +175,7 @@ export function registerWalletTools(server) {
             transactions.forEach((tx, i) => {
                 const time = tx.timestamp ? formatTimestamp(tx.timestamp) : 'N/A';
                 const status = tx.error ? 'Failed' : 'Success';
-                const fee = tx.fee ? formatSol(tx.fee) : 'N/A';
+                const fee = tx.fee != null ? `${tx.fee} SOL` : 'N/A';
                 lines.push(`${i + 1}. ${time} — ${status} — Fee: ${fee}`);
                 lines.push(`   Signature: \`${tx.signature}\``);
                 // Balance changes
@@ -252,7 +263,7 @@ export function registerWalletTools(server) {
             if (data.funderType)
                 lines.push(`**Type:** ${data.funderType}`);
             if (data.amount !== undefined) {
-                lines.push(`**Amount:** ${formatSol(data.amount)}`);
+                lines.push(`**Amount:** ${data.amount} SOL`);
             }
             if (data.date)
                 lines.push(`**Date:** ${data.date}`);

package/dist/tools/webhooks.js

@@ -3,7 +3,7 @@ import { getHeliusClient, hasApiKey } from '../utils/helius.js';
 import { formatAddress } from '../utils/formatters.js';
 import { noApiKeyResponse } from './shared.js';
 import { TRANSACTION_TYPES } from '../types/transaction-types.js';
-import { mcpText, validateEnum, handleToolError, http404Error, http400Error } from '../utils/errors.js';
+import { mcpText, mcpError, validateEnum, handleToolError, http404Error, http400Error } from '../utils/errors.js';
 export function registerWebhookTools(server) {
     server.tool('getAllWebhooks', 'List all active webhooks for your Helius account. Shows webhook IDs, URLs, and monitored addresses. Credit cost: 100 credits/call (management operation).', {}, async () => {
         if (!hasApiKey())
@@ -77,7 +77,7 @@ export function registerWebhookTools(server) {
         if (transactionTypes) {
             const invalid = transactionTypes.filter(t => !TRANSACTION_TYPES.includes(t));
             if (invalid.length > 0) {
-                return mcpText(`**Create Webhook Error**\n\nInvalid transaction type(s): ${invalid.join(', ')}. See valid types: https://www.helius.dev/docs/webhooks/transaction-types`);
+                return mcpError(`**Create Webhook Error**\n\nInvalid transaction type(s): ${invalid.join(', ')}. See valid types: https://www.helius.dev/docs/webhooks/transaction-types`, { type: 'VALIDATION', code: 'INVALID_ENUM', retryable: false, recovery: `Remove invalid transaction types: ${invalid.join(', ')}. See https://www.helius.dev/docs/webhooks/transaction-types for valid types.` });
             }
         }
         try {
@@ -113,7 +113,7 @@ export function registerWebhookTools(server) {
         if (transactionTypes) {
             const invalid = transactionTypes.filter(t => !TRANSACTION_TYPES.includes(t));
             if (invalid.length > 0) {
-                return mcpText(`**Update Webhook Error**\n\nInvalid transaction type(s): ${invalid.join(', ')}. See valid types: https://www.helius.dev/docs/webhooks/transaction-types`);
+                return mcpError(`**Update Webhook Error**\n\nInvalid transaction type(s): ${invalid.join(', ')}. See valid types: https://www.helius.dev/docs/webhooks/transaction-types`, { type: 'VALIDATION', code: 'INVALID_ENUM', retryable: false, recovery: `Remove invalid transaction types: ${invalid.join(', ')}. See https://www.helius.dev/docs/webhooks/transaction-types for valid types.` });
             }
         }
         try {

package/dist/tools/zk-compression.d.ts

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