helius-mcp 1.3.0 → 2.0.0

package/dist/results/store.js

@@ -0,0 +1,72 @@
+import { randomUUID } from 'node:crypto';
+const MAX_RESULTS = 10;
+const MAX_TOTAL_PAYLOAD_BYTES = 250 * 1024;
+const RESULT_TTL_MS = 5 * 60 * 1000;
+const results = new Map();
+function estimateBytes(value) {
+    return Buffer.byteLength(JSON.stringify(value), 'utf8');
+}
+function sweepExpired(now = Date.now()) {
+    for (const [resultId, result] of results) {
+        if (result.expiresAt <= now) {
+            results.delete(resultId);
+        }
+    }
+}
+function currentTotalBytes() {
+    let total = 0;
+    for (const result of results.values()) {
+        total += result.payloadSize;
+    }
+    return total;
+}
+function touch(resultId, result) {
+    results.delete(resultId);
+    results.set(resultId, result);
+}
+function evictToFit() {
+    sweepExpired();
+    while (results.size > MAX_RESULTS || currentTotalBytes() > MAX_TOTAL_PAYLOAD_BYTES) {
+        const oldest = results.keys().next().value;
+        if (!oldest) {
+            break;
+        }
+        results.delete(oldest);
+    }
+}
+export function putStoredResult(input) {
+    const createdAt = Date.now();
+    const payloadSize = estimateBytes(input.payload);
+    const stored = {
+        ...input,
+        resultId: randomUUID(),
+        createdAt,
+        expiresAt: createdAt + RESULT_TTL_MS,
+        payloadSize,
+    };
+    results.set(stored.resultId, stored);
+    evictToFit();
+    return stored;
+}
+export function getStoredResult(resultId, ownerSessionKey) {
+    sweepExpired();
+    const result = results.get(resultId);
+    if (!result) {
+        return null;
+    }
+    if (result.ownerSessionKey !== ownerSessionKey) {
+        return null;
+    }
+    touch(resultId, result);
+    return result;
+}
+export function clearStoredResults() {
+    results.clear();
+}
+export function getStoredResultStats() {
+    sweepExpired();
+    return {
+        count: results.size,
+        totalPayloadBytes: currentTotalBytes(),
+    };
+}

package/dist/results/types.d.ts

@@ -0,0 +1,47 @@
+import type { RoutedPublicToolName } from '../router/action-groups.js';
+import type { ActionName } from '../router/actions.js';
+import type { DetailLevel, ResponseFamily } from '../router/types.js';
+export type TransactionHistoryContinuation = {
+    kind: 'signaturesQuick';
+    nextBefore?: string;
+    lastSeenSignature?: string;
+    until?: string;
+} | {
+    kind: 'historyApi';
+    paginationToken?: string;
+} | {
+    kind: 'rawApi';
+    paginationToken?: string;
+};
+export type ContinuationState = {
+    model: 'none';
+} | {
+    model: 'page';
+    nextPage?: number;
+} | {
+    model: 'transactionHistory';
+    next?: TransactionHistoryContinuation;
+};
+export type ActionRecipe = {
+    publicTool: RoutedPublicToolName;
+    action: ActionName;
+    params: Record<string, unknown>;
+    responseFamily: ResponseFamily;
+    defaultDetail: DetailLevel;
+};
+export type ResultPayload = {
+    recipe: ActionRecipe;
+    continuation: ContinuationState;
+    sectionHints?: string[];
+};
+export type StoredResult = {
+    resultId: string;
+    kind: ResponseFamily;
+    ownerSessionKey: string;
+    summary: string;
+    availableExpansions: string[];
+    createdAt: number;
+    expiresAt: number;
+    payload: ResultPayload;
+    payloadSize: number;
+};

package/dist/results/types.js

@@ -0,0 +1 @@
+export {};

package/dist/router/action-groups.d.ts

