helius-mcp 0.5.2 → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
+
+## helius-mcp@1.0.0 - 2026-03-03
+
+### Merged
+
+- feat: Cross-platform skill portability for non-Claude developers [`#42`](https://github.com/helius-labs/core-ai/pull/42)
+- feat(MCP): Improve Testing Suite [`#41`](https://github.com/helius-labs/core-ai/pull/41)
+- feat(MCP): Add Changelog  [`#43`](https://github.com/helius-labs/core-ai/pull/43)
+- feat(MCP): Prep For 1.0.0 Release [`#40`](https://github.com/helius-labs/core-ai/pull/40)
+- release: helius-cli@1.1.0 [`#39`](https://github.com/helius-labs/core-ai/pull/39)
+- feat(docs): Better `README.md` Files [`#38`](https://github.com/helius-labs/core-ai/pull/38)
+- feat(mcp): add transferSol and transferToken tools [`#35`](https://github.com/helius-labs/core-ai/pull/35)
+- Add Helius x Phantom frontend skill [`#33`](https://github.com/helius-labs/core-ai/pull/33)
+- Standardize MCP Zod parameter descriptions [`#36`](https://github.com/helius-labs/core-ai/pull/36)
+- feat(mcp): reduce token usage across MCP server and SKILL.md [`#34`](https://github.com/helius-labs/core-ai/pull/34)
+- feat(skill): Add SVM Skill [`#37`](https://github.com/helius-labs/core-ai/pull/37)
+- Fix MCP tool selection ambiguity with BEST FOR/PREFER routing [`#32`](https://github.com/helius-labs/core-ai/pull/32)
+- Replace hardcoded billing data with live doc fetches [`#31`](https://github.com/helius-labs/core-ai/pull/31)
+- feat(mcp + cli): Add Solana Knowledge Tools [`#30`](https://github.com/helius-labs/core-ai/pull/30)
+- fix(cli): Improve Signup UX [`#29`](https://github.com/helius-labs/core-ai/pull/29)
+- feat(skill): Add Helius x DFlow Skill [`#27`](https://github.com/helius-labs/core-ai/pull/27)
+- Remove vestigial projectType from recommendStack [`#28`](https://github.com/helius-labs/core-ai/pull/28)
+- Add recommendStack MCP tool for architecture recommendations [`#25`](https://github.com/helius-labs/core-ai/pull/25)
+- feat(docs) Add README [`#11`](https://github.com/helius-labs/core-ai/pull/11)
+- feat(plugin): Add Helius Plugin For Claude Code [`#26`](https://github.com/helius-labs/core-ai/pull/26)
+- chore(GitHub): Add `.claude` to `.gitignore` [`#24`](https://github.com/helius-labs/core-ai/pull/24)
+- feat(mcp): Improve Onboarding [`#23`](https://github.com/helius-labs/core-ai/pull/23)
+- Improve MCP tool routing [`#22`](https://github.com/helius-labs/core-ai/pull/22)
+- feat(skills): Add Helius Skill [`#20`](https://github.com/helius-labs/core-ai/pull/20)
+- feat(cli): Better Errors [`#16`](https://github.com/helius-labs/core-ai/pull/16)
+- feat(mcp): Add Credit Cost Annotations [`#18`](https://github.com/helius-labs/core-ai/pull/18)
+- feat(mcp): Make All Data-bearing Guide Tools Fetch Directly From the Docs [`#19`](https://github.com/helius-labs/core-ai/pull/19)
+- feat(mcp): Add `getAccountStatus` Tool [`#17`](https://github.com/helius-labs/core-ai/pull/17)
+- fix: pass customer info through upgradePlan and CLI upgrade [`#15`](https://github.com/helius-labs/core-ai/pull/15)
+- feat(cli): Format Snake Case Enums Into Title Case [`#14`](https://github.com/helius-labs/core-ai/pull/14)
+- feat(cli): Explicitly Set Project ID on CLI Creation [`#13`](https://github.com/helius-labs/core-ai/pull/13)
+- feat: OpenPay integration for CLI and MCP server [`#10`](https://github.com/helius-labs/core-ai/pull/10)
+- feat/agent-signup [`#9`](https://github.com/helius-labs/core-ai/pull/9)
+- Add docs integration and cleanup [`#6`](https://github.com/helius-labs/core-ai/pull/6)
+- fix: migrate to use sdk [`#8`](https://github.com/helius-labs/core-ai/pull/8)
+- feat/claude.md and helius-sdk for cli [`#7`](https://github.com/helius-labs/core-ai/pull/7)
+- feat: add error handling [`#4`](https://github.com/helius-labs/core-ai/pull/4)
+- fix: repair updateWebhook and deleteWebhook MCP tools [`#2`](https://github.com/helius-labs/core-ai/pull/2)
+- feat: upgrade helius-mcp data tools with rich formatting and new capa… [`#1`](https://github.com/helius-labs/core-ai/pull/1)

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Helius Labs
+Copyright (c) 2026 Helius Labs
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,56 +1,132 @@
 # Helius MCP Server
 
-MCP server for Helius - Solana blockchain data access for Claude.
+MCP server for Helius — Solana blockchain data access for AI assistants, provided by Solana's fastest, most reliable infrastructure provider
 
-## Setup
+See the [CHANGELOG](https://github.com/helius-labs/core-ai/blob/main/helius-mcp/CHANGELOG.md) for version history and release notes.
+
+Interested in contributing? Read the [contribution guide](https://github.com/helius-labs/core-ai/blob/main/helius-mcp/CONTRIBUTING.md) before opening a PR.
+
+## Quick Start
+
+### 1. Add the MCP server
+
+Add to your MCP host's config (works with Claude, Cursor, Windsurf, and any MCP-compatible client):
+
+```json
+{
+  "mcpServers": {
+    "helius": {
+      "command": "npx",
+      "args": ["helius-mcp@latest"]
+    }
+  }
+}
+```
+
+Or if you're using Claude Code:
 
 ```bash
 claude mcp add helius npx helius-mcp@latest
 ```
 
-Set your API key:
+### 2. Configure your API key
+
+**If you already have a Helius API key:**
+
 ```bash
 export HELIUS_API_KEY=your-api-key
 ```
 
-## Tools (48)
+Or set it from your AI assistant by calling the `setHeliusApiKey` tool.
+
+**If you need a new account:**
+
+The MCP includes a fully autonomous signup flow — no browser needed:
+
+1. Call the `generateKeypair` tool — it creates a Solana wallet and returns the address
+2. Fund the wallet with **~0.001 SOL** (transaction fees) + **1 USDC** (basic plan costs $1)
+3. Call `checkSignupBalance` to verify funds arrived
+4. Call `agenticSignup` to create your account — API key is configured automatically
 
-**Config (2):** setHeliusApiKey, getHeliusApiKeyStatus
+> **Paid plans (developer/business/professional):** `agenticSignup` and `upgradePlan` require `email`, `firstName`, and `lastName`. Basic plan does not.
+
+Or do the same from the terminal:
+
+```bash
+npx helius-cli@latest keygen     # Generate keypair
+# Fund the wallet address shown above with ~0.001 SOL + 1 USDC
+npx helius-cli@latest signup      # Verify balance + create account
+```
 
-**DAS API (12):** getAsset, getAssetBatch, getAssetsByOwner, getAssetsByGroup, getAssetsByCreator, getAssetsByAuthority, searchAssets, getAssetProof, getAssetProofBatch, getSignaturesForAsset, getNftEditions, getTokenAccounts
+### 3. Start using tools
 
-**RPC (7):** getBalance, getTokenBalances, getAccountInfo, getProgramAccounts, getNetworkStatus, getBlock, getTokenHolders
+Ask questions in plain English — the right tool is selected automatically:
+
+- "What NFTs does this wallet own?"
+- "Parse this transaction: 5abc..."
+- "Get the balance of Gh9ZwEm..."
+- "Create a webhook for \<address\>"
+
+## Tools
+
+**Onboarding (6):** getStarted, setHeliusApiKey, generateKeypair, checkSignupBalance, agenticSignup, getAccountStatus
+
+**DAS API (9):** getAsset (single + batch), getAssetsByOwner, getAssetsByGroup, searchAssets (routes getAssetsByCreator / getAssetsByAuthority), getAssetProof, getAssetProofBatch, getSignaturesForAsset, getNftEditions, getTokenAccounts
+
+**RPC (5):** getBalance, getTokenBalances, getAccountInfo (single + batch), getNetworkStatus, getBlock
 
 **Transactions (2):** parseTransactions, getTransactionHistory
 
+**Transfers (2):** transferSol, transferToken
+
 **Priority Fees (1):** getPriorityFeeEstimate
 
+**Tokens (2):** getTokenHolders, getProgramAccounts
+
 **Webhooks (5):** getAllWebhooks, getWebhookByID, createWebhook, updateWebhook, deleteWebhook
 
 **Enhanced WebSockets (3):** transactionSubscribe, accountSubscribe, getEnhancedWebSocketInfo
 
 **Laserstream gRPC (2):** laserstreamSubscribe, getLaserstreamInfo
 
-**Wallet API (6):** getWalletIdentity, batchWalletIdentity, getWalletBalances, getWalletHistory, getWalletTransfers, getWalletFundedBy
+**Wallet (6):** getWalletIdentity, batchWalletIdentity, getWalletBalances, getWalletHistory, getWalletTransfers, getWalletFundedBy
 
-**Plans & Guides (8):** getHeliusPlanInfo, compareHeliusPlans, getRateLimitInfo, getSenderInfo, getWebhookGuide, troubleshootError, getLatencyComparison, getPumpFunGuide
+**Plans & Billing (5):** getHeliusPlanInfo, compareHeliusPlans, previewUpgrade, upgradePlan, payRenewal
 
-**Documentation (3):** lookupHeliusDocs, listHeliusDocTopics, getHeliusCreditsInfo
+**Docs & Guides (10):** lookupHeliusDocs, listHeliusDocTopics, getHeliusCreditsInfo, getRateLimitInfo, troubleshootError, getSenderInfo, getWebhookGuide, getLatencyComparison, getPumpFunGuide, recommendStack
 
-## Networks
+**Solana Knowledge (5):** getSIMD, listSIMDs, searchSolanaDocs, readSolanaSourceFile, fetchHeliusBlog
 
-Mainnet and Devnet. Set via `HELIUS_NETWORK` env var or use the `network` parameter in `setHeliusApiKey`.
+## System Prompts
 
-## Development
+This package ships with pre-built system prompts that teach AI models how to use Helius tools effectively. Find them in `system-prompts/`:
 
-```bash
-pnpm install
-pnpm build
-pnpm test
 ```
+system-prompts/
+├── helius/              # Core Helius skill
+├── helius-dflow/        # DFlow trading skill
+├── helius-phantom/      # Phantom frontend skill
+└── svm/                 # SVM architecture skill
+```
+
+Each contains three variants:
+- `openai.developer.md` — for OpenAI Responses/Chat Completions API (`developer` message)
+- `claude.system.md` — for Claude API (system prompt)
+- `full.md` — self-contained with all references inlined (Cursor Rules, ChatGPT, etc.)
+
+See [`helius-skills/SYSTEM-PROMPTS.md`](https://github.com/helius-labs/core-ai/blob/main/helius-skills/SYSTEM-PROMPTS.md) for integration guides and code examples.
+
+## Networks
+
+Mainnet Beta (default) and Devnet. Set via `HELIUS_NETWORK` env var or `setNetwork` in the session
 
-## Docs
+## Related Resources
 
-- [Helius API](https://docs.helius.dev)
-- [Enhanced WebSockets](https://docs.helius.dev/enhanced-websockets)
-- [Laserstream](https://docs.helius.dev/laserstream)
+- [Full Documentation](https://www.helius.dev/docs)
+- [LLM-Optimized Docs](https://www.helius.dev/docs/llms.txt)
+- [API Reference](https://www.helius.dev/docs/api-reference)
+- [Billing and Credits](https://www.helius.dev/docs/billing/credits.md)
+- [Rate Limits](https://www.helius.dev/docs/billing/rate-limits.md)
+- [Dashboard](https://dashboard.helius.dev)
+- [Status Page](https://helius.statuspage.io)
+- [Full Agent Signup Instructions](https://dashboard.helius.dev/agents.md)

package/dist/http.d.ts

@@ -0,0 +1 @@
+export declare const MCP_USER_AGENT = "helius-mcp/1.0.0";

package/dist/http.js

@@ -0,0 +1,2 @@
+import { version } from './version.js';
+export const MCP_USER_AGENT = `helius-mcp/${version}`;

package/dist/index.js

@@ -2,16 +2,93 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { registerTools } from './tools/index.js';
-import { setApiKey } from './utils/helius.js';
+import { setApiKey, setSessionSecretKey, setSessionWalletAddress } from './utils/helius.js';
+import { getSharedApiKey, loadKeypairFromDisk } from './utils/config.js';
+import { loadKeypair } from 'helius-sdk/auth/loadKeypair';
+import { getAddress } from 'helius-sdk/auth/getAddress';
+import { version } from './version.js';
 const server = new McpServer({
     name: 'helius-mcp',
-    version: '0.3.0'
+    version
+}, {
+    instructions: `These instructions provide fallback tool selection guidance. If you have more specific routing instructions from a Helius skill or system prompt, prefer those.
+
+## Tool Routing
+
+| Intent | Tool | Credits |
+|--------|------|---------|
+| SOL balance | getBalance | 1 |
+| token balances by wallet | getTokenBalances | 10/pg |
+| full portfolio + USD | getWalletBalances | 100 |
+| parse tx by signature | parseTransactions | 100 |
+| wallet transaction history | getTransactionHistory | ~110 |
+| balance deltas/tx | getWalletHistory | 100 |
+| sends/receives | getWalletTransfers | 100 |
+| asset by mint (single or batch) | getAsset | 10 |
+| wallet NFTs | getAssetsByOwner | 10 |
+| filtered asset search / by creator or authority | searchAssets | 10 |
+| collection NFTs | getAssetsByGroup | 10 |
+| asset tx history (by mint) | getSignaturesForAsset | 10 |
+| edition prints of master NFT | getNftEditions | 10 |
+| cNFT Merkle proof (single or batch) | getAssetProof, getAssetProofBatch | 10 |
+| raw account inspection (single or batch) | getAccountInfo | 1 |
+| token holders by mint | getTokenHolders | ~20 |
+| token accounts by mint or owner | getTokenAccounts | 10 |
+| program accounts / protocol state | getProgramAccounts | 10 |
+| network status / epoch / block height | getNetworkStatus | 3 |
+| block data by slot | getBlock | 1 |
+| plans/pricing | getHeliusPlanInfo | 0 |
+| plan comparison | compareHeliusPlans | 0 |
+| plan upgrade / billing | previewUpgrade, upgradePlan, payRenewal | 0 |
+| rate limits/credits | getRateLimitInfo | 0 |
+| API docs by topic | lookupHeliusDocs | 0 |
+| error diagnosis | troubleshootError | 0 |
+| tx sending / Jito / SWQoS | getSenderInfo | 0 |
+| webhook setup guide | getWebhookGuide | 0 |
+| streaming latency | getLatencyComparison | 0 |
+| pump.fun tokens | getPumpFunGuide | 0 |
+| project architecture / stack selection | recommendStack | 0 |
+| Solana SIMDs / protocol proposals | getSIMD, listSIMDs | 0 |
+| Solana source / docs search | searchSolanaDocs, readSolanaSourceFile | 0 |
+| Helius blog posts | fetchHeliusBlog | 0 |
+| wallet identity | getWalletIdentity | 100 |
+| batch wallet identity | batchWalletIdentity | 100 |
+| funding source | getWalletFundedBy | 100 |
+| event notifications (any plan) | createWebhook | 100 |
+| live streaming (WS, Business+) | transactionSubscribe, accountSubscribe | — |
+| production streaming (gRPC, Pro) | laserstreamSubscribe | — |
+| Account setup | getStarted → generateKeypair → agenticSignup | — |
+
+Rules:
+- For pricing, start with getHeliusPlanInfo — NOT lookupHeliusDocs.
+- For errors, use troubleshootError first.
+- When a user describes ANY project they want to build ("I want to build/make/create...", "help me build...", "I need a..."), call recommendStack immediately with their description — do not ask clarifying questions first. After recommendations, use getHeliusPlanInfo for pricing and lookupHeliusDocs for API details.
+- "send SOL" / "transfer SOL" → transferSol (~3 credits). "send tokens" / "transfer USDC/BONK/etc" → transferToken (~13 credits). Both require a configured keypair (generateKeypair) and use Helius Sender.`
 });
 registerTools(server);
 async function main() {
     if (process.env.HELIUS_API_KEY) {
         setApiKey(process.env.HELIUS_API_KEY);
     }
+    else {
+        const sharedKey = getSharedApiKey();
+        if (sharedKey) {
+            setApiKey(sharedKey);
+        }
+    }
+    // Load persisted keypair from disk so MCP survives restarts
+    const diskKey = loadKeypairFromDisk();
+    if (diskKey) {
+        try {
+            const walletKeypair = loadKeypair(diskKey);
+            const address = await getAddress(walletKeypair);
+            setSessionSecretKey(diskKey);
+            setSessionWalletAddress(address);
+        }
+        catch {
+            // Ignore invalid keypair on disk
+        }
+    }
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/dist/scripts/validate-catalog.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * Validates the product catalog for correctness.
+ *
+ * Checks:
+ * 1. Every mcpTools entry exists in KNOWN_TOOLS
+ * 2. Every referenceFile exists on disk
+ * 3. Every docKey exists in DOCS_INDEX
+ * 4. Every minimumPlan is a valid key in PLAN_RANK and HELIUS_PLANS
+ * 5. Plan-feature compatibility (Laserstream mainnet → professional, Enhanced WebSockets → business+)
+ * 6. No empty mcpTools arrays
+ */
+export {};

package/dist/scripts/validate-catalog.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+/**
+ * Validates the product catalog for correctness.
+ *
+ * Checks:
+ * 1. Every mcpTools entry exists in KNOWN_TOOLS
+ * 2. Every referenceFile exists on disk
+ * 3. Every docKey exists in DOCS_INDEX
+ * 4. Every minimumPlan is a valid key in PLAN_RANK and HELIUS_PLANS
+ * 5. Plan-feature compatibility (Laserstream mainnet → professional, Enhanced WebSockets → business+)
+ * 6. No empty mcpTools arrays
+ */
+import fs from 'fs';
+import path from 'path';
+import { PRODUCT_CATALOG } from '../tools/product-catalog.js';
+import { KNOWN_TOOLS, PLAN_RANK } from '../tools/recommend.js';
+import { HELIUS_PLANS } from '../tools/plans.js';
+import { DOCS_INDEX } from '../utils/docs.js';
+// Resolve skill references relative to repo root
+const REPO_ROOT = path.resolve(import.meta.dirname, '..', '..', '..');
+const SKILL_DIR = path.join(REPO_ROOT, 'helius-skills', 'helius');
+let errors = [];
+function error(productKey, msg) {
+    errors.push(`[${productKey}] ${msg}`);
+}
+for (const [key, product] of Object.entries(PRODUCT_CATALOG)) {
+    // 1. MCP tool names exist in KNOWN_TOOLS
+    for (const tool of product.mcpTools) {
+        if (!KNOWN_TOOLS.has(tool)) {
+            error(key, `Unknown MCP tool "${tool}"`);
+        }
+    }
+    // 2. referenceFile exists on disk
+    if (product.referenceFile) {
+        const refPath = path.join(SKILL_DIR, product.referenceFile);
+        if (!fs.existsSync(refPath)) {
+            error(key, `Reference file not found: ${product.referenceFile} (looked at ${refPath})`);
+        }
+    }
+    // 3. docKey exists in DOCS_INDEX
+    if (!(product.docKey in DOCS_INDEX)) {
+        error(key, `Unknown docKey "${product.docKey}" — available: ${Object.keys(DOCS_INDEX).join(', ')}`);
+    }
+    // 4. minimumPlan is valid
+    if (!(product.minimumPlan in PLAN_RANK)) {
+        error(key, `Unknown plan "${product.minimumPlan}" in PLAN_RANK`);
+    }
+    if (!(product.minimumPlan in HELIUS_PLANS)) {
+        error(key, `Plan "${product.minimumPlan}" not found in HELIUS_PLANS`);
+    }
+    // 5. Plan-feature compatibility
+    const nameLower = product.name.toLowerCase();
+    if (nameLower.includes('laserstream') && nameLower.includes('mainnet') && product.minimumPlan !== 'professional') {
+        error(key, `Laserstream mainnet requires professional plan, but has "${product.minimumPlan}"`);
+    }
+    if (nameLower.includes('enhanced websocket') && (PLAN_RANK[product.minimumPlan] ?? 0) < PLAN_RANK['business']) {
+        error(key, `Enhanced WebSockets requires business+ plan, but has "${product.minimumPlan}"`);
+    }
+    // 6. No empty mcpTools
+    if (product.mcpTools.length === 0) {
+        error(key, 'mcpTools array is empty');
+    }
+}
+// ── Report ──
+if (errors.length > 0) {
+    console.error(`\n\u274C Catalog validation failed with ${errors.length} error(s):\n`);
+    for (const err of errors) {
+        console.error(`  \u2022 ${err}`);
+    }
+    console.error('');
+    process.exit(1);
+}
+else {
+    const productCount = Object.keys(PRODUCT_CATALOG).length;
+    console.log(`\u2705 All products valid (${productCount} products in catalog)`);
+}