helius-mcp 1.3.0 → 2.0.0

package/dist/tools/plans.js

@@ -1,10 +1,12 @@
 import { z } from 'zod';
 import { fetchDoc, extractSections } from '../utils/docs.js';
-import { mcpError } from '../utils/errors.js';
+import { mcpText, mcpError } from '../utils/errors.js';
+import { hasApiKey } from '../utils/helius.js';
 import { getJwt } from '../utils/config.js';
 import { listProjects } from 'helius-sdk/auth/listProjects';
 import { getProject } from 'helius-sdk/auth/getProject';
 import { MCP_USER_AGENT } from '../http.js';
+import { PRODUCT_CATALOG, PLAN_RANK } from './product-catalog.js';
 /**
  * Static plan metadata — NOT the source of truth for pricing or billing data.
  *
@@ -17,8 +19,8 @@ import { MCP_USER_AGENT } from '../http.js';
  * from the billing docs via fetchDoc('billing').
  */
 export const HELIUS_PLANS = {
-    free: {
-        name: 'Free',
+    agent: {
+        name: 'Agent',
         features: { webhooks: true, standardWebSockets: true, enhancedWebSockets: false, laserstream: false, stakedConnections: true, archivalData: true },
     },
     developer: {
@@ -37,11 +39,30 @@ export const HELIUS_PLANS = {
 const BILLING_FETCH_ERROR = 'Could not fetch live billing data. Try:\n' +
     '- `lookupHeliusDocs({ topic: \'billing\' })` for full billing documentation\n' +
     '- Visit https://www.helius.dev/docs/billing directly';
+const BILLING_FETCH_META = {
+    type: 'API',
+    code: 'FETCH_FAILED',
+    retryable: true,
+    recovery: 'Try lookupHeliusDocs({ topic: "billing" }) or visit https://www.helius.dev/docs/billing directly',
+};
 /**
  * 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.
  */
+/**
+ * Normalize backend plan keys (e.g. `agent_v4`, `developer_v4`) to the
+ * canonical short keys used in HELIUS_PLANS / PLAN_RANK / PRODUCT_CATALOG.
+ * Backend appends `_v4` for current-generation plans; the MCP/CLI surface
+ * uses the short form throughout.
+ */
+function normalizePlanKey(raw) {
+    if (!raw)
+        return undefined;
+    const trimmed = raw.trim().toLowerCase();
+    // Strip `_v4` (and any future `_v<N>`) suffix.
+    return trimmed.replace(/_v\d+$/, '');
+}
 export async function detectCurrentPlan() {
     const jwt = getJwt();
     if (!jwt)
@@ -50,9 +71,9 @@ export async function detectCurrentPlan() {
         const projects = await listProjects(jwt, MCP_USER_AGENT);
         if (projects.length > 0) {
             const details = await getProject(jwt, projects[0].id, MCP_USER_AGENT);
-            const raw = details.subscriptionPlanDetails?.currentPlan?.trim().toLowerCase();
-            if (raw && raw in HELIUS_PLANS)
-                return raw;
+            const normalized = normalizePlanKey(details.subscriptionPlanDetails?.currentPlan);
+            if (normalized && normalized in HELIUS_PLANS)
+                return normalized;
         }
     }
     catch {
@@ -62,19 +83,19 @@ export async function detectCurrentPlan() {
 }
 export function registerPlanTools(server) {
     server.tool('getHeliusPlanInfo', 'BEST FOR: pricing and plan questions. PREFER compareHeliusPlans for side-by-side category comparisons, getRateLimitInfo for per-method credit costs. Get Helius plan pricing, credits, rate limits, and feature availability. Fetches live from billing docs.', {
-        plan: z.enum(['free', 'developer', 'business', 'professional', 'all']).optional().default('all').describe('Specific plan to show details for, or "all" for comparison'),
+        plan: z.enum(['agent', 'developer', 'business', 'professional', 'all']).optional().default('all').describe('Specific plan to show details for, or "all" for comparison. Note: the MCP/CLI signup flow uses Agent ($10 one-time) as the entry tier; the dashboard\'s Free tier is not available through this path.'),
     }, async ({ plan }) => {
         let billingDoc;
         try {
             billingDoc = await fetchDoc('billing');
         }
         catch {
-            return mcpError(BILLING_FETCH_ERROR);
+            return mcpError(BILLING_FETCH_ERROR, BILLING_FETCH_META);
         }
         // Required: plans table
         const plansTable = extractSections(billingDoc, ['standard plans', 'standard pricing'], { includeLooseMatches: false });
         if (!plansTable) {
-            return mcpError(BILLING_FETCH_ERROR);
+            return mcpError(BILLING_FETCH_ERROR, BILLING_FETCH_META);
         }
         // Optional sections
         const credits = extractSections(billingDoc, ['credits system', 'credit costs'], { includeLooseMatches: false });
@@ -98,7 +119,7 @@ export function registerPlanTools(server) {
             sections.push('', addOns);
         if (rateLimits)
             sections.push('', rateLimits);
-        sections.push('', '---', '', '## Actions', '', '- To upgrade, use the `upgradePlan` tool with a plan name (developer, business, professional)', '- To preview pricing before upgrading, use the `previewUpgrade` tool', '', 'Source: https://www.helius.dev/docs/billing (fetched live)');
+        sections.push('', '---', '', '## Actions', '', '- To sign up for the Agent plan ($10 one-time, 1M credits), use the `signup` tool', '- To upgrade an existing account, use the `upgradePlan` tool with a plan name (developer, business, professional)', '- To preview pricing before upgrading, use the `previewUpgrade` tool', '', 'Source: https://www.helius.dev/docs/billing (fetched live)');
         return { content: [{ type: 'text', text: sections.join('\n') }] };
     });
     server.tool('compareHeliusPlans', 'BEST FOR: side-by-side plan comparison in a specific category. Compare Helius plans for rate limits, features, or pricing. Fetches live from billing docs.', {
@@ -109,7 +130,7 @@ export function registerPlanTools(server) {
             billingDoc = await fetchDoc('billing');
         }
         catch {
-            return mcpError(BILLING_FETCH_ERROR);
+            return mcpError(BILLING_FETCH_ERROR, BILLING_FETCH_META);
         }
         const sectionMap = {
             rates: ['rate limits', 'standard rate limits', 'special rate limits'],
@@ -118,7 +139,7 @@ export function registerPlanTools(server) {
         };
         const extracted = extractSections(billingDoc, sectionMap[category], { includeLooseMatches: false });
         if (!extracted) {
-            return mcpError(BILLING_FETCH_ERROR);
+            return mcpError(BILLING_FETCH_ERROR, BILLING_FETCH_META);
         }
         const lines = [];
         const currentPlanKey = await detectCurrentPlan();
@@ -130,4 +151,138 @@ export function registerPlanTools(server) {
         lines.push('', '---', 'Source: https://www.helius.dev/docs/billing (fetched live)');
         return { content: [{ type: 'text', text: lines.join('\n') }] };
     });
+    // ── getAccountPlan — lightweight pre-flight check ──
+    server.tool('getAccountPlan', 'Lightweight pre-flight check: returns current plan, credit balance, and which MCP tools require an upgrade. 0 credits. Call before gated tools (transactionSubscribe, laserstreamSubscribe, etc.).', {}, async () => {
+        // ── Tier 1: not authenticated at all ──
+        if (!hasApiKey()) {
+            return mcpText(`## Account Plan\n\n` +
+                `**Auth:** Not authenticated\n\n` +
+                `No API key or session found. To get started:\n` +
+                `- If you have a key: use the \`setHeliusApiKey\` tool\n` +
+                `- If you need an account: use \`generateKeypair\` → \`signup\` (link mode prints a payment URL)`);
+        }
+        // ── Tier 2: API key present but no JWT ──
+        const jwt = getJwt();
+        if (!jwt) {
+            return mcpText(`## Account Plan\n\n` +
+                `**Auth:** API key configured, plan unknown\n\n` +
+                `To see your plan and tool eligibility, call \`signup\`.\n` +
+                `Your existing account will be detected automatically — no payment needed.`);
+        }
+        // ── Tier 3: full status via JWT ──
+        try {
+            const projects = await listProjects(jwt, MCP_USER_AGENT);
+            if (projects.length === 0) {
+                return mcpError('No projects found. Call `signup` to create an account first.');
+            }
+            const projectId = projects[0].id;
+            const details = await getProject(jwt, projectId, MCP_USER_AGENT);
+            const planKey = normalizePlanKey(details.subscriptionPlanDetails?.currentPlan) ?? 'unknown';
+            const planInfo = HELIUS_PLANS[planKey];
+            if (!planInfo) {
+                console.warn(`[getAccountPlan] Unrecognized plan "${planKey}" — tool eligibility may be inaccurate`);
+            }
+            const planName = planInfo?.name ?? planKey;
+            // Credit info
+            const totalCredits = details.subscriptionPlanDetails?.totalCredits ?? 0;
+            const usedCredits = details.subscriptionPlanDetails?.usedCredits ?? 0;
+            const remainingCredits = totalCredits - usedCredits;
+            const usedPct = totalCredits > 0 ? ((usedCredits / totalCredits) * 100).toFixed(1) : '0.0';
+            // Tool eligibility
+            const eligibility = computeToolEligibility(planKey);
+            const lines = [
+                `## Account Plan`,
+                ``,
+                `**Plan:** ${planName}`,
+                ``,
+                `### Credits`,
+                `- **Remaining:** ${remainingCredits.toLocaleString()} / ${totalCredits.toLocaleString()} (${usedPct}% used)`,
+                ``,
+                `### Gated Tool Eligibility`,
+                `All Agent-tier tools are available on every plan.`,
+                ``,
+            ];
+            if (eligibility.length > 0) {
+                lines.push(`| Tool | Status | Requires |`, `|------|--------|----------|`);
+                for (const e of eligibility) {
+                    lines.push(`| ${e.tool} | ${e.status} | ${e.requires} |`);
+                }
+            }
+            else {
+                lines.push(`All tools are available on your plan.`);
+            }
+            // Next steps — find tools that need upgrade
+            const upgradeNeeded = eligibility.filter(e => e.status.includes('UPGRADE REQUIRED'));
+            if (upgradeNeeded.length > 0) {
+                lines.push(``, `### Next Steps`);
+                const toolNames = upgradeNeeded.map(e => e.tool);
+                const uniqueRequires = [...new Set(upgradeNeeded.map(e => e.requires))];
+                lines.push(`To unlock ${toolNames.join(', ')}, upgrade to ${uniqueRequires.join(' or ')}.`);
+                lines.push(`→ Use \`previewUpgrade\` to see pricing`);
+            }
+            return mcpText(lines.join('\n'));
+        }
+        catch (err) {
+            return mcpError(`Failed to fetch account plan: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+}
+function computeToolEligibility(planKey) {
+    const userRank = PLAN_RANK[planKey] ?? 0;
+    // Collect all non-free product entries per tool
+    const toolProducts = {};
+    for (const product of Object.values(PRODUCT_CATALOG)) {
+        if (product.minimumPlan === 'agent')
+            continue;
+        for (const tool of product.mcpTools) {
+            if (!toolProducts[tool])
+                toolProducts[tool] = [];
+            toolProducts[tool].push({ productName: product.name, minimumPlan: product.minimumPlan });
+        }
+    }
+    const results = [];
+    for (const [tool, products] of Object.entries(toolProducts)) {
+        // Also check if this tool appears in any baseline product (Agent tier)
+        const inBaselineToo = Object.values(PRODUCT_CATALOG).some(p => p.minimumPlan === 'agent' && p.mcpTools.includes(tool));
+        if (products.length === 1) {
+            const p = products[0];
+            const available = userRank >= (PLAN_RANK[p.minimumPlan] ?? 99);
+            const planDisplay = HELIUS_PLANS[p.minimumPlan]?.name ?? p.minimumPlan;
+            if (inBaselineToo && available) {
+                // Tool is available at baseline tier AND at this gated tier — show available
+                results.push({ tool, status: 'AVAILABLE', requires: planDisplay });
+            }
+            else if (inBaselineToo && !available) {
+                // Tool works at baseline tier but the enhanced version needs upgrade
+                results.push({ tool, status: `AVAILABLE (basic) / UPGRADE REQUIRED (${p.productName})`, requires: planDisplay });
+            }
+            else {
+                results.push({ tool, status: available ? 'AVAILABLE' : 'UPGRADE REQUIRED', requires: planDisplay });
+            }
+        }
+        else {
+            // Multiple gated products (e.g. laserstreamSubscribe in devnet + mainnet)
+            const statuses = [];
+            const requires = [];
+            for (const p of products) {
+                const available = userRank >= (PLAN_RANK[p.minimumPlan] ?? 99);
+                const planDisplay = HELIUS_PLANS[p.minimumPlan]?.name ?? p.minimumPlan;
+                const label = p.productName.includes('(') ? p.productName.replace(/.*\(/, '').replace(/\).*/, '').toLowerCase() : p.productName;
+                statuses.push(available ? `AVAILABLE (${label})` : `UPGRADE REQUIRED (${label})`);
+                requires.push(planDisplay);
+            }
+            const allAvailable = statuses.every(s => s.startsWith('AVAILABLE'));
+            const allUnavailable = statuses.every(s => s.startsWith('UPGRADE'));
+            if (allAvailable) {
+                results.push({ tool, status: 'AVAILABLE', requires: requires.join(' / ') });
+            }
+            else if (allUnavailable) {
+                results.push({ tool, status: 'UPGRADE REQUIRED', requires: requires[requires.length - 1] });
+            }
+            else {
+                results.push({ tool, status: statuses.join(' / '), requires: requires.join(' / ') });
+            }
+        }
+    }
+    return results;
 }

package/dist/tools/product-catalog.d.ts

@@ -7,4 +7,5 @@ export interface CatalogProduct {
     referenceFile?: string;
     description: string;
 }
+export declare const PLAN_RANK: Record<string, number>;
 export declare const PRODUCT_CATALOG: Record<string, CatalogProduct>;

package/dist/tools/product-catalog.js

@@ -3,12 +3,17 @@
 // Centralized product definitions — each Helius product defined once with its
 // invariant properties. The recommend tool groups products by minimumPlan into
 // tiers and uses the description field to give AI consumers rich context.
+// ─── Plan Ranking ───
+// Pure data constant — lives here (zero imports) to avoid circular dependencies.
+// Plan tiers, lowest to highest. The MCP/CLI signup flow uses Agent as the
+// entry tier (the dashboard's Free tier is not reachable through this surface).
+export const PLAN_RANK = { agent: 0, developer: 1, business: 2, professional: 3 };
 export const PRODUCT_CATALOG = {
     'das-api': {
         name: 'DAS API',
         mcpTools: ['getAssetsByOwner', 'getAssetsByGroup', 'searchAssets', 'getAsset', 'getTokenBalances', 'getTokenAccounts'],
         creditCostPerCall: '10 credits',
-        minimumPlan: 'free',
+        minimumPlan: 'agent',
         docKey: 'das',
         referenceFile: 'references/das.md',
         description: 'Query tokens, NFTs, collections, and digital assets. Fetches wallet token holdings with names, symbols, and prices. Browse NFT collections, search assets by creator/authority/owner.',
@@ -17,7 +22,7 @@ export const PRODUCT_CATALOG = {
         name: 'Standard RPC',
         mcpTools: ['getBalance', 'getAccountInfo', 'getBlock', 'getNetworkStatus'],
         creditCostPerCall: '1-10 credits',
-        minimumPlan: 'free',
+        minimumPlan: 'agent',
         docKey: 'rpc',
         description: 'Core Solana RPC for native SOL balances, account data, block info, and network status. Foundation for any Solana app.',
     },
@@ -25,7 +30,7 @@ export const PRODUCT_CATALOG = {
         name: 'Enhanced Transactions API',
         mcpTools: ['parseTransactions', 'getTransactionHistory'],
         creditCostPerCall: '100 credits',
-        minimumPlan: 'free',
+        minimumPlan: 'agent',
         docKey: 'enhanced-transactions',
         referenceFile: 'references/enhanced-transactions.md',
         description: 'Parse any transaction into human-readable format with types (SWAP, TRANSFER, NFT_SALE), descriptions, token transfers, and fees. Powers transaction history views and trade verification.',
@@ -41,9 +46,9 @@ export const PRODUCT_CATALOG = {
     },
     'webhooks': {
         name: 'Webhooks',
-        mcpTools: ['createWebhook', 'getAllWebhooks', 'updateWebhook', 'deleteWebhook'],
+        mcpTools: ['createWebhook', 'getAllWebhooks', 'getWebhookByID', 'updateWebhook', 'deleteWebhook'],
         creditCostPerCall: '100 credits to create, 1 credit per event',
-        minimumPlan: 'free',
+        minimumPlan: 'agent',
         docKey: 'webhooks',
         referenceFile: 'references/webhooks.md',
         description: 'HTTP POST notifications when monitored addresses have on-chain activity. Event-driven architecture without polling. Monitor up to 100k addresses per webhook. Filter by 150+ transaction types (SWAP, NFT_SALE, TRANSFER, etc.).',
@@ -51,8 +56,8 @@ export const PRODUCT_CATALOG = {
     'enhanced-websockets': {
         name: 'Enhanced WebSockets',
         mcpTools: ['transactionSubscribe', 'accountSubscribe', 'getEnhancedWebSocketInfo'],
-        creditCostPerCall: '3 credits per 0.1 MB streamed',
-        minimumPlan: 'business',
+        creditCostPerCall: '2 credits per 0.1 MB streamed',
+        minimumPlan: 'developer',
         docKey: 'enhanced-websockets',
         referenceFile: 'references/websockets.md',
         description: 'Real-time transaction and account streaming over persistent WebSocket connections. 1.5-2x faster than standard WebSockets with advanced filtering (up to 50k addresses per filter). Powers live dashboards and real-time UIs.',
@@ -61,7 +66,7 @@ export const PRODUCT_CATALOG = {
         name: 'Helius Sender',
         mcpTools: ['getSenderInfo'],
         creditCostPerCall: '0 credits',
-        minimumPlan: 'free',
+        minimumPlan: 'agent',
         docKey: 'sender',
         referenceFile: 'references/sender.md',
         description: 'Submit transactions with SWQoS routing, staked connections, and Jito tip integration for optimal landing rates. Essential for trading bots, token launches, and any app that sends transactions.',
@@ -70,7 +75,7 @@ export const PRODUCT_CATALOG = {
         name: 'Priority Fee API',
         mcpTools: ['getPriorityFeeEstimate'],
         creditCostPerCall: '1 credit',
-        minimumPlan: 'free',
+        minimumPlan: 'agent',
         docKey: 'priority-fee',
         referenceFile: 'references/priority-fees.md',
         description: 'Real-time fee estimates for transaction prioritization during network congestion. Returns recommended fees at multiple priority levels (Min, Low, Medium, High, VeryHigh).',
@@ -78,8 +83,8 @@ export const PRODUCT_CATALOG = {
     'standard-websockets': {
         name: 'Standard WebSockets',
         mcpTools: ['transactionSubscribe'],
-        creditCostPerCall: '3 credits per 0.1 MB streamed',
-        minimumPlan: 'free',
+        creditCostPerCall: '2 credits per 0.1 MB streamed',
+        minimumPlan: 'agent',
         docKey: 'websocket',
         referenceFile: 'references/websockets.md',
         description: 'Persistent connection for real-time transaction and account updates using standard Solana WebSocket subscriptions. Good for confirmation tracking and basic streaming.',
@@ -87,7 +92,7 @@ export const PRODUCT_CATALOG = {
     'laserstream-devnet': {
         name: 'Laserstream (Devnet)',
         mcpTools: ['laserstreamSubscribe', 'getLaserstreamInfo'],
-        creditCostPerCall: '3 credits per 0.1 MB streamed',
+        creditCostPerCall: '2 credits per 0.1 MB streamed',
         minimumPlan: 'developer',
         docKey: 'laserstream',
         referenceFile: 'references/laserstream.md',
@@ -96,8 +101,8 @@ export const PRODUCT_CATALOG = {
     'laserstream-mainnet': {
         name: 'Laserstream (Mainnet)',
         mcpTools: ['laserstreamSubscribe', 'getLaserstreamInfo'],
-        creditCostPerCall: '3 credits per 0.1 MB streamed',
-        minimumPlan: 'professional',
+        creditCostPerCall: '2 credits per 0.1 MB streamed',
+        minimumPlan: 'business',
         docKey: 'laserstream',
         referenceFile: 'references/laserstream.md',
         description: 'Lowest-latency gRPC streaming with 24h historical replay for production indexers, trading infrastructure, and data pipelines. Subscribe to all transactions, accounts, blocks, or entries on mainnet.',
@@ -106,16 +111,46 @@ export const PRODUCT_CATALOG = {
         name: 'Token Transfers',
         mcpTools: ['transferSol', 'transferToken'],
         creditCostPerCall: '~3-13 credits + on-chain fees',
-        minimumPlan: 'free',
+        minimumPlan: 'agent',
         docKey: 'sender',
         referenceFile: 'references/sender.md',
         description: 'Send native SOL or SPL tokens from the MCP keypair to any Solana address. Uses Helius Sender for optimal landing rates. Requires a configured keypair.',
     },
+    'zk-compression': {
+        name: 'ZK Compression',
+        mcpTools: [
+            'getCompressedAccount', 'getCompressedAccountsByOwner', 'getMultipleCompressedAccounts',
+            'getCompressedBalance', 'getCompressedBalanceByOwner',
+            'getCompressedMintTokenHolders', 'getCompressedTokenAccountBalance',
+            'getCompressedTokenAccountsByOwner', 'getCompressedTokenAccountsByDelegate',
+            'getCompressedTokenBalancesByOwnerV2',
+            'getCompressedAccountProof', 'getMultipleCompressedAccountProofs', 'getMultipleNewAddressProofs',
+            'getCompressionSignaturesForAccount', 'getCompressionSignaturesForAddress',
+            'getCompressionSignaturesForOwner', 'getCompressionSignaturesForTokenOwner',
+            'getLatestCompressionSignatures', 'getLatestNonVotingSignatures',
+            'getTransactionWithCompressionInfo', 'getValidityProof',
+            'getIndexerHealth', 'getIndexerSlot',
+        ],
+        creditCostPerCall: '10 credits',
+        minimumPlan: 'agent',
+        docKey: 'zk-compression',
+        referenceFile: 'references/zk-compression.md',
+        description: 'Query compressed accounts, token balances, Merkle proofs, validity proofs, and compression transaction history via the ZK Compression / Light Protocol indexer. Powers state compression for cost-efficient on-chain data storage.',
+    },
+    'native-staking': {
+        name: 'Native Staking',
+        mcpTools: ['stakeSOL', 'unstakeSOL', 'withdrawStake', 'getStakeAccounts', 'getWithdrawableAmount'],
+        creditCostPerCall: '~3-10 credits + on-chain fees',
+        minimumPlan: 'agent',
+        docKey: 'sender',
+        referenceFile: 'references/sender.md',
+        description: 'Stake, unstake, and withdraw native SOL via the Helius validator. Earn staking yield with one-click delegation. Query stake accounts and withdrawable amounts.',
+    },
     'token-holders': {
         name: 'Token Holders',
         mcpTools: ['getTokenHolders'],
         creditCostPerCall: '20 credits',
-        minimumPlan: 'free',
+        minimumPlan: 'agent',
         docKey: 'das',
         referenceFile: 'references/das.md',
         description: 'Top 20 holders of any SPL token. Check token distribution, find whale wallets, verify decentralization. Useful for token launches and analytics.',

package/dist/tools/recommend.d.ts

@@ -1,4 +1,3 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export declare const KNOWN_TOOLS: Set<string>;
-export declare const PLAN_RANK: Record<string, number>;
 export declare function registerRecommendTools(server: McpServer): void;

package/dist/tools/recommend.js

@@ -3,31 +3,12 @@ import { mcpText } from '../utils/errors.js';
 import { hasApiKey } from '../utils/helius.js';
 import { getPreferences, savePreferences } from '../utils/config.js';
 import { HELIUS_PLANS, detectCurrentPlan } from './plans.js';
-import { PRODUCT_CATALOG } from './product-catalog.js';
+import { PRODUCT_CATALOG, PLAN_RANK } from './product-catalog.js';
+import { ACTION_NAME_SET } from '../router/actions.js';
 // fetchDoc/extractSections no longer needed — live billing fetch removed
 // ─── Known MCP Tools (for validation script) ───
-export const KNOWN_TOOLS = new Set([
-    'getStarted', 'setHeliusApiKey', 'generateKeypair', 'checkSignupBalance',
-    'agenticSignup', 'getAccountStatus', 'previewUpgrade', 'upgradePlan', 'payRenewal',
-    'getBalance', 'getTokenBalances', 'getWalletBalances',
-    'parseTransactions', 'getTransactionHistory', 'getWalletHistory', 'getWalletTransfers',
-    'getAsset', 'getAssetsByOwner', 'searchAssets', 'getAssetsByGroup',
-    'getAssetProof', 'getAssetProofBatch', 'getSignaturesForAsset', 'getNftEditions',
-    'getAccountInfo', 'getTokenAccounts', 'getProgramAccounts', 'getTokenHolders',
-    'getBlock', 'getNetworkStatus',
-    'getPriorityFeeEstimate',
-    'createWebhook', 'getAllWebhooks', 'getWebhookByID', 'updateWebhook', 'deleteWebhook',
-    'transactionSubscribe', 'accountSubscribe', 'getEnhancedWebSocketInfo',
-    'laserstreamSubscribe', 'getLaserstreamInfo',
-    'getWalletIdentity', 'batchWalletIdentity', 'getWalletFundedBy',
-    'getHeliusPlanInfo', 'compareHeliusPlans',
-    'lookupHeliusDocs', 'listHeliusDocTopics', 'getHeliusCreditsInfo', 'getRateLimitInfo',
-    'troubleshootError', 'getSenderInfo', 'getWebhookGuide', 'getLatencyComparison', 'getPumpFunGuide',
-    'recommendStack',
-    'transferSol', 'transferToken',
-]);
-// ─── Plan Ranking ───
-export const PLAN_RANK = { free: 0, developer: 1, business: 2, professional: 3 };
+export const KNOWN_TOOLS = ACTION_NAME_SET;
+// ─── Plan Ranking (re-exported from product-catalog.ts) ───
 function planAtOrBelow(plan, maxPlan) {
     return (PLAN_RANK[plan] ?? 99) <= (PLAN_RANK[maxPlan] ?? 99);
 }
@@ -57,8 +38,8 @@ const TIER_MAP = {
     business: 'production',
     professional: 'production',
 };
-const TIER_DISPLAY = { budget: 'Free', standard: 'Developer', production: 'Business / Professional' };
-const TIER_PLANS = { budget: 'free', standard: 'developer', production: 'business' };
+const TIER_DISPLAY = { budget: 'Agent', standard: 'Developer', production: 'Business / Professional' };
+const TIER_PLANS = { budget: 'agent', standard: 'developer', production: 'business' };
 function groupCatalogByTier() {
     const groups = { budget: [], standard: [], production: [] };
     for (const product of Object.values(PRODUCT_CATALOG)) {
@@ -67,7 +48,7 @@ function groupCatalogByTier() {
     }
     const tiers = [];
     if (groups.budget.length > 0)
-        tiers.push({ tier: 'budget', tierPlan: 'free', products: groups.budget });
+        tiers.push({ tier: 'budget', tierPlan: 'agent', products: groups.budget });
     if (groups.standard.length > 0)
         tiers.push({ tier: 'standard', tierPlan: 'developer', products: groups.standard });
     if (groups.production.length > 0)
@@ -133,7 +114,7 @@ function formatCatalog(availableTiers, upgradeTiers, description, complexity, de
     }
     lines.push('---', '');
     if (complexity) {
-        const label = { low: 'free tier only', medium: 'free + developer tiers', high: 'all tiers' };
+        const label = { low: 'agent tier only', medium: 'agent + developer tiers', high: 'all tiers' };
         lines.push(`_Showing ${label[complexity]}_`, '', '---', '');
     }
     for (let i = 0; i < availableTiers.length; i++) {
@@ -170,7 +151,7 @@ const SCALE_TIERS = {
 export function registerRecommendTools(server) {
     server.tool('recommendStack', 'BEST FOR: project architecture when user describes a Solana app to build. PREFER getHeliusPlanInfo for pricing-only, lookupHeliusDocs for API docs. Get tiered architecture recommendations. Returns Helius products, MCP tools, credit costs, minimum plan, and reference files.', {
         description: z.string().describe('What the user wants to build, in their own words'),
-        budget: z.enum(['free', 'developer', 'business', 'professional']).optional(),
+        budget: z.enum(['agent', 'developer', 'business', 'professional']).optional(),
         complexity: z.enum(['low', 'medium', 'high']).optional(),
         scale: z.enum(['budget', 'standard', 'production', 'all']).optional().default('all'),
         remember: z.boolean().optional().describe('Save budget/complexity preferences for future sessions'),

package/dist/tools/shared.d.ts

@@ -3,4 +3,5 @@ export declare function noApiKeyResponse(): {
         type: "text";
         text: string;
     }[];
+    isError: boolean;
 };

package/dist/tools/shared.js

@@ -1,18 +1,26 @@
-const NO_API_KEY_MESSAGE = `**Helius API Key Required**
-
-I need a Helius API key to query the Solana blockchain.
-
-**Option 1 — Sign up here (recommended):**
-1. Call \`generateKeypair\` to create a signup wallet
-2. Fund the wallet with ~0.001 SOL + 1 USDC
-3. Call \`agenticSignup\` to create your account — the API key will be configured automatically
-
-**Option 2 — Use an existing key:**
-1. Go to https://dashboard.helius.dev/api-keys
-2. Copy your API key
+const NO_API_KEY_META = {
+    type: 'AUTH',
+    code: 'NO_API_KEY',
+    retryable: false,
+    recovery: 'Call generateKeypair + signup, or setHeliusApiKey',
+};
+const NO_API_KEY_MESSAGE = `**Helius API Key Required**
+
+I need a Helius API key to query the Solana blockchain.
+
+**Option 1 — Sign up here (recommended):**
+1. Call \`generateKeypair\` to create a signup wallet
+2. Fund the wallet with ~0.001 SOL + 1 USDC
+3. Call \`signup\` to create your account — the API key will be configured automatically
+
+**Option 2 — Use an existing key:**
+1. Go to https://dashboard.helius.dev/api-keys
+2. Copy your API key
 3. Call \`setHeliusApiKey\` with your key`;
 export function noApiKeyResponse() {
+    const body = '```json\n' + JSON.stringify(NO_API_KEY_META) + '\n```\n\n' + NO_API_KEY_MESSAGE;
     return {
-        content: [{ type: 'text', text: NO_API_KEY_MESSAGE }]
+        content: [{ type: 'text', text: body }],
+        isError: true,
     };
 }

package/dist/tools/solana-knowledge.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { MCP_USER_AGENT } from '../http.js';
-import { mcpText, handleToolError } from '../utils/errors.js';
+import { mcpText, mcpError, handleToolError } from '../utils/errors.js';
 // ---------------------------------------------------------------------------
 // Cache
 // ---------------------------------------------------------------------------
@@ -271,7 +271,7 @@ export function registerSolanaKnowledgeTools(server) {
                 })
                     .map((e) => `  SIMD-${e.number}: ${e.slug}`)
                     .join('\n');
-                return mcpText(`SIMD-${paddedNumber} not found.\n\n${nearby ? `Nearby proposals:\n${nearby}` : `Total proposals available: ${index.length}`}`);
+                return mcpError(`SIMD-${paddedNumber} not found.\n\n${nearby ? `Nearby proposals:\n${nearby}` : `Total proposals available: ${index.length}`}`, { type: 'NOT_FOUND', code: 'RESOURCE_NOT_FOUND', retryable: false, recovery: 'Check the SIMD number. Use listSIMDs to see available proposals.' });
             }
             const url = `${SIMD_RAW_BASE}/${entry.filename}`;
             const content = await cachedFetch(url);
@@ -331,7 +331,7 @@ export function registerSolanaKnowledgeTools(server) {
     }, async ({ path, repo, branch }) => {
         try {
             if (path.includes('..')) {
-                return mcpText('Invalid path: must not contain ".." segments.');
+                return mcpError('Invalid path: must not contain ".." segments.', { type: 'VALIDATION', code: 'INVALID_PARAM', retryable: false, recovery: 'Remove ".." segments from the path.' });
             }
             const repoMap = {
                 agave: { fullName: 'anza-xyz/agave', defaultBranch: 'master' },
@@ -366,7 +366,7 @@ export function registerSolanaKnowledgeTools(server) {
             return handleToolError(error, 'Error reading source file', [
                 {
                     match: (msg) => msg.includes('404'),
-                    respond: () => mcpText(`**File not found:** \`${path}\`\n\nTips:\n- Check the path is correct\n- Browse https://github.com/${repoInfo} to find the right path\n- The default branch for ${repo} is "${defaultBr}"`),
+                    respond: () => mcpError(`**File not found:** \`${path}\`\n\nTips:\n- Check the path is correct\n- Browse https://github.com/${repoInfo} to find the right path\n- The default branch for ${repo} is "${defaultBr}"`, { type: 'NOT_FOUND', code: 'HTTP_404', retryable: false, recovery: `Check the file path. Browse https://github.com/${repoInfo} to find the right path.` }),
                 },
             ]);
         }
@@ -476,7 +476,8 @@ export function registerSolanaKnowledgeTools(server) {
     server.tool('fetchHeliusBlog', 'Fetch a technical blog post from Helius (helius.dev/blog). The Helius blog covers SVM internals, consensus, transactions, fees, MEV, validator economics, development frameworks, security, and more. Use "list" to see available posts or "fetch" to read one.', {
         action: z
             .enum(['fetch', 'list'])
-            .describe('"fetch" to read a specific post, "list" to see available posts by category'),
+            .optional()
+            .describe('"fetch" to read a specific post, "list" to see available posts by category. Defaults to "fetch" if slug provided, "list" otherwise.'),
         slug: z
             .string()
             .optional()
@@ -485,7 +486,9 @@ export function registerSolanaKnowledgeTools(server) {
             .enum(['all', 'runtime', 'consensus', 'transactions', 'validators', 'data', 'security', 'development', 'tokens'])
             .default('all')
             .describe('Filter by category when listing posts'),
-    }, async ({ action, slug, category }) => {
+    }, async ({ action: rawAction, slug: rawSlug, category }) => {
+        let slug = rawSlug;
+        const action = rawAction ?? (slug ? 'fetch' : 'list');
         try {
             if (action === 'list') {
                 const entries = Object.entries(BLOG_INDEX);
@@ -524,7 +527,20 @@ export function registerSolanaKnowledgeTools(server) {
             }
             // Fetch a specific post
             if (!slug) {
-                return mcpText('Please provide a slug. Use `fetchHeliusBlog` with action "list" to see available posts.');
+                return mcpError('Please provide a slug. Use `fetchHeliusBlog` with action "list" to see available posts.', { type: 'VALIDATION', code: 'MISSING_PARAM', retryable: false, recovery: 'Provide a slug. Use fetchHeliusBlog with action "list" to see available posts.' });
+            }
+            // Fuzzy slug matching — if exact slug isn't in index, find close matches
+            if (!BLOG_INDEX[slug]) {
+                const lower = slug.toLowerCase();
+                const matches = Object.keys(BLOG_INDEX).filter((k) => k.includes(lower) || lower.includes(k) || k.split('-').some((w) => lower.includes(w) && w.length > 3));
+                if (matches.length === 1) {
+                    // Single match — auto-correct
+                    slug = matches[0];
+                }
+                else if (matches.length > 1) {
+                    return mcpError(`No exact blog post "${slug}". Did you mean one of these?\n${matches.map((m) => `- \`${m}\` — ${BLOG_INDEX[m].title}`).join('\n')}`, { type: 'VALIDATION', code: 'UNKNOWN_SLUG', retryable: true, recovery: 'Retry with one of the suggested slugs.' });
+                }
+                // If no matches, let it proceed — the fetch will 404 with a helpful message
             }
             const url = `https://www.helius.dev/blog/${slug}`;
             const html = await cachedFetch(url);

package/dist/tools/staking.d.ts

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