helius-mcp 1.2.0 → 1.3.0

package/dist/scripts/test-htmltotext.js

@@ -0,0 +1,67 @@
+/**
+ * Quick test: fetch a real blog post and check htmlToText output quality.
+ * Run: node dist/scripts/test-htmltotext.js
+ */
+function htmlToText(html) {
+    let content = html;
+    const articleMatch = html.match(/<article[^>]*>([\s\S]*)<\/article>/i);
+    if (articleMatch) {
+        content = articleMatch[1];
+    }
+    else {
+        const mainMatch = html.match(/<main[^>]*>([\s\S]*)<\/main>/i);
+        if (mainMatch) {
+            content = mainMatch[1];
+        }
+    }
+    return (content
+        .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, '')
+        .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, '')
+        .replace(/<noscript[^>]*>[\s\S]*?<\/noscript>/gi, '')
+        .replace(/<svg[^>]*>[\s\S]*?<\/svg>/gi, '')
+        .replace(/<nav[^>]*>[\s\S]*?<\/nav>/gi, '')
+        .replace(/<footer[^>]*>[\s\S]*?<\/footer>/gi, '')
+        .replace(/<header[^>]*>[\s\S]*?<\/header>/gi, '')
+        .replace(/<h1[^>]*>([\s\S]*?)<\/h1>/gi, '\n# $1\n')
+        .replace(/<h2[^>]*>([\s\S]*?)<\/h2>/gi, '\n## $1\n')
+        .replace(/<h3[^>]*>([\s\S]*?)<\/h3>/gi, '\n### $1\n')
+        .replace(/<h4[^>]*>([\s\S]*?)<\/h4>/gi, '\n#### $1\n')
+        .replace(/<pre[^>]*><code[^>]*>([\s\S]*?)<\/code><\/pre>/gi, '\n```\n$1\n```\n')
+        .replace(/<code[^>]*>([\s\S]*?)<\/code>/gi, '`$1`')
+        .replace(/<li[^>]*>([\s\S]*?)<\/li>/gi, '- $1\n')
+        .replace(/<p[^>]*>([\s\S]*?)<\/p>/gi, '\n$1\n')
+        .replace(/<br\s*\/?>/gi, '\n')
+        .replace(/<a[^>]*href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/gi, '[$2]($1)')
+        .replace(/<(?:strong|b)[^>]*>([\s\S]*?)<\/(?:strong|b)>/gi, '**$1**')
+        .replace(/<(?:em|i)[^>]*>([\s\S]*?)<\/(?:em|i)>/gi, '*$1*')
+        .replace(/<[^>]+>/g, '')
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&#(\d+);/g, (_, code) => String.fromCharCode(parseInt(code, 10)))
+        .replace(/&#x([0-9a-f]+);/gi, (_, hex) => String.fromCharCode(parseInt(hex, 16)))
+        .replace(/\n{3,}/g, '\n\n')
+        .trim());
+}
+async function main() {
+    const res = await fetch('https://www.helius.dev/blog/alpenglow');
+    const html = await res.text();
+    const text = htmlToText(html);
+    console.log('=== htmlToText Output (first 3000 chars) ===\n');
+    console.log(text.slice(0, 3000));
+    console.log('\n=== Stats ===');
+    console.log(`HTML length: ${html.length}`);
+    console.log(`Text length: ${text.length}`);
+    console.log(`Compression ratio: ${((1 - text.length / html.length) * 100).toFixed(1)}%`);
+    console.log(`Has ## headers: ${/^## /m.test(text)}`);
+    console.log(`Has ### headers: ${/^### /m.test(text)}`);
+    console.log(`Has **bold**: ${/\*\*[^*]+\*\*/.test(text)}`);
+    console.log(`Has [links](url): ${/\[[^\]]+\]\([^)]+\)/.test(text)}`);
+    console.log(`Has bullet lists: ${/^- /m.test(text)}`);
+    console.log(`Residual HTML tags: ${(text.match(/<[^>]+>/g) || []).length}`);
+}
+main();
+export {};

