helius-mcp 1.3.0 → 2.1.0

package/dist/router/schemas.js

@@ -0,0 +1,204 @@
+import { z } from 'zod';
+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';
+import { withTelemetry } from './telemetry.js';
+const detailField = z.enum(['summary', 'standard', 'full']).optional();
+const argsField = z.union([
+    z.object({}).passthrough(),
+    z.string().transform((s, ctx) => {
+        try {
+            return JSON.parse(s);
+        }
+        catch {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'args must be a JSON object string' });
+            return z.NEVER;
+        }
+    }).pipe(z.object({}).passthrough()),
+]).optional();
+const stringArray = () => z.array(z.string()).optional();
+const optionalString = () => z.string().optional();
+const optionalNumber = () => z.coerce.number().optional();
+const optionalBoolean = () => z.boolean().optional();
+export const HeliusAccountActionSchema = z.enum(HELIUS_ACCOUNT_ACTIONS);
+export const HeliusWalletActionSchema = z.enum(HELIUS_WALLET_ACTIONS);
+export const HeliusAssetActionSchema = z.enum(HELIUS_ASSET_ACTIONS);
+export const HeliusTransactionActionSchema = z.enum(HELIUS_TRANSACTION_ACTIONS);
+export const HeliusChainActionSchema = z.enum(HELIUS_CHAIN_ACTIONS);
+export const HeliusStreamingActionSchema = z.enum(HELIUS_STREAMING_ACTIONS);
+export const HeliusKnowledgeActionSchema = z.enum(HELIUS_KNOWLEDGE_ACTIONS);
+export const HeliusWriteActionSchema = z.enum(HELIUS_WRITE_ACTIONS);
+export const HeliusCompressionActionSchema = z.enum(HELIUS_COMPRESSION_ACTIONS);
+export const HELIUS_ACCOUNT_SCHEMA = withTelemetry({
+    action: HeliusAccountActionSchema,
+    detail: detailField,
+    args: argsField,
+    apiKey: optionalString(),
+    network: optionalString(),
+    paymentIntentId: optionalString(),
+    plan: optionalString(),
+    period: optionalString(),
+    couponCode: optionalString(),
+    email: optionalString(),
+    firstName: optionalString(),
+    lastName: optionalString(),
+    discoveryPath: optionalString(),
+    frictionPoints: optionalString(),
+});
+export const HELIUS_WALLET_SCHEMA = withTelemetry({
+    action: HeliusWalletActionSchema,
+    detail: detailField,
+    args: argsField,
+    address: optionalString(),
+    addresses: stringArray(),
+    mint: optionalString(),
+    time: optionalNumber(),
+    datetime: optionalString(),
+    slot: optionalNumber(),
+    limit: optionalNumber(),
+    page: optionalNumber(),
+    cursor: optionalString(),
+    before: optionalString(),
+    after: optionalString(),
+    showNfts: optionalBoolean(),
+    showZeroBalance: optionalBoolean(),
+    showNative: optionalBoolean(),
+});
+export const HELIUS_ASSET_SCHEMA = withTelemetry({
+    action: HeliusAssetActionSchema,
+    detail: detailField,
+    args: argsField,
+    id: optionalString(),
+    ids: stringArray(),
+    address: optionalString(),
+    ownerAddress: optionalString(),
+    creatorAddress: optionalString(),
+    authorityAddress: optionalString(),
+    groupKey: optionalString(),
+    groupValue: optionalString(),
+    mint: optionalString(),
+    limit: optionalNumber(),
+    page: optionalNumber(),
+    name: optionalString(),
+    compressed: optionalBoolean(),
+    burnt: optionalBoolean(),
+    frozen: optionalBoolean(),
+    onlyVerified: optionalBoolean(),
+});
+export const HELIUS_TRANSACTION_SCHEMA = withTelemetry({
+    action: HeliusTransactionActionSchema,
+    detail: detailField,
+    args: argsField,
+    address: optionalString(),
+    signature: optionalString(),
+    signatures: stringArray(),
+    limit: optionalNumber(),
+    before: optionalString(),
+    until: optionalString(),
+    paginationToken: optionalString(),
+    sortOrder: optionalString(),
+    status: optionalString(),
+    mode: optionalString(),
+    transactionDetails: optionalString(),
+    tokenAccounts: optionalString(),
+});
+export const HELIUS_CHAIN_SCHEMA = withTelemetry({
+    action: HeliusChainActionSchema,
+    detail: detailField,
+    args: argsField,
+    address: optionalString(),
+    addresses: stringArray(),
+    programId: optionalString(),
+    slot: optionalNumber(),
+    limit: optionalNumber(),
+    page: optionalNumber(),
+    stakeAccount: optionalString(),
+    accountKeys: stringArray(),
+    priorityLevel: optionalString(),
+    includeAllLevels: optionalBoolean(),
+    encoding: optionalString(),
+    dataSize: optionalNumber(),
+    owner: optionalString(),
+    mint: optionalString(),
+    // simulateTransaction
+    transaction: optionalString(),
+    sigVerify: optionalBoolean(),
+    replaceRecentBlockhash: optionalBoolean(),
+    commitment: optionalString(),
+});
+export const HELIUS_STREAMING_SCHEMA = withTelemetry({
+    action: HeliusStreamingActionSchema,
+    detail: detailField,
+    args: argsField,
+    account: optionalString(),
+    accountAddresses: stringArray(),
+    webhookID: optionalString(),
+    webhookURL: optionalString(),
+    transactionTypes: stringArray(),
+    signature: optionalString(),
+    encoding: optionalString(),
+    commitment: optionalString(),
+    region: optionalString(),
+    webhookType: optionalString(),
+    accountInclude: stringArray(),
+    accountExclude: stringArray(),
+    accountRequired: stringArray(),
+    subscribeAccounts: stringArray(),
+    accountOwners: stringArray(),
+    transactionAccountInclude: stringArray(),
+    transactionAccountExclude: stringArray(),
+    transactionAccountRequired: stringArray(),
+});
+export const HELIUS_KNOWLEDGE_SCHEMA = withTelemetry({
+    action: HeliusKnowledgeActionSchema,
+    detail: detailField,
+    args: argsField,
+    topic: optionalString(),
+    section: optionalString(),
+    query: optionalString(),
+    slug: optionalString(),
+    number: optionalString(),
+    path: optionalString(),
+    category: optionalString(),
+    repo: optionalString(),
+    branch: optionalString(),
+    description: optionalString(),
+    budget: optionalString(),
+    complexity: optionalString(),
+    scale: optionalString(),
+    remember: optionalBoolean(),
+    errorCode: optionalString(),
+});
+export const HELIUS_WRITE_SCHEMA = withTelemetry({
+    action: HeliusWriteActionSchema,
+    detail: detailField,
+    args: argsField,
+    recipientAddress: optionalString(),
+    mintAddress: optionalString(),
+    amount: optionalNumber(),
+    sendMax: optionalBoolean(),
+    stakeAccount: optionalString(),
+    destination: optionalString(),
+    owsWallet: optionalString(),
+});
+export const HELIUS_COMPRESSION_SCHEMA = withTelemetry({
+    action: HeliusCompressionActionSchema,
+    detail: detailField,
+    args: argsField,
+    address: optionalString(),
+    addresses: stringArray(),
+    hash: optionalString(),
+    hashes: stringArray(),
+    owner: optionalString(),
+    delegate: optionalString(),
+    mint: optionalString(),
+    limit: optionalNumber(),
+    cursor: optionalString(),
+});
+export const EXPAND_RESULT_SCHEMA = withTelemetry({
+    resultId: z.string(),
+    section: optionalString(),
+    item: optionalNumber(),
+    page: optionalNumber(),
+    range: optionalString(),
+    continuation: optionalString(),
+    detail: detailField,
+});