@@ -0,0 +1,6 @@
+import { type ActionName } from './actions.js';
+export declare const PUBLIC_TOOL_NAMES: readonly ["heliusAccount", "heliusWallet", "heliusAsset", "heliusTransaction", "heliusChain", "heliusStreaming", "heliusKnowledge", "heliusWrite", "heliusCompression", "expandResult"];
+export type PublicToolName = typeof PUBLIC_TOOL_NAMES[number];
+export type RoutedPublicToolName = Exclude<PublicToolName, 'expandResult'>;
+export declare const ACTION_GROUPS: Record<RoutedPublicToolName, readonly ActionName[]>;
+export declare function findPublicToolForAction(action: ActionName): RoutedPublicToolName;

package/dist/router/action-groups.js

@@ -0,0 +1,32 @@
+import { HELIUS_ACCOUNT_ACTIONS, HELIUS_ASSET_ACTIONS, HELIUS_CHAIN_ACTIONS, HELIUS_COMPRESSION_ACTIONS, HELIUS_KNOWLEDGE_ACTIONS, HELIUS_STREAMING_ACTIONS, HELIUS_TRANSACTION_ACTIONS, HELIUS_WALLET_ACTIONS, HELIUS_WRITE_ACTIONS, } from './actions.js';
+export const PUBLIC_TOOL_NAMES = [
+    'heliusAccount',
+    'heliusWallet',
+    'heliusAsset',
+    'heliusTransaction',
+    'heliusChain',
+    'heliusStreaming',
+    'heliusKnowledge',
+    'heliusWrite',
+    'heliusCompression',
+    'expandResult',
+];
+export const ACTION_GROUPS = {
+    heliusAccount: HELIUS_ACCOUNT_ACTIONS,
+    heliusWallet: HELIUS_WALLET_ACTIONS,
+    heliusAsset: HELIUS_ASSET_ACTIONS,
+    heliusTransaction: HELIUS_TRANSACTION_ACTIONS,
+    heliusChain: HELIUS_CHAIN_ACTIONS,
+    heliusStreaming: HELIUS_STREAMING_ACTIONS,
+    heliusKnowledge: HELIUS_KNOWLEDGE_ACTIONS,
+    heliusWrite: HELIUS_WRITE_ACTIONS,
+    heliusCompression: HELIUS_COMPRESSION_ACTIONS,
+};
+export function findPublicToolForAction(action) {
+    for (const [tool, actions] of Object.entries(ACTION_GROUPS)) {
+        if (actions.includes(action)) {
+            return tool;
+        }
+    }
+    throw new Error(`No public tool mapping found for action "${action}"`);
+}

package/dist/router/action-handlers.d.ts

@@ -0,0 +1,20 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ActionName } from './actions.js';
+export type ActionHandlerResponse = {
+    content?: Array<{
+        type?: string;
+        text?: string;
+    }>;
+    isError?: boolean;
+    structuredContent?: unknown;
+};
+export type ActionHandler = (params: Record<string, unknown>, extra: unknown) => Promise<ActionHandlerResponse> | ActionHandlerResponse;
+export type ActionHandlerDefinition = {
+    name: ActionName;
+    description?: string;
+    inputSchema?: unknown;
+    handler: ActionHandler;
+};
+export declare function registerActionHandlers(server: McpServer): void;
+export declare function getActionHandlers(): Map<ActionName, ActionHandlerDefinition>;
+export declare function callActionHandler(action: ActionName, params: Record<string, unknown>, extra: unknown): Promise<ActionHandlerResponse>;

package/dist/router/action-handlers.js