package/dist/scripts/test-solana-knowledge.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Integration test for solana-knowledge tools.
+ *
+ * Run after build:
+ *   node dist/scripts/test-solana-knowledge.js
+ *
+ * Tests each tool against live endpoints and validates the response shape.
+ */
+export {};

package/dist/scripts/test-solana-knowledge.js

@@ -0,0 +1,272 @@
+/**
+ * Integration test for solana-knowledge tools.
+ *
+ * Run after build:
+ *   node dist/scripts/test-solana-knowledge.js
+ *
+ * Tests each tool against live endpoints and validates the response shape.
+ */
+const PASS = '\x1b[32m✅\x1b[0m';
+const FAIL = '\x1b[31m❌\x1b[0m';
+const WARN = '\x1b[33m⚠️\x1b[0m';
+let passed = 0;
+let failed = 0;
+function assert(condition, label, detail) {
+    if (condition) {
+        console.log(`${PASS} ${label}`);
+        passed++;
+    }
+    else {
+        console.log(`${FAIL} ${label}${detail ? ` — ${detail}` : ''}`);
+        failed++;
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers — minimal reimplementation to test without starting an MCP server
+// ---------------------------------------------------------------------------
+const SIMD_REPO = 'solana-foundation/solana-improvement-documents';
+const SIMD_API_URL = `https://api.github.com/repos/${SIMD_REPO}/contents/proposals`;
+const SIMD_RAW_BASE = `https://raw.githubusercontent.com/${SIMD_REPO}/main/proposals`;
+const UA = 'helius-mcp-test';
+function ghHeaders() {
+    const h = { Accept: 'application/vnd.github.v3+json' };
+    if (process.env.GITHUB_TOKEN)
+        h['Authorization'] = `token ${process.env.GITHUB_TOKEN}`;
+    return h;
+}
+// ---------------------------------------------------------------------------
+// Test: getSIMD
+// ---------------------------------------------------------------------------
+async function testGetSIMD() {
+    console.log('\n--- getSIMD ---');
+    // 1. Fetch SIMD index
+    const indexRes = await fetch(SIMD_API_URL, { headers: { 'User-Agent': UA, ...ghHeaders() } });
+    assert(indexRes.ok, 'SIMD index fetch succeeds', `status=${indexRes.status}`);
+    const files = (await indexRes.json());
+    const mdFiles = files.filter((f) => f.name.endsWith('.md'));
+    assert(mdFiles.length > 50, `SIMD index has >50 proposals (got ${mdFiles.length})`);
+    // 2. Parse filenames
+    const parsed = mdFiles
+        .map((f) => {
+        const match = f.name.match(/^(\d+)-(.+)\.md$/);
+        return match ? { number: match[1], slug: match[2], filename: f.name } : null;
+    })
+        .filter((x) => x !== null);
+    assert(parsed.length === mdFiles.length, `All ${mdFiles.length} filenames parsed correctly`);
+    // 3. Fetch a known SIMD (SIMD-0096)
+    const entry96 = parsed.find((e) => e.number === '0096');
+    assert(!!entry96, 'SIMD-0096 exists in index');
+    if (entry96) {
+        const rawRes = await fetch(`${SIMD_RAW_BASE}/${entry96.filename}`, { headers: { 'User-Agent': UA } });
+        assert(rawRes.ok, 'SIMD-0096 raw fetch succeeds');
+        const content = await rawRes.text();
+        assert(content.length > 500, `SIMD-0096 has substantial content (${content.length} chars)`);
+        assert(content.includes('---'), 'SIMD-0096 has YAML frontmatter delimiter');
+    }
+    // 4. Test number padding logic
+    const padTest = (input, expected) => {
+        const result = input.replace(/^0+/, '').padStart(4, '0');
+        assert(result === expected, `Padding "${input}" → "${result}" (expected "${expected}")`);
+    };
+    padTest('228', '0228');
+    padTest('0096', '0096');
+    padTest('1', '0001');
+    padTest('0001', '0001');
+    // 5. Test not-found with nearby suggestions
+    const entry9999 = parsed.find((e) => e.number === '9999');
+    assert(!entry9999, 'SIMD-9999 does not exist (good — tests not-found path)');
+}
+// ---------------------------------------------------------------------------
+// Test: listSIMDs
+// ---------------------------------------------------------------------------
+async function testListSIMDs() {
+    console.log('\n--- listSIMDs ---');
+    // Already tested via getSIMD index fetch — just verify table format
+    const indexRes = await fetch(SIMD_API_URL, { headers: { 'User-Agent': UA, ...ghHeaders() } });
+    const files = (await indexRes.json());
+    const parsed = files
+        .filter((f) => f.name.endsWith('.md'))
+        .map((f) => {
+        const match = f.name.match(/^(\d+)-(.+)\.md$/);
+        return match ? { number: match[1], slug: match[2] } : null;
+    })
+        .filter(Boolean);
+    const tableRow = `| ${parsed[0].number} | ${parsed[0].slug.replace(/-/g, ' ')} |`;
+    assert(tableRow.includes('|'), 'Table row format is valid markdown');
+    assert(parsed.length > 0, `listSIMDs would return ${parsed.length} entries`);
+}
+// ---------------------------------------------------------------------------
+// Test: readSolanaSourceFile
+// ---------------------------------------------------------------------------
+async function testReadSolanaSourceFile() {
+    console.log('\n--- readSolanaSourceFile ---');
+    // 1. Agave — known file
+    const agaveUrl = 'https://raw.githubusercontent.com/anza-xyz/agave/master/svm/src/lib.rs';
+    const agaveRes = await fetch(agaveUrl, { headers: { 'User-Agent': UA } });
+    assert(agaveRes.ok, `Agave svm/src/lib.rs exists (status=${agaveRes.status})`);
+    const agaveContent = await agaveRes.text();
+    assert(agaveContent.length > 0, `Agave svm/src/lib.rs has content (${agaveContent.length} chars)`);
+    // 2. Firedancer — test with correct default branch ("main")
+    const fdUrl = 'https://raw.githubusercontent.com/firedancer-io/firedancer/main/README.md';
+    const fdRes = await fetch(fdUrl, { headers: { 'User-Agent': UA } });
+    assert(fdRes.ok, `Firedancer README.md on "main" branch exists (status=${fdRes.status})`);
+    // 3. Firedancer — verify default branch is "main" via GitHub API
+    const fdApiRes = await fetch('https://api.github.com/repos/firedancer-io/firedancer', {
+        headers: { 'User-Agent': UA, ...ghHeaders() },
+    });
+    if (fdApiRes.ok) {
+        const fdRepo = (await fdApiRes.json());
+        assert(fdRepo.default_branch === 'main', `Firedancer default branch is "${fdRepo.default_branch}" (expected "main")`);
+    }
+    else {
+        console.log(`${WARN} Could not check Firedancer default branch (status=${fdApiRes.status})`);
+    }
+    // 4. Non-existent file returns error
+    const badUrl = 'https://raw.githubusercontent.com/anza-xyz/agave/master/this/does/not/exist.rs';
+    const badRes = await fetch(badUrl, { headers: { 'User-Agent': UA } });
+    assert(!badRes.ok, `Non-existent path returns error (status=${badRes.status})`);
+    // 5. Truncation logic
+    const longContent = 'x'.repeat(60_000);
+    const MAX_CHARS = 50_000;
+    const truncated = longContent.length > MAX_CHARS;
+    assert(truncated, 'Content >50k chars is detected as needing truncation');
+    const display = longContent.slice(0, MAX_CHARS);
+    assert(display.length === MAX_CHARS, `Truncated to exactly ${MAX_CHARS} chars`);
+}
+// ---------------------------------------------------------------------------
+// Test: searchSolanaDocs
+// ---------------------------------------------------------------------------
+async function testSearchSolanaDocs() {
+    console.log('\n--- searchSolanaDocs ---');
+    // 1. Fetch the docs
+    const docsRes = await fetch('https://solana.com/llms-full.txt', { headers: { 'User-Agent': UA } });
+    assert(docsRes.ok, `Solana llms-full.txt fetch succeeds (status=${docsRes.status})`);
+    const docsContent = await docsRes.text();
+    assert(docsContent.length > 10_000, `Solana docs has substantial content (${docsContent.length} chars)`);
+    // 2. Test section extraction for "Accounts"
+    const lines = docsContent.split('\n');
+    const accountSections = [];
+    let inSection = false;
+    let sectionDepth = 0;
+    let sectionLines = [];
+    for (const line of lines) {
+        const headerMatch = line.match(/^(#{1,4})\s+(.+)/);
+        if (headerMatch) {
+            const depth = headerMatch[1].length;
+            const title = headerMatch[2].toLowerCase();
+            if (inSection && depth <= sectionDepth) {
+                accountSections.push(sectionLines.join('\n'));
+                sectionLines = [];
+                inSection = false;
+            }
+            if (title.includes('accounts')) {
+                inSection = true;
+                sectionDepth = depth;
+                sectionLines.push(line);
+            }
+            else if (inSection) {
+                sectionLines.push(line);
+            }
+        }
+        else if (inSection) {
+            sectionLines.push(line);
+        }
+    }
+    if (inSection)
+        accountSections.push(sectionLines.join('\n'));
+    assert(accountSections.length > 0, `Found ${accountSections.length} sections matching "accounts"`);
+    // 3. Test empty queryWords edge case (the bug we fixed)
+    const shortQuery = 'a b';
+    const shortQueryLower = shortQuery.toLowerCase();
+    const shortQueryWords = shortQueryLower.split(/\s+/).filter((w) => w.length > 2);
+    assert(shortQueryWords.length === 0, 'Short query "a b" produces empty queryWords');
+    // With our fix, the condition `queryWords.length > 0 && queryWords.every(...)` prevents vacuous truth
+    const wouldMatchAll = shortQueryWords.length > 0 && shortQueryWords.every(() => true);
+    assert(!wouldMatchAll, 'Empty queryWords does NOT vacuously match all headers (bug fixed)');
+    // 4. Test "PDAs" query
+    const pdaLines = lines.filter((l) => l.toLowerCase().includes('pda'));
+    assert(pdaLines.length > 0, `"PDAs" finds ${pdaLines.length} matching lines in Solana docs`);
+}
+// ---------------------------------------------------------------------------
+// Test: fetchHeliusBlog
+// ---------------------------------------------------------------------------
+async function testFetchHeliusBlog() {
+    console.log('\n--- fetchHeliusBlog ---');
+    // 1. Test blog index size
+    const BLOG_INDEX_SIZE = 55; // approximate — we have ~55 curated posts
+    // We can't import the actual index, so just validate the fetch works
+    // 2. Fetch a known blog post
+    const blogUrl = 'https://www.helius.dev/blog/solana-virtual-machine';
+    const blogRes = await fetch(blogUrl, { headers: { 'User-Agent': UA } });
+    assert(blogRes.ok, `Blog post "solana-virtual-machine" fetch succeeds (status=${blogRes.status})`);
+    const html = await blogRes.text();
+    assert(html.length > 1000, `Blog HTML has content (${html.length} chars)`);
+    // 3. Test htmlToText conversion
+    const hasArticle = /<article/i.test(html);
+    const hasMain = /<main/i.test(html);
+    assert(hasArticle || hasMain, `Blog HTML has <article> or <main> tag for content extraction`);
+    // Basic HTML-to-text test
+    const simpleHtml = '<h2>Test Header</h2><p>Some <strong>bold</strong> text.</p>';
+    const converted = simpleHtml
+        .replace(/<h2[^>]*>([\s\S]*?)<\/h2>/gi, '\n## $1\n')
+        .replace(/<p[^>]*>([\s\S]*?)<\/p>/gi, '\n$1\n')
+        .replace(/<(?:strong|b)[^>]*>([\s\S]*?)<\/(?:strong|b)>/gi, '**$1**')
+        .replace(/<[^>]+>/g, '')
+        .trim();
+    assert(converted.includes('## Test Header'), 'h2 converted to ## markdown');
+    assert(converted.includes('**bold**'), 'strong converted to **bold**');
+    // 4. Test a non-existent slug returns error
+    const badBlogUrl = 'https://www.helius.dev/blog/this-post-does-not-exist-12345';
+    const badBlogRes = await fetch(badBlogUrl, { headers: { 'User-Agent': UA } });
+    // Helius might return 200 with a "not found" page or 404 — either way test completes
+    console.log(`${WARN} Non-existent blog slug returns status=${badBlogRes.status} (expected 404 or redirect)`);
+    // 5. Fetch another post to verify consistency
+    const blog2Url = 'https://www.helius.dev/blog/alpenglow';
+    const blog2Res = await fetch(blog2Url, { headers: { 'User-Agent': UA } });
+    assert(blog2Res.ok, `Blog post "alpenglow" fetch succeeds (status=${blog2Res.status})`);
+}
+// ---------------------------------------------------------------------------
+// Run all tests
+// ---------------------------------------------------------------------------
+async function main() {
+    console.log('=== Solana Knowledge Tools — Integration Tests ===\n');
+    try {
+        await testGetSIMD();
+    }
+    catch (e) {
+        console.log(`${FAIL} getSIMD test threw: ${e}`);
+        failed++;
+    }
+    try {
+        await testListSIMDs();
+    }
+    catch (e) {
+        console.log(`${FAIL} listSIMDs test threw: ${e}`);
+        failed++;
+    }
+    try {
+        await testReadSolanaSourceFile();
+    }
+    catch (e) {
+        console.log(`${FAIL} readSolanaSourceFile test threw: ${e}`);
+        failed++;
+    }
+    try {
+        await testSearchSolanaDocs();
+    }
+    catch (e) {
+        console.log(`${FAIL} searchSolanaDocs test threw: ${e}`);
+        failed++;
+    }
+    try {
+        await testFetchHeliusBlog();
+    }
+    catch (e) {
+        console.log(`${FAIL} fetchHeliusBlog test threw: ${e}`);
+        failed++;
+    }
+    console.log(`\n=== Results: ${passed} passed, ${failed} failed ===`);
+    process.exit(failed > 0 ? 1 : 0);
+}
+main();
+export {};

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

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * Validates recommendStack template data for correctness.
+ *
+ * Checks:
+ * 1. MCP tool names exist in KNOWN_TOOLS
+ * 2. Reference paths exist on disk
+ * 3. Plan-feature compatibility (e.g., Laserstream mainnet requires professional)
+ * 4. Tier ordering (budget <= standard <= production plan rank)
+ * 5. No empty arrays (products, limitations, references)
+ */
+export {};

package/dist/scripts/validate-templates.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+/**
+ * Validates recommendStack template data for correctness.
+ *
+ * Checks:
+ * 1. MCP tool names exist in KNOWN_TOOLS
+ * 2. Reference paths exist on disk
+ * 3. Plan-feature compatibility (e.g., Laserstream mainnet requires professional)
+ * 4. Tier ordering (budget <= standard <= production plan rank)
+ * 5. No empty arrays (products, limitations, references)
+ */
+import fs from 'fs';
+import path from 'path';
+import { PROJECT_TEMPLATES, KNOWN_TOOLS } from '../tools/recommend.js';
+import { HELIUS_PLANS } from '../tools/plans.js';
+const PLAN_RANK = { free: 0, developer: 1, business: 2, professional: 3 };
+const TIER_RANK = { budget: 0, standard: 1, production: 2 };
+// 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(templateName, msg) {
+    errors.push(`[${templateName}] ${msg}`);
+}
+for (const [key, template] of Object.entries(PROJECT_TEMPLATES)) {
+    // ── Check tier ordering ──
+    const sorted = [...template.tiers].sort((a, b) => TIER_RANK[a.tier] - TIER_RANK[b.tier]);
+    for (let i = 1; i < sorted.length; i++) {
+        const prev = sorted[i - 1];
+        const curr = sorted[i];
+        if ((PLAN_RANK[curr.minimumPlan] ?? 0) < (PLAN_RANK[prev.minimumPlan] ?? 0)) {
+            error(key, `Tier ordering violation: ${curr.tier} (${curr.minimumPlan}) has lower plan rank than ${prev.tier} (${prev.minimumPlan})`);
+        }
+    }
+    for (const tier of template.tiers) {
+        const tierLabel = `${key}/${tier.tier}`;
+        // ── No empty arrays ──
+        if (tier.products.length === 0) {
+            error(tierLabel, 'products array is empty');
+        }
+        if (tier.limitations.length === 0) {
+            error(tierLabel, 'limitations array is empty');
+        }
+        if (tier.references.length === 0) {
+            error(tierLabel, 'references array is empty');
+        }
+        // ── Validate each product ──
+        for (const product of tier.products) {
+            // MCP tool name validation
+            for (const tool of product.mcpTools) {
+                if (!KNOWN_TOOLS.has(tool)) {
+                    error(tierLabel, `Unknown MCP tool "${tool}" in product "${product.product}"`);
+                }
+            }
+            // Plan-feature compatibility
+            if (!(product.minimumPlan in PLAN_RANK)) {
+                error(tierLabel, `Unknown plan "${product.minimumPlan}" in product "${product.product}"`);
+            }
+            if (!(product.minimumPlan in HELIUS_PLANS)) {
+                error(tierLabel, `Plan "${product.minimumPlan}" not found in HELIUS_PLANS for product "${product.product}"`);
+            }
+            // Laserstream mainnet must require professional
+            const nameLower = product.product.toLowerCase();
+            if (nameLower.includes('laserstream') && nameLower.includes('mainnet') && product.minimumPlan !== 'professional') {
+                error(tierLabel, `Laserstream mainnet in product "${product.product}" requires professional plan, but has "${product.minimumPlan}"`);
+            }
+            // Enhanced WebSockets must require business+
+            if (nameLower.includes('enhanced websocket') && (PLAN_RANK[product.minimumPlan] ?? 0) < PLAN_RANK['business']) {
+                error(tierLabel, `Enhanced WebSockets in product "${product.product}" requires business+ plan, but has "${product.minimumPlan}"`);
+            }
+        }
+        // ── Reference path validation ──
+        for (const ref of tier.references) {
+            const refPath = path.join(SKILL_DIR, ref);
+            if (!fs.existsSync(refPath)) {
+                error(tierLabel, `Reference file not found: ${ref} (looked at ${refPath})`);
+            }
+        }
+    }
+}
+// ── Report ──
+if (errors.length > 0) {
+    console.error(`\n❌ Template validation failed with ${errors.length} error(s):\n`);
+    for (const err of errors) {
+        console.error(`  • ${err}`);
+    }
+    console.error('');
+    process.exit(1);
+}
+else {
+    const templateCount = Object.keys(PROJECT_TEMPLATES).length;
+    const tierCount = Object.values(PROJECT_TEMPLATES).reduce((sum, t) => sum + t.tiers.length, 0);
+    console.log(`✅ All templates valid (${templateCount} templates, ${tierCount} tiers)`);
+}

package/dist/tools/auth.js

@@ -16,6 +16,9 @@ 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'];
+/** Tracks consecutive insufficient-balance checks to prevent agent polling loops. */
+let insufficientBalanceChecks = 0;
+const MAX_BALANCE_CHECKS_BEFORE_STOP = 3;
 export function registerAuthTools(server) {
     // ── Getting Started Guide ──
     server.tool('getStarted', 'Get setup instructions for Helius. Checks whether an API key is configured (not validated), whether a keypair exists on disk, and whether a JWT session is present, then tells you exactly what to do next. Call this when a user asks "how do I get started?" or needs onboarding help.', {}, async () => {
@@ -48,6 +51,8 @@ export function registerAuthTools(server) {
     // ── Keypair Generation ──
     server.tool('generateKeypair', 'Generate a new Solana keypair for Helius account signup. Returns the wallet address. The user must fund this wallet with ~0.001 SOL + 1 USDC (basic plan) or more USDC (for paid plans) before calling agenticSignup.', {}, async () => {
         try {
+            // Reset balance-check counter for fresh signup flow
+            insufficientBalanceChecks = 0;
             // Check disk first — reuse existing keypair if available
             const existingKey = loadKeypairFromDisk();
             if (existingKey) {
@@ -105,22 +110,48 @@ export function registerAuthTools(server) {
             const usdcAmount = Number(usdcBalance) / 1_000_000;
             const solOk = solBalance >= 1000000n;
             const usdcOk = usdcBalance >= 1000000n; // 1 USDC for basic plan
-            let status;
-            if (solOk && usdcOk) {
-                status = 'Ready for signup (basic plan). For paid plans, ensure sufficient USDC for the plan price.';
-            }
-            else {
-                const missing = [];
-                if (!solOk)
-                    missing.push(`~0.001 SOL (have ${solAmount.toFixed(6)})`);
-                if (!usdcOk)
-                    missing.push(`1 USDC (have ${usdcAmount.toFixed(2)})`);
-                status = `Need more funds: ${missing.join(', ')}`;
-            }
-            return mcpText(`**Signup Wallet Balance** (\`${address}\`)\n\n` +
+            const funded = solOk && usdcOk;
+            // Reset counter when balance is sufficient
+            if (funded) {
+                insufficientBalanceChecks = 0;
+                return mcpText(`**Signup Wallet Balance** (\`${address}\`)\n\n` +
+                    `- **SOL:** ${solAmount.toFixed(6)} (sufficient)\n` +
+                    `- **USDC:** ${usdcAmount.toFixed(2)} (sufficient for basic)\n\n` +
+                    `**Status:** Ready for signup (basic plan). For paid plans, ensure sufficient USDC for the plan price.\n\n` +
+                    `Call \`agenticSignup\` to proceed.`);
+            }
+            // Insufficient — increment counter and escalate guidance
+            insufficientBalanceChecks++;
+            const missing = [];
+            if (!solOk)
+                missing.push(`~0.001 SOL (have ${solAmount.toFixed(6)})`);
+            if (!usdcOk)
+                missing.push(`1 USDC (have ${usdcAmount.toFixed(2)})`);
+            let balanceBlock = `**Signup Wallet Balance** (\`${address}\`)\n\n` +
                 `- **SOL:** ${solAmount.toFixed(6)} ${solOk ? '(sufficient)' : '(insufficient)'}\n` +
                 `- **USDC:** ${usdcAmount.toFixed(2)} ${usdcOk ? '(sufficient for basic)' : '(insufficient)'}\n\n` +
-                `**Status:** ${status}`);
+                `**Status:** Need more funds: ${missing.join(', ')}`;
+            if (insufficientBalanceChecks === 1) {
+                // First check — normal guidance
+                balanceBlock +=
+                    `\n\n**Action required:** Ask the user to send the missing funds to \`${address}\`. ` +
+                        `Do **not** call \`checkSignupBalance\` again until the user confirms they have sent the funds.`;
+            }
+            else if (insufficientBalanceChecks < MAX_BALANCE_CHECKS_BEFORE_STOP) {
+                // Second check — firmer nudge
+                balanceBlock +=
+                    `\n\n**⚠ Balance still insufficient (check ${insufficientBalanceChecks}/${MAX_BALANCE_CHECKS_BEFORE_STOP}).** ` +
+                        `The wallet has not been funded yet. Ask the user to confirm they have sent funds to \`${address}\` before calling this tool again.`;
+            }
+            else {
+                // Third+ check — hard stop
+                balanceBlock +=
+                    `\n\n**🛑 Balance checked ${insufficientBalanceChecks} times — still insufficient. Stop polling.** ` +
+                        `The wallet \`${address}\` has not received funds. ` +
+                        `Tell the user the exact amounts needed and the wallet address, then **wait for the user to explicitly confirm** they have sent funds before calling \`checkSignupBalance\` again. ` +
+                        `Do not retry automatically.`;
+            }
+            return mcpText(balanceBlock);
         }
         catch (err) {
             return handleToolError(err, 'Error checking balances');

package/dist/tools/network.js

@@ -3,17 +3,18 @@ import { formatSolCompact } from '../utils/formatters.js';
 import { noApiKeyResponse } from './shared.js';
 import { mcpText, handleToolError } from '../utils/errors.js';
 export function registerNetworkTools(server) {
-    server.tool('getNetworkStatus', 'BEST FOR: quick Solana network health check — epoch, slot, supply, version. Get current Solana network status including epoch info (current epoch, slot, progress), total SOL supply, cluster version, and current block height. No parameters needed — gives a quick overview of blockchain health and state. Credit cost: 3 credits (3 standard RPC calls).', {}, async () => {
+    server.tool('getNetworkStatus', 'BEST FOR: quick Solana network health check — epoch, slot, TPS, supply, version. Get current Solana network status including epoch info (current epoch, slot, progress), current TPS (transactions per second), total SOL supply, cluster version, and current block height. No parameters needed — gives a quick overview of blockchain health and state. Credit cost: 4 credits (4 standard RPC calls).', {}, async () => {
         if (!hasApiKey())
             return noApiKeyResponse();
         try {
             const helius = getHeliusClient();
             // Fire all requests in parallel — Kit returns bigint for numeric fields
             // wrapAutoSend in the SDK already calls .send() on pending RPC requests
-            const [epochInfo, supplyResult, version] = await Promise.all([
+            const [epochInfo, supplyResult, version, perfSamples] = await Promise.all([
                 helius.getEpochInfo(),
                 helius.getSupply(),
                 helius.getVersion(),
+                helius.getRecentPerformanceSamples(4),
             ]);
             const lines = ['**Solana Network Status**', ''];
             // Epoch info — all fields are bigint from Kit
@@ -35,6 +36,38 @@ export function registerNetworkTools(server) {
                 }
                 lines.push('');
             }
+            // TPS — averaged from 4 recent performance samples (~60s each, ~4 min window)
+            // numTransactions includes vote + non-vote; numNonVoteTransactions is real user TPS
+            if (Array.isArray(perfSamples) && perfSamples.length > 0) {
+                let totalTx = 0;
+                let totalNonVoteTx = 0;
+                let totalSeconds = 0;
+                let hasNonVoteData = false;
+                for (const sample of perfSamples) {
+                    const samplePeriod = Number(sample.samplePeriodSecs);
+                    if (samplePeriod > 0) {
+                        totalTx += Number(sample.numTransactions);
+                        totalSeconds += samplePeriod;
+                        if (sample.numNonVoteTransactions != null) {
+                            totalNonVoteTx += Number(sample.numNonVoteTransactions);
+                            hasNonVoteData = true;
+                        }
+                    }
+                }
+                if (totalSeconds > 0) {
+                    const totalTps = Math.round(totalTx / totalSeconds);
+                    lines.push('**TPS (avg. last ~4 min):**');
+                    if (hasNonVoteData) {
+                        const nonVoteTps = Math.round(totalNonVoteTx / totalSeconds);
+                        lines.push(`- Real (non-vote): ~${nonVoteTps.toLocaleString()} tx/sec`);
+                        lines.push(`- Total (incl. vote): ~${totalTps.toLocaleString()} tx/sec`);
+                    }
+                    else {
+                        lines.push(`- Total: ~${totalTps.toLocaleString()} tx/sec (includes vote transactions)`);
+                    }
+                    lines.push('');
+                }
+            }
             // Supply — value fields are bigint from Kit
             if (supplyResult?.value) {
                 const supply = supplyResult.value;

package/dist/tools/shared.js

@@ -1,15 +1,15 @@
-const NO_API_KEY_MESSAGE = `**Helius API Key Required**
-
-I need a Helius API key to query the Solana blockchain.
-
-**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. Copy your API key
+const NO_API_KEY_MESSAGE = `**Helius API Key Required**
+
+I need a Helius API key to query the Solana blockchain.
+
+**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. Copy your API key
 3. Call \`setHeliusApiKey\` with your key`;
 export function noApiKeyResponse() {
     return {

package/dist/version.d.ts

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

package/dist/version.js

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