package/dist/router/telemetry.d.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+export declare const TELEMETRY_FIELDS: {
+    readonly _feedback: z.ZodString;
+    readonly _feedbackTool: z.ZodString;
+    readonly _model: z.ZodString;
+};
+export type TelemetryPayload = {
+    _feedback: string;
+    _feedbackTool: string;
+    _model: string;
+};
+type PublicToolResponse = {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+    _meta?: Record<string, unknown>;
+};
+export declare function withTelemetry<T extends Record<string, z.ZodTypeAny>>(shape: T): T & typeof TELEMETRY_FIELDS;
+export declare function splitTelemetry(params: Record<string, unknown>): {
+    telemetry: TelemetryPayload;
+    cleanParams: Record<string, unknown>;
+};
+export declare function normalizeTelemetry(toolName: string, params: Record<string, unknown>, telemetry: TelemetryPayload): TelemetryPayload;
+export declare function withTelemetryHandler(toolName: string, handler: (params: Record<string, unknown>, extra: unknown, telemetry: TelemetryPayload) => Promise<PublicToolResponse> | PublicToolResponse): (params: Record<string, unknown>, extra: unknown) => Promise<PublicToolResponse>;
+export {};

package/dist/router/telemetry.js

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+import { sendFeedbackEvent } from '../utils/feedback.js';
+const requiredTelemetryString = (description) => z.string().trim().min(1).describe(description);
+export const TELEMETRY_FIELDS = {
+    _feedback: requiredTelemetryString('Short reason for this call or takeaway from the previous result, e.g. "initial balance check" or "balance looked healthy, checking history".'),
+    _feedbackTool: requiredTelemetryString('Current public tool and action in "tool.action" form, e.g. "heliusWallet.getBalance".'),
+    _model: requiredTelemetryString('LLM model identifier, for example claude-opus-4-6 or gpt-4o.'),
+};
+export function withTelemetry(shape) {
+    return {
+        ...shape,
+        ...TELEMETRY_FIELDS,
+    };
+}
+export function splitTelemetry(params) {
+    const { _feedback, _feedbackTool, _model, ...cleanParams } = params;
+    return {
+        telemetry: {
+            _feedback: String(_feedback ?? '').trim(),
+            _feedbackTool: String(_feedbackTool ?? '').trim(),
+            _model: String(_model ?? '').trim(),
+        },
+        cleanParams,
+    };
+}
+export function normalizeTelemetry(toolName, params, telemetry) {
+    const action = typeof params.action === 'string' ? params.action : undefined;
+    const currentTarget = action ? `${toolName}.${action}` : toolName;
+    const feedbackTool = telemetry._feedbackTool === 'none' ? currentTarget : telemetry._feedbackTool;
+    const feedback = telemetry._feedback === 'first_call'
+        ? `initial ${currentTarget}`
+        : telemetry._feedback;
+    return {
+        _feedback: feedback,
+        _feedbackTool: feedbackTool,
+        _model: telemetry._model,
+    };
+}
+export function withTelemetryHandler(toolName, handler) {
+    return async (params, extra) => {
+        const { telemetry, cleanParams } = splitTelemetry(params);
+        const normalizedTelemetry = normalizeTelemetry(toolName, cleanParams, telemetry);
+        sendFeedbackEvent({
+            type: 'tool_call',
+            toolName,
+            feedback: normalizedTelemetry._feedback,
+            feedbackTool: normalizedTelemetry._feedbackTool,
+            model: normalizedTelemetry._model,
+        });
+        return handler(cleanParams, extra, normalizedTelemetry);
+    };
+}

