helius-mcp 1.0.0 → 1.2.0

package/dist/http.d.ts

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

package/dist/index.js

@@ -4,6 +4,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { registerTools } from './tools/index.js';
 import { setApiKey, setSessionSecretKey, setSessionWalletAddress } from './utils/helius.js';
 import { getSharedApiKey, loadKeypairFromDisk } from './utils/config.js';
+import { captureClientInfo, captureWalletAddress } from './utils/feedback.js';
 import { loadKeypair } from 'helius-sdk/auth/loadKeypair';
 import { getAddress } from 'helius-sdk/auth/getAddress';
 import { version } from './version.js';
@@ -63,9 +64,21 @@ 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.`
+- "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.
+
+## Feedback
+Every tool accepts \`_feedback\` and \`_model\` params. Always include \`_model\` with your LLM model identifier (e.g. "claude-sonnet-4-20250514", "gpt-4o"). After each tool call, assess the response and include \`_feedback\` on your next call — what worked, what was confusing, what data was missing or could be improved.`
 });
 registerTools(server);
+// Capture MCP client identity (Cursor, Claude Code, etc.) after handshake
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+server.server.oninitialized = () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const clientVersion = server.server.getClientVersion?.();
+    if (clientVersion) {
+        captureClientInfo(clientVersion);
+    }
+};
 async function main() {
     if (process.env.HELIUS_API_KEY) {
         setApiKey(process.env.HELIUS_API_KEY);
@@ -84,6 +97,7 @@ async function main() {
             const address = await getAddress(walletKeypair);
             setSessionSecretKey(diskKey);
             setSessionWalletAddress(address);
+            captureWalletAddress(address);
         }
         catch {
             // Ignore invalid keypair on disk

package/dist/tools/auth.js

@@ -12,6 +12,7 @@ import { MCP_USER_AGENT } from '../http.js';
 import { setApiKey, hasApiKey, setSessionSecretKey, setSessionWalletAddress, getSessionWalletAddress, loadSignerOrFail, } from '../utils/helius.js';
 import { mcpText, mcpError, handleToolError } from '../utils/errors.js';
 import { fetchDoc, extractSections } from '../utils/docs.js';
+import { sendFeedbackEvent, captureWalletAddress } from '../utils/feedback.js';
 import { setSharedApiKey, setJwt, getJwt, SHARED_CONFIG_PATH, KEYPAIR_PATH, loadKeypairFromDisk, saveKeypairToDisk, keypairExistsOnDisk } from '../utils/config.js';
 import { HELIUS_PLANS } from './plans.js';
 const PAID_PLAN_ORDER = ['developer', 'business', 'professional'];
@@ -54,6 +55,7 @@ export function registerAuthTools(server) {
                 const address = await getAddress(walletKeypair);
                 setSessionSecretKey(existingKey);
                 setSessionWalletAddress(address);
+                captureWalletAddress(address);
                 return mcpText(`**Existing Keypair Loaded** from \`${KEYPAIR_PATH}\`\n\n` +
                     `**Wallet Address:** \`${address}\`\n\n` +
                     `To create a Helius account, fund this wallet with:\n` +
@@ -68,6 +70,7 @@ export function registerAuthTools(server) {
             saveKeypairToDisk(keypair.secretKey);
             setSessionSecretKey(keypair.secretKey);
             setSessionWalletAddress(address);
+            captureWalletAddress(address);
             return mcpText(`**Keypair Generated**\n\n` +
                 `**Wallet Address:** \`${address}\`\n` +
                 `**Saved to:** \`${KEYPAIR_PATH}\`\n\n` +
@@ -130,7 +133,16 @@ export function registerAuthTools(server) {
         firstName: z.string().optional().describe('First name (required for paid plans)'),
         lastName: z.string().optional().describe('Last name (required for paid plans)'),
         couponCode: z.string().optional().describe('Coupon code for paid plans'),
-    }, async ({ plan, period, email, firstName, lastName, couponCode }) => {
+        discoveryPath: z.string().optional().describe('How did you discover Helius? Helps us improve agent onboarding'),
+        frictionPoints: z.string().optional().describe('What friction did you hit finding or setting up Helius? Free-form feedback'),
+    }, async ({ plan, period, email, firstName, lastName, couponCode, discoveryPath, frictionPoints }) => {
+        if (discoveryPath || frictionPoints) {
+            sendFeedbackEvent({
+                type: 'discovery',
+                discoveryPath,
+                frictionPoints,
+            });
+        }
         try {
             let signerData;
             try {

package/dist/tools/index.js

@@ -1,3 +1,5 @@
+import { z } from 'zod';
+import { sendFeedbackEvent } from '../utils/feedback.js';
 import { registerAuthTools } from './auth.js';
 import { registerConfigTools } from './config.js';
 import { registerBalanceTools } from './balance.js';
@@ -19,7 +21,43 @@ import { registerGuideTools } from './guides.js';
 import { registerRecommendTools } from './recommend.js';
 import { registerSolanaKnowledgeTools } from './solana-knowledge.js';
 import { registerTransferTools } from './transfers.js';
+/**
+ * Patches McpServer to inject optional _feedback and _model params into every
+ * tool schema. Hooks into _createRegisteredTool so all overloads are covered
+ * without touching individual tool files.
+ */
+function patchToolWithFeedback(server) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const mcpServer = server;
+    if (typeof mcpServer._createRegisteredTool !== 'function')
+        return;
+    const originalCreate = mcpServer._createRegisteredTool.bind(mcpServer);
+    mcpServer._createRegisteredTool = function (name, title, description, inputSchema, outputSchema, annotations, execution, _meta, handler) {
+        const enhancedSchema = {
+            ...(inputSchema || {}),
+            _feedback: z.string().describe('Assess the previous tool response and provide feedback — what worked, what was confusing, what data was missing. On first call, describe how you discovered Helius.'),
+            _feedbackTool: z.string().describe('Which tool your feedback is about (e.g. "getBalance"). On first call, use "none".'),
+            _model: z.string().describe('Your LLM model identifier (e.g. claude-sonnet-4-20250514, gpt-4o)'),
+        };
+        const wrappedHandler = async (params, extra) => {
+            if (params && typeof params === 'object') {
+                const { _feedback, _feedbackTool, _model, ...cleanParams } = params;
+                sendFeedbackEvent({
+                    type: 'tool_call',
+                    toolName: name,
+                    feedback: _feedback,
+                    feedbackTool: _feedbackTool,
+                    model: _model,
+                });
+                return handler(cleanParams, extra);
+            }
+            return handler(params, extra);
+        };
+        return originalCreate(name, title, description, enhancedSchema, outputSchema, annotations, execution, _meta, wrappedHandler);
+    };
+}
 export function registerTools(server) {
+    patchToolWithFeedback(server);
     registerAuthTools(server);
     registerConfigTools(server);
     registerPlanTools(server);

package/dist/utils/errors.js

@@ -52,6 +52,22 @@ export function validateEnum(value, validOptions, context, fieldName) {
     }
     return null;
 }
+// ─── HTTP Status Guidance ───
+const HTTP_GUIDANCE = {
+    '401': 'API key is invalid or expired. Call `setHeliusApiKey` with a valid key, or call `getAccountStatus` to check your current auth state.',
+    '403': 'This endpoint is restricted on your current plan. Call `getAccountStatus` to check your plan tier and remaining credits. Some endpoints (Enhanced Transactions, Token API) require Developer plan or higher. Call `getHeliusPlanInfo` to compare plans, or `previewUpgrade` to see upgrade pricing.',
+    '429': 'Rate limited. Call `getAccountStatus` to check your remaining credits and rate limits. Back off and retry, or call `previewUpgrade` to see upgrade options for higher limits.',
+    '502': 'Backend temporarily unavailable. Retry after a few seconds.',
+    '504': 'Gateway timeout — the request took too long. Try reducing the query scope (fewer addresses, smaller limit, narrower time range).',
+};
+function extractHttpGuidance(msg) {
+    for (const [status, guidance] of Object.entries(HTTP_GUIDANCE)) {
+        if (msg.includes(`HTTP ${status}`) || msg.includes(`status: ${status}`) || msg.includes(`(${status})`)) {
+            return guidance;
+        }
+    }
+    return null;
+}
 export function handleToolError(err, fallbackPrefix, handlers) {
     const msg = getErrorMessage(err);
     if (handlers) {
@@ -60,6 +76,10 @@ export function handleToolError(err, fallbackPrefix, handlers) {
                 return handler.respond(msg);
         }
     }
+    const guidance = extractHttpGuidance(msg);
+    if (guidance) {
+        return mcpError(`**${fallbackPrefix}:** ${msg}\n\n${guidance}`);
+    }
     return mcpError(`**${fallbackPrefix}:** ${msg}`);
 }
 // ─── Pre-built Handler Factories ───

package/dist/utils/feedback.d.ts

@@ -2,6 +2,7 @@ interface FeedbackEvent {
     type: 'tool_call' | 'discovery';
     toolName?: string;
     feedback?: string;
+    feedbackTool?: string;
     model?: string;
     discoveryPath?: string;
     frictionPoints?: string;
@@ -10,5 +11,6 @@ export declare function captureClientInfo(info: {
     name: string;
     version: string;
 }): void;
+export declare function captureWalletAddress(address: string): void;
 export declare function sendFeedbackEvent(event: FeedbackEvent): void;
 export {};

package/dist/utils/feedback.js

@@ -1,25 +1,87 @@
-import { MCP_USER_AGENT } from '../http.js';
-const FEEDBACK_ENDPOINT = 'https://dev-api.helius.xyz/v0/agents/feedback';
+import { version } from '../version.js';
+import crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+const POSTHOG_ENDPOINT = 'https://www.helius.dev/relay-RMqE/capture/';
+const POSTHOG_API_KEY = 'phc_aLmID5mMwUZi3pVhG4HomDeZaWZ1PqAEkWTempDogzi';
+const HELIUS_DIR = path.join(os.homedir(), '.helius');
+const ANON_ID_PATH = path.join(HELIUS_DIR, 'anon-id');
 let clientInfo = null;
 let feedbackEnabled = true;
+let walletAddress = null;
+let identifySent = false;
+// Persistent anonymous ID shared with helius-cli.
+let sessionId;
+try {
+    if (fs.existsSync(ANON_ID_PATH)) {
+        sessionId = fs.readFileSync(ANON_ID_PATH, 'utf-8').trim();
+    }
+    else {
+        sessionId = crypto.randomUUID();
+        try {
+            fs.mkdirSync(HELIUS_DIR, { recursive: true });
+            fs.writeFileSync(ANON_ID_PATH, sessionId, 'utf-8');
+        }
+        catch { }
+    }
+}
+catch {
+    sessionId = crypto.randomUUID();
+}
 export function captureClientInfo(info) {
     clientInfo = info;
 }
-export function sendFeedbackEvent(event) {
+export function captureWalletAddress(address) {
+    const previousId = walletAddress ? null : sessionId;
+    walletAddress = address;
+    if (previousId && !identifySent) {
+        identifySent = true;
+        posthogCapture('$identify', {
+            distinct_id: address,
+            $anon_distinct_id: previousId,
+        });
+    }
+}
+function getDistinctId() {
+    return walletAddress || sessionId;
+}
+function posthogCapture(event, properties) {
     if (!feedbackEnabled)
         return;
-    const headers = {
-        'Content-Type': 'application/json',
-        'User-Agent': MCP_USER_AGENT,
-    };
-    if (clientInfo) {
-        headers['X-MCP-Client'] = `${clientInfo.name}/${clientInfo.version}`;
-    }
-    fetch(FEEDBACK_ENDPOINT, {
+    fetch(POSTHOG_ENDPOINT, {
         method: 'POST',
-        headers,
-        body: JSON.stringify({ ...event, timestamp: new Date().toISOString() }),
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            api_key: POSTHOG_API_KEY,
+            event,
+            properties,
+        }),
     }).catch(() => {
         feedbackEnabled = false;
     });
 }
+export function sendFeedbackEvent(event) {
+    const eventName = event.type === 'discovery' ? 'agent_discovery' : 'agent_invocation';
+    const properties = {
+        distinct_id: getDistinctId(),
+        helius_client: 'helius-mcp',
+        helius_version: version,
+    };
+    if (clientInfo) {
+        properties.mcp_client = `${clientInfo.name}/${clientInfo.version}`;
+    }
+    if (event.toolName)
+        properties.current_tool = event.toolName;
+    if (event.feedback)
+        properties.feedback = event.feedback;
+    if (event.feedbackTool)
+        properties.feedback_tool = event.feedbackTool;
+    if (event.model)
+        properties.llm_model = event.model;
+    if (event.discoveryPath)
+        properties.discovery_path = event.discoveryPath;
+    if (event.frictionPoints)
+        properties.friction_points = event.frictionPoints;
+    posthogCapture(eventName, properties);
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const version = "1.0.0";
+export declare const version = "1.2.0";

package/dist/version.js

@@ -1 +1 @@
-export const version = '1.0.0';
+export const version = '1.2.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helius-mcp",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Official Helius MCP Server - Complete Solana blockchain data access for AI assistants",
   "type": "module",
   "main": "dist/index.js",