helius-mcp 0.5.3 → 1.2.0

package/dist/tools/recommend.js

@@ -0,0 +1,233 @@
+import { z } from 'zod';
+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';
+// 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 };
+function planAtOrBelow(plan, maxPlan) {
+    return (PLAN_RANK[plan] ?? 99) <= (PLAN_RANK[maxPlan] ?? 99);
+}
+// ─── Plan Limitations ───
+function derivePlanLimitations(minimumPlan) {
+    const plan = HELIUS_PLANS[minimumPlan];
+    if (!plan)
+        return [];
+    const limitations = [];
+    limitations.push(`${plan.name} plan — see \`getHeliusPlanInfo\` for credits and rate limits`);
+    const gates = [];
+    if (!plan.features.enhancedWebSockets)
+        gates.push('Enhanced WebSockets');
+    if (!plan.features.laserstream) {
+        gates.push('Laserstream');
+    }
+    else if (typeof plan.features.laserstream === 'string' && plan.features.laserstream.toLowerCase().includes('devnet only')) {
+        limitations.push('Laserstream limited to devnet');
+    }
+    if (gates.length > 0)
+        limitations.push(`No ${gates.join(' or ')}`);
+    return limitations;
+}
+const TIER_MAP = {
+    free: 'budget',
+    developer: 'standard',
+    business: 'production',
+    professional: 'production',
+};
+const TIER_DISPLAY = { budget: 'Free', standard: 'Developer', production: 'Business / Professional' };
+const TIER_PLANS = { budget: 'free', standard: 'developer', production: 'business' };
+function groupCatalogByTier() {
+    const groups = { budget: [], standard: [], production: [] };
+    for (const product of Object.values(PRODUCT_CATALOG)) {
+        const tier = TIER_MAP[product.minimumPlan] ?? 'production';
+        groups[tier].push(product);
+    }
+    const tiers = [];
+    if (groups.budget.length > 0)
+        tiers.push({ tier: 'budget', tierPlan: 'free', products: groups.budget });
+    if (groups.standard.length > 0)
+        tiers.push({ tier: 'standard', tierPlan: 'developer', products: groups.standard });
+    if (groups.production.length > 0)
+        tiers.push({ tier: 'production', tierPlan: 'business', products: groups.production });
+    return tiers;
+}
+// ─── Formatting ───
+function formatProduct(product) {
+    const docs = product.referenceFile ? ` | Docs: \`${product.referenceFile}\`` : '';
+    return `- **${product.name}** \u2014 ${product.description} (${product.creditCostPerCall})${docs}\n  Tools: ${product.mcpTools.map(t => '`' + t + '`').join(', ')}`;
+}
+function formatTier(tier, detectedPlan) {
+    const tierLabel = TIER_DISPLAY[tier.tier];
+    let heading = `## ${tierLabel} Tier`;
+    if (detectedPlan) {
+        if (planAtOrBelow(tier.tierPlan, detectedPlan)) {
+            heading += ` \u2014 Available on your plan`;
+        }
+        else {
+            heading += ` \u2014 Requires upgrade`;
+        }
+    }
+    const lines = [heading, ''];
+    for (const product of tier.products) {
+        lines.push(formatProduct(product), '');
+    }
+    const limitations = derivePlanLimitations(tier.tierPlan);
+    if (limitations.length > 0) {
+        lines.push(`### ${tierLabel} Tier Limits`);
+        for (const lim of limitations) {
+            lines.push(`- ${lim}`);
+        }
+    }
+    return lines.join('\n');
+}
+function formatUpgradeTier(tier) {
+    const planInfo = HELIUS_PLANS[tier.tierPlan];
+    const planName = planInfo ? planInfo.name : tier.tierPlan;
+    const tierLabel = TIER_DISPLAY[tier.tier];
+    const productNames = tier.products.map(p => p.name);
+    const firstDesc = tier.products[0].description.split('.')[0];
+    const addsLine = `Adds: ${productNames.join(', ')} \u2014 ${firstDesc}`;
+    const refs = tier.products
+        .filter(p => p.referenceFile)
+        .map(p => `\`${p.referenceFile}\``);
+    const refsLine = refs.length > 0 ? `Read: ${refs.join(', ')}` : '';
+    const lines = [
+        `### ${tierLabel} Tier \u2014 Requires ${planName} plan`,
+        addsLine,
+    ];
+    if (refsLine)
+        lines.push(refsLine);
+    return lines.join('\n');
+}
+function formatCatalog(availableTiers, upgradeTiers, description, complexity, detectedPlan) {
+    const lines = ['# Helius Product Catalog', ''];
+    lines.push(`> "${description}"`, '');
+    if (detectedPlan) {
+        const planInfo = HELIUS_PLANS[detectedPlan];
+        if (planInfo) {
+            lines.push(`**Your plan:** ${planInfo.name}`, '');
+        }
+    }
+    lines.push('---', '');
+    if (complexity) {
+        const label = { low: 'free tier only', medium: 'free + developer tiers', high: 'all tiers' };
+        lines.push(`_Showing ${label[complexity]}_`, '', '---', '');
+    }
+    for (let i = 0; i < availableTiers.length; i++) {
+        lines.push(formatTier(availableTiers[i], detectedPlan));
+        if (i < availableTiers.length - 1) {
+            lines.push('', '---', '');
+        }
+    }
+    if (upgradeTiers.length > 0) {
+        lines.push('', '---', '', '## Upgrade Paths', '');
+        for (let i = 0; i < upgradeTiers.length; i++) {
+            lines.push(formatUpgradeTier(upgradeTiers[i]));
+            if (i < upgradeTiers.length - 1) {
+                lines.push('');
+            }
+        }
+    }
+    lines.push('', '---', '', '_Use `getHeliusPlanInfo` for pricing and `lookupHeliusDocs` for API details._', '', '*Token tip: Use batch endpoints and `section` filters on `lookupHeliusDocs` to minimize per-call context usage.*');
+    return lines.join('\n');
+}
+// ─── Filtering ───
+const COMPLEXITY_MAX_TIER = {
+    low: ['budget'],
+    medium: ['budget', 'standard'],
+    high: ['budget', 'standard', 'production'],
+};
+const SCALE_TIERS = {
+    budget: ['budget'],
+    standard: ['standard'],
+    production: ['production'],
+    all: ['budget', 'standard', 'production'],
+};
+// ─── Tool Registration ───
+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(),
+        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'),
+    }, async ({ description, budget, complexity, scale, remember }) => {
+        // 1. Load saved preferences, merge with provided params
+        const savedPrefs = getPreferences();
+        const effectiveBudget = budget ?? savedPrefs.budget;
+        const effectiveComplexity = complexity ?? savedPrefs.complexity;
+        // 2. Save preferences if requested
+        if (remember) {
+            savePreferences({
+                budget: effectiveBudget,
+                complexity: effectiveComplexity,
+            });
+        }
+        // 3. Detect current plan from JWT
+        const detectedPlan = await detectCurrentPlan();
+        // 4. Group catalog into tiers
+        let tiers = groupCatalogByTier();
+        // 5. Apply filters (AND logic)
+        if (scale !== 'all') {
+            const allowed = SCALE_TIERS[scale] ?? [];
+            tiers = tiers.filter(t => allowed.includes(t.tier));
+        }
+        if (effectiveComplexity) {
+            const allowed = COMPLEXITY_MAX_TIER[effectiveComplexity] ?? [];
+            tiers = tiers.filter(t => allowed.includes(t.tier));
+        }
+        if (effectiveBudget) {
+            tiers = tiers.filter(t => planAtOrBelow(t.tierPlan, effectiveBudget));
+        }
+        if (tiers.length === 0) {
+            return mcpText(`# Helius Product Catalog\n\n` +
+                `> "${description}"\n\n` +
+                'No tiers match your current filters. Try:\n' +
+                '- Increasing your `budget` (e.g., `developer`, `business`)\n' +
+                '- Setting `scale` to `all` to see all tiers\n' +
+                '- Removing filters to see the full recommendation');
+        }
+        // 6. Partition tiers when plan is detected and no explicit budget filter
+        const shouldSplit = detectedPlan && !budget && !savedPrefs.budget;
+        let availableTiers = tiers;
+        let upgradeTiers = [];
+        if (shouldSplit) {
+            const available = tiers.filter(t => planAtOrBelow(t.tierPlan, detectedPlan));
+            const upgrades = tiers.filter(t => !planAtOrBelow(t.tierPlan, detectedPlan));
+            if (available.length > 0) {
+                availableTiers = available;
+                upgradeTiers = upgrades;
+            }
+        }
+        // 7. Format output
+        let output = formatCatalog(availableTiers, upgradeTiers, description, effectiveComplexity, detectedPlan);
+        // 9. Soft hint: if no API key, append setup note
+        if (!hasApiKey()) {
+            output += '\n\n---\n\n> **Setup needed:** You\'ll need a Helius API key to use these tools. Call `getStarted` for setup instructions.';
+        }
+        return mcpText(output);
+    });
+}

package/dist/tools/shared.js

@@ -2,10 +2,15 @@ const NO_API_KEY_MESSAGE = `**Helius API Key Required**
 
 I need a Helius API key to query the Solana blockchain.
 
-**Get your key:**
+**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. Sign in or sign up
-3. Send your API key here in chat`;
+2. Copy your API key
+3. Call \`setHeliusApiKey\` with your key`;
 export function noApiKeyResponse() {
     return {
         content: [{ type: 'text', text: NO_API_KEY_MESSAGE }]

package/dist/tools/solana-knowledge.d.ts

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