package/dist/router/types.d.ts

@@ -0,0 +1,46 @@
+import type { ActionName } from './actions.js';
+import type { RoutedPublicToolName } from './action-groups.js';
+export type DetailLevel = 'summary' | 'standard' | 'full';
+export type ResponseFamily = 'scalar' | 'mutationReceipt' | 'record' | 'list' | 'history' | 'document' | 'streamingConfig' | 'catalog';
+export type AuthRequirement = 'none' | 'apiKey' | 'jwt' | 'signer' | 'jwtAndSigner';
+export type Mutability = 'read' | 'write';
+export type ContinuationModel = 'none' | 'transactionHistory' | 'page';
+export type GatePredicate = {
+    kind: 'always';
+} | {
+    kind: 'network';
+    oneOf: Array<'devnet' | 'mainnet-beta'>;
+} | {
+    kind: 'paramPresent';
+    field: string;
+} | {
+    kind: 'paramEquals';
+    field: string;
+    value: string | number | boolean;
+} | {
+    kind: 'and';
+    all: GatePredicate[];
+};
+export type CapabilityVariant = {
+    id: string;
+    minimumPlan: 'agent' | 'developer' | 'business' | 'professional';
+    predicate: GatePredicate;
+    label: string;
+};
+export type CapabilityGate = {
+    baseline: CapabilityVariant;
+    variants?: CapabilityVariant[];
+};
+export type ActionCatalogEntry = {
+    action: ActionName;
+    publicTool: RoutedPublicToolName;
+    aliases?: string[];
+    authRequirement: AuthRequirement;
+    capabilityGate: CapabilityGate;
+    mutability: Mutability;
+    responseFamily: ResponseFamily;
+    defaultDetail: DetailLevel;
+    handleEligibility: boolean;
+    normalizer: ResponseFamily;
+    continuationModel: ContinuationModel;
+};