@@ -0,0 +1,125 @@
+import { z } from 'zod';
+import { registerAuthTools } from '../tools/auth.js';
+import { registerConfigTools } from '../tools/config.js';
+import { registerPlanTools } from '../tools/plans.js';
+import { registerBalanceTools } from '../tools/balance.js';
+import { registerTransactionTools } from '../tools/transactions.js';
+import { registerAssetTools } from '../tools/assets.js';
+import { registerAccountTools } from '../tools/accounts.js';
+import { registerFeeTools } from '../tools/fees.js';
+import { registerNetworkTools } from '../tools/network.js';
+import { registerBlockTools } from '../tools/blocks.js';
+import { registerTokenTools } from '../tools/tokens.js';
+import { registerDasExtraTools } from '../tools/das-extras.js';
+import { registerWebhookTools } from '../tools/webhooks.js';
+import { registerEnhancedWebSocketTools } from '../tools/enhanced-websockets.js';
+import { registerLaserstreamTools } from '../tools/laserstream.js';
+import { registerWalletTools } from '../tools/wallet.js';
+import { registerDocsTools } from '../tools/docs.js';
+import { registerGuideTools } from '../tools/guides.js';
+import { registerRecommendTools } from '../tools/recommend.js';
+import { registerSolanaKnowledgeTools } from '../tools/solana-knowledge.js';
+import { registerTransferTools } from '../tools/transfers.js';
+import { registerZkCompressionTools } from '../tools/zk-compression.js';
+import { registerStakingTools } from '../tools/staking.js';
+function isZodType(value) {
+    return typeof value === 'object' && value !== null && typeof value.safeParse === 'function';
+}
+function buildRuntimeSchema(inputSchema) {
+    if (isZodType(inputSchema) && 'passthrough' in inputSchema && typeof inputSchema.passthrough === 'function') {
+        return inputSchema.passthrough();
+    }
+    if (!inputSchema || typeof inputSchema !== 'object' || Array.isArray(inputSchema)) {
+        return null;
+    }
+    const rawShape = {};
+    for (const [key, value] of Object.entries(inputSchema)) {
+        if (isZodType(value)) {
+            rawShape[key] = value;
+        }
+    }
+    if (Object.keys(rawShape).length === 0) {
+        return null;
+    }
+    return z.object(rawShape).passthrough();
+}
+function materializeActionParams(tool, params) {
+    const schema = buildRuntimeSchema(tool.inputSchema);
+    if (!schema) {
+        return params;
+    }
+    const parsed = schema.safeParse(params);
+    if (parsed.success) {
+        return parsed.data;
+    }
+    const issue = parsed.error.issues[0];
+    const path = issue?.path?.length ? issue.path.join('.') : 'input';
+    const message = `Invalid parameters for ${tool.name}: ${path} ${issue?.message ?? 'is invalid'}`.trim();
+    throw new Error(message);
+}
+class ActionHandlerCollector {
+    tools = new Map();
+    tool(name, ...rest) {
+        let description;
+        let inputSchema;
+        if (typeof rest[0] === 'string') {
+            description = rest.shift();
+        }
+        if (rest.length > 1 && typeof rest[0] === 'object' && rest[0] !== null) {
+            inputSchema = rest.shift();
+        }
+        const handler = rest[0];
+        if (typeof handler !== 'function') {
+            throw new Error(`Action handler "${name}" is missing a callable handler`);
+        }
+        this.tools.set(name, {
+            name: name,
+            description,
+            inputSchema,
+            handler: handler,
+        });
+    }
+}
+let cachedActionHandlers = null;
+export function registerActionHandlers(server) {
+    registerAuthTools(server);
+    registerConfigTools(server);
+    registerPlanTools(server);
+    registerBalanceTools(server);
+    registerTransactionTools(server);
+    registerAssetTools(server);
+    registerAccountTools(server);
+    registerFeeTools(server);
+    registerNetworkTools(server);
+    registerBlockTools(server);
+    registerTokenTools(server);
+    registerDasExtraTools(server);
+    registerWebhookTools(server);
+    registerEnhancedWebSocketTools(server);
+    registerLaserstreamTools(server);
+    registerWalletTools(server);
+    registerDocsTools(server);
+    registerGuideTools(server);
+    registerRecommendTools(server);
+    registerSolanaKnowledgeTools(server);
+    registerTransferTools(server);
+    registerZkCompressionTools(server);
+    registerStakingTools(server);
+}
+export function getActionHandlers() {
+    if (cachedActionHandlers) {
+        return cachedActionHandlers;
+    }
+    const collector = new ActionHandlerCollector();
+    registerActionHandlers(collector);
+    cachedActionHandlers = collector.tools;
+    return cachedActionHandlers;
+}
+export async function callActionHandler(action, params, extra) {
+    const tool = getActionHandlers().get(action);
+    if (!tool) {
+        throw new Error(`No action handler registered for action "${action}"`);
+    }
+    const normalizedParams = materializeActionParams(tool, params);
+    return await Promise.resolve(tool.handler(normalizedParams, extra));
+}