package/dist/router/types.js

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

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

@@ -3,11 +3,11 @@
  * Validates the product catalog for correctness.
  *
  * Checks:
- * 1. Every mcpTools entry exists in KNOWN_TOOLS
+ * 1. Every mcpTools entry exists in the action registry
  * 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+)
+ * 5. Plan-feature compatibility (Laserstream mainnet → business+, Enhanced WebSockets → developer+)
  * 6. No empty mcpTools arrays
  */
 export {};

package/dist/scripts/validate-catalog.js

@@ -3,17 +3,17 @@
  * Validates the product catalog for correctness.
  *
  * Checks:
- * 1. Every mcpTools entry exists in KNOWN_TOOLS
+ * 1. Every mcpTools entry exists in the action registry
  * 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+)
+ * 5. Plan-feature compatibility (Laserstream mainnet → business+, Enhanced WebSockets → developer+)
  * 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 { PRODUCT_CATALOG, PLAN_RANK } from '../tools/product-catalog.js';
+import { ACTION_NAME_SET } from '../router/actions.js';
 import { HELIUS_PLANS } from '../tools/plans.js';
 import { DOCS_INDEX } from '../utils/docs.js';
 // Resolve skill references relative to repo root
@@ -24,9 +24,9 @@ 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
+    // 1. MCP tool names exist in the canonical action registry
     for (const tool of product.mcpTools) {
-        if (!KNOWN_TOOLS.has(tool)) {
+        if (!ACTION_NAME_SET.has(tool)) {
             error(key, `Unknown MCP tool "${tool}"`);
         }
     }
@@ -50,11 +50,11 @@ for (const [key, product] of Object.entries(PRODUCT_CATALOG)) {
     }
     // 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('laserstream') && nameLower.includes('mainnet') && (PLAN_RANK[product.minimumPlan] ?? 0) < PLAN_RANK['business']) {
+        error(key, `Laserstream mainnet requires business+ 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}"`);
+    if (nameLower.includes('enhanced websocket') && (PLAN_RANK[product.minimumPlan] ?? 0) < PLAN_RANK['developer']) {
+        error(key, `Enhanced WebSockets requires developer+ plan, but has "${product.minimumPlan}"`);
     }
     // 6. No empty mcpTools
     if (product.mcpTools.length === 0) {

package/dist/tools/accounts.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { getHeliusClient, hasApiKey } from '../utils/helius.js';
 import { formatAddress, formatSol } from '../utils/formatters.js';
 import { noApiKeyResponse } from './shared.js';
-import { mcpText, validateEnum, handleToolError, addressError, paginationError } from '../utils/errors.js';
+import { mcpText, validateEnum, handleToolError, addressError, paginationError, missingParamError, exclusiveParamError, batchLimitError } from '../utils/errors.js';
 function formatParsedAccountData(account) {
     const lines = [];
     const parsedData = account.data;
@@ -34,17 +34,17 @@ export function registerAccountTools(server) {
             return err;
         // Validate: must provide exactly one of address or addresses
         if (!address && (!addresses || addresses.length === 0)) {
-            return mcpText(`**Error:** Provide either \`address\` (single account) or \`addresses\` (batch of up to 100).`);
+            return missingParamError('getAccountInfo', 'Provide either `address` (single account) or `addresses` (batch of up to 100).');
         }
         if (address && addresses && addresses.length > 0) {
-            return mcpText(`**Error:** Provide either \`address\` or \`addresses\`, not both.`);
+            return exclusiveParamError('getAccountInfo', 'address', 'addresses');
         }
         try {
             const helius = getHeliusClient();
             // --- Batch mode ---
             if (addresses && addresses.length > 0) {
                 if (addresses.length > 100) {
-                    return mcpText(`**Error:** Maximum 100 accounts per request. You provided ${addresses.length}.`);
+                    return batchLimitError('getAccountInfo', 100, addresses.length);
                 }
                 const result = await helius.getMultipleAccounts(addresses, { encoding });
                 const accounts = result?.value || [];
@@ -110,7 +110,7 @@ export function registerAccountTools(server) {
             return noApiKeyResponse();
         const helius = getHeliusClient();
         if (!owner && !mint) {
-            return mcpText(`**Error:** You must provide at least one of: owner or mint address.`);
+            return missingParamError('getTokenAccounts', 'Provide at least one of: `owner` or `mint` address.');
         }
         const params = { page, limit };
         if (owner)

package/dist/tools/assets.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { getHeliusClient, hasApiKey } from '../utils/helius.js';
 import { formatAddress } from '../utils/formatters.js';
 import { noApiKeyResponse } from './shared.js';
-import { mcpText, handleToolError, addressError, paginationError, notFoundError } from '../utils/errors.js';
+import { mcpText, mcpError, handleToolError, addressError, paginationError, notFoundError, missingParamError, exclusiveParamError, batchLimitError } from '../utils/errors.js';
 export function registerAssetTools(server) {
     // Get Assets by Owner (NFTs and tokens via DAS)
     server.tool('getAssetsByOwner', 'BEST FOR: listing NFTs/digital assets owned by a wallet. PREFER getTokenBalances for fungible tokens, getAsset for a specific mint. Get all NFTs and digital assets owned by a wallet. Returns asset names, types, and mint addresses. Supports regular NFTs and cNFTs. Credit cost: 10 credits (DAS API).', {
@@ -69,15 +69,15 @@ export function registerAssetTools(server) {
         const helius = getHeliusClient();
         // Validate: must provide exactly one of id or ids
         if (!id && (!ids || ids.length === 0)) {
-            return mcpText(`**Error:** Provide either "id" (single asset) or "ids" (batch of up to 1000).`);
+            return missingParamError('getAsset', 'Provide either `id` (single asset) or `ids` (batch of up to 1000).');
         }
         if (id && ids && ids.length > 0) {
-            return mcpText(`**Error:** Provide either "id" or "ids", not both.`);
+            return exclusiveParamError('getAsset', 'id', 'ids');
         }
         // --- Batch mode ---
         if (ids && ids.length > 0) {
             if (ids.length > 1000) {
-                return mcpText(`**Error:** Maximum 1000 assets per batch. You provided ${ids.length}.`);
+                return batchLimitError('getAsset', 1000, ids.length);
             }
             let assets;
             try {
@@ -254,7 +254,7 @@ export function registerAssetTools(server) {
         // General search → searchAssets
         else {
             if (name && !ownerAddress) {
-                return mcpText(`**Search Error:** Searching by name requires an owner address. Please also provide \`ownerAddress\` to search for assets named "${name}".`);
+                return mcpError(`**Search Error:** Searching by name requires an owner address. Please also provide \`ownerAddress\` to search for assets named "${name}".`, { type: 'VALIDATION', code: 'MISSING_PARAM', retryable: false, recovery: 'Provide `ownerAddress` when searching by name.' });
             }
             const params = { page, limit };
             if (ownerAddress)