package/dist/router/actions.d.ts

@@ -0,0 +1,12 @@
+export declare const HELIUS_ACCOUNT_ACTIONS: readonly ["getStarted", "setHeliusApiKey", "generateKeypair", "signup", "getAccountStatus", "getAccountPlan", "getHeliusPlanInfo", "compareHeliusPlans", "previewUpgrade", "upgradePlan", "payRenewal", "purchaseCredits"];
+export declare const HELIUS_WALLET_ACTIONS: readonly ["getBalance", "getTokenBalances", "getWalletBalances", "getWalletHistory", "getWalletTransfers", "getWalletIdentity", "batchWalletIdentity", "getWalletFundedBy"];
+export declare const HELIUS_ASSET_ACTIONS: readonly ["getAsset", "getAssetsByOwner", "searchAssets", "getAssetsByGroup", "getAssetProof", "getAssetProofBatch", "getSignaturesForAsset", "getNftEditions", "getTokenHolders"];
+export declare const HELIUS_TRANSACTION_ACTIONS: readonly ["parseTransactions", "getTransactionHistory", "getTransfersByAddress"];
+export declare const HELIUS_CHAIN_ACTIONS: readonly ["getAccountInfo", "getTokenAccounts", "getProgramAccounts", "getBlock", "getNetworkStatus", "getPriorityFeeEstimate", "getStakeAccounts", "getWithdrawableAmount"];
+export declare const HELIUS_STREAMING_ACTIONS: readonly ["createWebhook", "getAllWebhooks", "getWebhookByID", "updateWebhook", "deleteWebhook", "transactionSubscribe", "accountSubscribe", "laserstreamSubscribe"];
+export declare const HELIUS_KNOWLEDGE_ACTIONS: readonly ["lookupHeliusDocs", "listHeliusDocTopics", "getHeliusCreditsInfo", "getRateLimitInfo", "troubleshootError", "recommendStack", "getSIMD", "listSIMDs", "searchSolanaDocs", "readSolanaSourceFile", "fetchHeliusBlog", "getPumpFunGuide", "getSenderInfo", "getWebhookGuide", "getLatencyComparison", "getEnhancedWebSocketInfo", "getLaserstreamInfo"];
+export declare const HELIUS_WRITE_ACTIONS: readonly ["transferSol", "transferToken", "stakeSOL", "unstakeSOL", "withdrawStake"];
+export declare const HELIUS_COMPRESSION_ACTIONS: readonly ["getCompressedAccount", "getCompressedAccountsByOwner", "getMultipleCompressedAccounts", "getCompressedBalance", "getCompressedBalanceByOwner", "getCompressedMintTokenHolders", "getCompressedTokenAccountBalance", "getCompressedTokenAccountsByOwner", "getCompressedTokenAccountsByDelegate", "getCompressedTokenBalancesByOwnerV2", "getCompressedAccountProof", "getMultipleCompressedAccountProofs", "getMultipleNewAddressProofs", "getCompressionSignaturesForAccount", "getCompressionSignaturesForAddress", "getCompressionSignaturesForOwner", "getCompressionSignaturesForTokenOwner", "getLatestCompressionSignatures", "getLatestNonVotingSignatures", "getTransactionWithCompressionInfo", "getValidityProof", "getIndexerHealth", "getIndexerSlot"];
+export declare const ACTION_NAMES: readonly ["getStarted", "setHeliusApiKey", "generateKeypair", "signup", "getAccountStatus", "getAccountPlan", "getHeliusPlanInfo", "compareHeliusPlans", "previewUpgrade", "upgradePlan", "payRenewal", "purchaseCredits", "getBalance", "getTokenBalances", "getWalletBalances", "getWalletHistory", "getWalletTransfers", "getWalletIdentity", "batchWalletIdentity", "getWalletFundedBy", "getAsset", "getAssetsByOwner", "searchAssets", "getAssetsByGroup", "getAssetProof", "getAssetProofBatch", "getSignaturesForAsset", "getNftEditions", "getTokenHolders", "parseTransactions", "getTransactionHistory", "getTransfersByAddress", "getAccountInfo", "getTokenAccounts", "getProgramAccounts", "getBlock", "getNetworkStatus", "getPriorityFeeEstimate", "getStakeAccounts", "getWithdrawableAmount", "createWebhook", "getAllWebhooks", "getWebhookByID", "updateWebhook", "deleteWebhook", "transactionSubscribe", "accountSubscribe", "laserstreamSubscribe", "lookupHeliusDocs", "listHeliusDocTopics", "getHeliusCreditsInfo", "getRateLimitInfo", "troubleshootError", "recommendStack", "getSIMD", "listSIMDs", "searchSolanaDocs", "readSolanaSourceFile", "fetchHeliusBlog", "getPumpFunGuide", "getSenderInfo", "getWebhookGuide", "getLatencyComparison", "getEnhancedWebSocketInfo", "getLaserstreamInfo", "transferSol", "transferToken", "stakeSOL", "unstakeSOL", "withdrawStake", "getCompressedAccount", "getCompressedAccountsByOwner", "getMultipleCompressedAccounts", "getCompressedBalance", "getCompressedBalanceByOwner", "getCompressedMintTokenHolders", "getCompressedTokenAccountBalance", "getCompressedTokenAccountsByOwner", "getCompressedTokenAccountsByDelegate", "getCompressedTokenBalancesByOwnerV2", "getCompressedAccountProof", "getMultipleCompressedAccountProofs", "getMultipleNewAddressProofs", "getCompressionSignaturesForAccount", "getCompressionSignaturesForAddress", "getCompressionSignaturesForOwner", "getCompressionSignaturesForTokenOwner", "getLatestCompressionSignatures", "getLatestNonVotingSignatures", "getTransactionWithCompressionInfo", "getValidityProof", "getIndexerHealth", "getIndexerSlot"];
+export type ActionName = typeof ACTION_NAMES[number];
+export declare const ACTION_NAME_SET: Set<string>;

package/dist/router/actions.js

@@ -0,0 +1,123 @@
+export const HELIUS_ACCOUNT_ACTIONS = [
+    'getStarted',
+    'setHeliusApiKey',
+    'generateKeypair',
+    'signup',
+    'getAccountStatus',
+    'getAccountPlan',
+    'getHeliusPlanInfo',
+    'compareHeliusPlans',
+    'previewUpgrade',
+    'upgradePlan',
+    'payRenewal',
+    'purchaseCredits',
+];
+export const HELIUS_WALLET_ACTIONS = [
+    'getBalance',
+    'getTokenBalances',
+    'getWalletBalances',
+    'getWalletHistory',
+    'getWalletTransfers',
+    'getWalletIdentity',
+    'batchWalletIdentity',
+    'getWalletFundedBy',
+];
+export const HELIUS_ASSET_ACTIONS = [
+    'getAsset',
+    'getAssetsByOwner',
+    'searchAssets',
+    'getAssetsByGroup',
+    'getAssetProof',
+    'getAssetProofBatch',
+    'getSignaturesForAsset',
+    'getNftEditions',
+    'getTokenHolders',
+];
+export const HELIUS_TRANSACTION_ACTIONS = [
+    'parseTransactions',
+    'getTransactionHistory',
+    'getTransfersByAddress',
+];
+export const HELIUS_CHAIN_ACTIONS = [
+    'getAccountInfo',
+    'getTokenAccounts',
+    'getProgramAccounts',
+    'getBlock',
+    'getNetworkStatus',
+    'getPriorityFeeEstimate',
+    'getStakeAccounts',
+    'getWithdrawableAmount',
+];
+export const HELIUS_STREAMING_ACTIONS = [
+    'createWebhook',
+    'getAllWebhooks',
+    'getWebhookByID',
+    'updateWebhook',
+    'deleteWebhook',
+    'transactionSubscribe',
+    'accountSubscribe',
+    'laserstreamSubscribe',
+];
+export const HELIUS_KNOWLEDGE_ACTIONS = [
+    'lookupHeliusDocs',
+    'listHeliusDocTopics',
+    'getHeliusCreditsInfo',
+    'getRateLimitInfo',
+    'troubleshootError',
+    'recommendStack',
+    'getSIMD',
+    'listSIMDs',
+    'searchSolanaDocs',
+    'readSolanaSourceFile',
+    'fetchHeliusBlog',
+    'getPumpFunGuide',
+    'getSenderInfo',
+    'getWebhookGuide',
+    'getLatencyComparison',
+    'getEnhancedWebSocketInfo',
+    'getLaserstreamInfo',
+];
+export const HELIUS_WRITE_ACTIONS = [
+    'transferSol',
+    'transferToken',
+    'stakeSOL',
+    'unstakeSOL',
+    'withdrawStake',
+];
+export const HELIUS_COMPRESSION_ACTIONS = [
+    'getCompressedAccount',
+    'getCompressedAccountsByOwner',
+    'getMultipleCompressedAccounts',
+    'getCompressedBalance',
+    'getCompressedBalanceByOwner',
+    'getCompressedMintTokenHolders',
+    'getCompressedTokenAccountBalance',
+    'getCompressedTokenAccountsByOwner',
+    'getCompressedTokenAccountsByDelegate',
+    'getCompressedTokenBalancesByOwnerV2',
+    'getCompressedAccountProof',
+    'getMultipleCompressedAccountProofs',
+    'getMultipleNewAddressProofs',
+    'getCompressionSignaturesForAccount',
+    'getCompressionSignaturesForAddress',
+    'getCompressionSignaturesForOwner',
+    'getCompressionSignaturesForTokenOwner',
+    'getLatestCompressionSignatures',
+    'getLatestNonVotingSignatures',
+    'getTransactionWithCompressionInfo',
+    'getValidityProof',
+    'getIndexerHealth',
+    'getIndexerSlot',
+];
+export const ACTION_NAMES = [
+    ...HELIUS_ACCOUNT_ACTIONS,
+    ...HELIUS_WALLET_ACTIONS,
+    ...HELIUS_ASSET_ACTIONS,
+    ...HELIUS_TRANSACTION_ACTIONS,
+    ...HELIUS_CHAIN_ACTIONS,
+    ...HELIUS_STREAMING_ACTIONS,
+    ...HELIUS_KNOWLEDGE_ACTIONS,
+    ...HELIUS_WRITE_ACTIONS,
+    ...HELIUS_COMPRESSION_ACTIONS,
+];
+export const ACTION_NAME_SET = new Set(ACTION_NAMES);

package/dist/router/catalog.d.ts

@@ -0,0 +1,6 @@
+import { type ActionName } from './actions.js';
+import { type RoutedPublicToolName } from './action-groups.js';
+import type { ActionCatalogEntry } from './types.js';
+export declare const ACTION_CATALOG: Record<ActionName, ActionCatalogEntry>;
+export declare function getActionCatalogEntry(action: ActionName): ActionCatalogEntry;
+export declare function getActionsForTool(tool: RoutedPublicToolName): ActionName[];