helius-mcp 1.2.0 → 2.0.0

package/dist/router/dispatch.js

@@ -0,0 +1,276 @@
+import { getStoredResult, putStoredResult } from '../results/store.js';
+import { callActionHandler } from './action-handlers.js';
+import { getActionCatalogEntry } from './catalog.js';
+import { getRouterContext } from './context.js';
+import { ACTION_REQUIRED_PARAMS } from './required-params.js';
+import { applyItemSelection, applyRangeSelection, applySectionSelection, buildTextVariant, collectSectionHints, compactErrorText, estimateRenderedSize, getFamilyLimit, mcpErrorCompact, mcpResultHandle, mcpText, toPlainText, } from './responses.js';
+function isHandleEligible(entry) {
+    return entry.handleEligibility;
+}
+function pickRequestedDetail(entry, detail) {
+    if (detail === 'summary' || detail === 'standard' || detail === 'full') {
+        return detail;
+    }
+    return entry.defaultDetail;
+}
+function buildActionParams(input) {
+    const { action: _action, detail: _detail, args, ...topLevel } = input;
+    const merged = {
+        ...(args && typeof args === 'object' && !Array.isArray(args) ? args : {}),
+    };
+    for (const [key, value] of Object.entries(topLevel)) {
+        if (value !== undefined) {
+            merged[key] = value;
+        }
+    }
+    // Normalize common address field mismatches
+    if (!merged.address && merged.ownerAddress)
+        merged.address = merged.ownerAddress;
+    if (!merged.owner && merged.address && !merged.ownerAddress)
+        merged.owner = merged.address;
+    if (!merged.address && merged.owner)
+        merged.address = merged.owner;
+    return merged;
+}
+function detectContinuation(action, params, text) {
+    if (action === 'getTransactionHistory') {
+        // Fragile: depends on handler markdown format "**Next Page Token:** `<token>`"
+        const tokenMatch = text.match(/\*\*Next Page Token:\*\*\s+`([^`]+)`/);
+        if (tokenMatch) {
+            const mode = typeof params.mode === 'string' ? params.mode : 'parsed';
+            const next = mode === 'raw'
+                ? { kind: 'rawApi', paginationToken: tokenMatch[1] }
+                : { kind: 'historyApi', paginationToken: tokenMatch[1] };
+            return { model: 'transactionHistory', next };
+        }
+        const hasFilters = [
+            'paginationToken',
+            'status',
+            'tokenAccounts',
+            'blockTimeGte',
+            'blockTimeLte',
+            'slotGte',
+            'slotLte',
+        ].some((key) => params[key] !== undefined);
+        const mode = typeof params.mode === 'string' ? params.mode : 'parsed';
+        const sortOrder = typeof params.sortOrder === 'string' ? params.sortOrder : 'desc';
+        if (mode === 'signatures' && sortOrder === 'desc' && !hasFilters) {
+            // Fragile: depends on handler "✅/❌ <base58sig>" line format for signature extraction
+            const signatures = Array.from(text.matchAll(/^[^\S\r\n]*[✅❌]\s+([1-9A-HJ-NP-Za-km-z]{86,88})$/gm)).map((match) => match[1]);
+            const lastSignature = signatures.at(-1);
+            if (lastSignature) {
+                return {
+                    model: 'transactionHistory',
+                    next: {
+                        kind: 'signaturesQuick',
+                        nextBefore: lastSignature,
+                        lastSeenSignature: lastSignature,
+                        until: typeof params.until === 'string' ? params.until : undefined,
+                    },
+                };
+            }
+        }
+    }
+    if (action === 'getTransfersByAddress') {
+        // Fragile: depends on handler markdown format "**Next Page Token:** `<token>`" (mirrors getTransactionHistory)
+        const tokenMatch = text.match(/\*\*Next Page Token:\*\*\s+`([^`]+)`/);
+        if (tokenMatch) {
+            return {
+                model: 'transactionHistory',
+                next: { kind: 'rawApi', paginationToken: tokenMatch[1] },
+            };
+        }
+    }
+    if (typeof params.page === 'number') {
+        return { model: 'page', nextPage: params.page + 1 };
+    }
+    return { model: 'none' };
+}
+function buildAvailableExpansions(family, continuation, sectionHints) {
+    const expansions = new Set(['full']);
+    if (family === 'document' || sectionHints.length > 0) {
+        expansions.add('section');
+        expansions.add('range');
+    }
+    if (family === 'list' || family === 'history') {
+        expansions.add('item');
+    }
+    if (continuation.model === 'page') {
+        expansions.add('page');
+    }
+    if (continuation.model === 'transactionHistory' && continuation.next) {
+        expansions.add('continuation');
+    }
+    return Array.from(expansions);
+}
+function buildStoredResult(entry, publicTool, params, summary, text) {
+    const context = getRouterContext();
+    const continuation = detectContinuation(entry.action, params, text);
+    const sectionHints = collectSectionHints(text);
+    const stored = putStoredResult({
+        kind: entry.responseFamily,
+        ownerSessionKey: context.sessionKey,
+        summary,
+        availableExpansions: buildAvailableExpansions(entry.responseFamily, continuation, sectionHints),
+        payload: {
+            recipe: {
+                publicTool,
+                action: entry.action,
+                params,
+                responseFamily: entry.responseFamily,
+                defaultDetail: entry.defaultDetail,
+            },
+            continuation,
+            sectionHints,
+        },
+    });
+    return stored;
+}
+function normalizeSuccessResponse(entry, publicTool, params, text, requestedDetail, allowHandles) {
+    const baseText = text.trim();
+    const summaryText = buildTextVariant(entry.responseFamily, 'summary', baseText);
+    const standardText = buildTextVariant(entry.responseFamily, 'standard', baseText);
+    const fullText = buildTextVariant(entry.responseFamily, 'full', baseText);
+    const requestedText = requestedDetail === 'summary'
+        ? summaryText
+        : requestedDetail === 'standard'
+            ? standardText
+            : fullText;
+    const size = estimateRenderedSize(requestedText);
+    const limit = getFamilyLimit(entry.responseFamily, requestedDetail);
+    const needsHandle = allowHandles
+        && isHandleEligible(entry)
+        && (requestedDetail === 'summary' || size > limit);
+    if (needsHandle) {
+        const stored = buildStoredResult(entry, publicTool, params, summaryText, fullText);
+        return mcpResultHandle(summaryText, stored.resultId, stored.availableExpansions, {
+            family: entry.responseFamily,
+            action: entry.action,
+            defaultDetail: entry.defaultDetail,
+        });
+    }
+    return mcpText(requestedText, {
+        family: entry.responseFamily,
+        action: entry.action,
+        detail: requestedDetail,
+    });
+}
+function normalizeActionResponse(entry, publicTool, params, result, requestedDetail, allowHandles) {
+    const text = toPlainText(result);
+    if (result.isError) {
+        return mcpErrorCompact(compactErrorText(text), {
+            action: entry.action,
+            publicTool,
+            error: true,
+        });
+    }
+    return normalizeSuccessResponse(entry, publicTool, params, text, requestedDetail, allowHandles);
+}
+async function executeActionViaRouter(publicTool, action, params, requestedDetail, extra, allowHandles) {
+    const entry = getActionCatalogEntry(action);
+    try {
+        const result = await callActionHandler(action, params, extra);
+        return normalizeActionResponse(entry, publicTool, params, result, requestedDetail, allowHandles);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return mcpErrorCompact(message, { code: 'HANDLER_ERROR', action, publicTool });
+    }
+}
+export async function dispatchRoutedTool(publicTool, params, extra) {
+    const action = params.action;
+    if (!action) {
+        return mcpErrorCompact('Missing required "action" field.', { code: 'MISSING_ACTION' });
+    }
+    const requestedDetail = pickRequestedDetail(getActionCatalogEntry(action), params.detail);
+    const actionParams = buildActionParams(params);
+    const requiredFields = ACTION_REQUIRED_PARAMS[action];
+    if (requiredFields) {
+        const missing = requiredFields.filter((f) => actionParams[f] === undefined);
+        if (missing.length > 0) {
+            return mcpErrorCompact(`Missing required parameter${missing.length > 1 ? 's' : ''} for ${action}: ${missing.join(', ')}`, { code: 'MISSING_PARAMS', action, missing });
+        }
+    }
+    return executeActionViaRouter(publicTool, action, actionParams, requestedDetail, extra, true);
+}
+function applyContinuation(params, stored, continuation) {
+    if (!continuation) {
+        return params;
+    }
+    if (continuation !== 'next') {
+        return {
+            ...params,
+            continuation,
+        };
+    }
+    if (stored.payload.continuation.model === 'transactionHistory' && stored.payload.continuation.next) {
+        const next = stored.payload.continuation.next;
+        if (next.kind === 'signaturesQuick') {
+            return {
+                ...params,
+                before: next.nextBefore,
+            };
+        }
+        return {
+            ...params,
+            paginationToken: next.paginationToken,
+        };
+    }
+    if (stored.payload.continuation.model === 'page' && stored.payload.continuation.nextPage !== undefined) {
+        return {
+            ...params,
+            page: stored.payload.continuation.nextPage,
+        };
+    }
+    return params;
+}
+export async function expandStoredResult(params, extra) {
+    const resultId = typeof params.resultId === 'string' ? params.resultId : '';
+    if (!resultId) {
+        return mcpErrorCompact('Missing required "resultId".', { code: 'MISSING_RESULT_ID' });
+    }
+    const context = getRouterContext();
+    const stored = getStoredResult(resultId, context.sessionKey);
+    if (!stored) {
+        return mcpErrorCompact('Result handle not found or no longer available. Re-run the original action.', {
+            code: 'RESULT_NOT_FOUND',
+            resultId,
+        });
+    }
+    let nextParams = {
+        ...stored.payload.recipe.params,
+    };
+    if (typeof params.page === 'number') {
+        nextParams.page = params.page;
+    }
+    nextParams = applyContinuation(nextParams, stored, typeof params.continuation === 'string' ? params.continuation : undefined);
+    const requestedDetail = (params.detail === 'summary' || params.detail === 'standard' || params.detail === 'full')
+        ? params.detail
+        : 'full';
+    try {
+        const rawResponse = await callActionHandler(stored.payload.recipe.action, nextParams, extra);
+        const rawText = toPlainText(rawResponse);
+        if (rawResponse.isError) {
+            return mcpErrorCompact(compactErrorText(rawText), {
+                code: 'EXPAND_FAILED',
+                action: stored.payload.recipe.action,
+            });
+        }
+        const selected = applyRangeSelection(applyItemSelection(applySectionSelection(rawText, typeof params.section === 'string' ? params.section : undefined), typeof params.item === 'number' ? params.item : undefined), typeof params.range === 'string' ? params.range : undefined);
+        const entry = getActionCatalogEntry(stored.payload.recipe.action);
+        if (params.continuation === 'next' || typeof params.page === 'number') {
+            return normalizeSuccessResponse(entry, stored.payload.recipe.publicTool, nextParams, selected, requestedDetail, true);
+        }
+        const rendered = buildTextVariant(entry.responseFamily, requestedDetail, selected);
+        return mcpText(rendered, {
+            action: stored.payload.recipe.action,
+            family: stored.kind,
+            resultId,
+            detail: requestedDetail,
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return mcpErrorCompact(message, { code: 'EXPAND_HANDLER_ERROR', action: stored.payload.recipe.action });
+    }
+}

package/dist/router/instructions.d.ts

@@ -0,0 +1 @@
+export declare const ROUTER_INSTRUCTIONS = "Helius MCP exposes 10 public tools total: 9 routed domain tools plus `expandResult`.\n\nChoose tools by user intent, not by name similarity.\n\nRouting:\n- Account setup, API keys, signup, plans, billing: `heliusAccount`\n- Wallet-centric balances, holdings, identity, wallet history: `heliusWallet`\n- Assets, NFTs, collections, token holders: `heliusAsset`\n- Parsed transactions or wallet transaction history: `heliusTransaction`\n- Raw chain state, token accounts, stake reads, blocks, network status, priority fees: `heliusChain`\n- Webhook CRUD or live subscription configuration: `heliusStreaming`\n- Docs, guides, pricing references, troubleshooting, source, blog, SIMDs: `heliusKnowledge`\n- SOL/token transfers or staking mutations: `heliusWrite`\n- Compressed account, proof, balance, compression history: `heliusCompression`\n\nRules:\n- Use the chosen routed tool plus the Helius action name in `action`.\n- Wallet holdings use `heliusWallet.getTokenBalances`; raw token accounts use `heliusChain.getTokenAccounts`.\n- Parsed transaction details use `heliusTransaction.parseTransactions`; wallet activity listing uses `heliusTransaction.getTransactionHistory`; per-transfer rows (token + SOL with mint/direction/counterparty filters) use `heliusTransaction.getTransfersByAddress`.\n- Streaming or webhook setup guides live under `heliusKnowledge`; actual webhook/subscription config lives under `heliusStreaming`.\n- Pricing and plan selection start with `heliusAccount.getHeliusPlanInfo`; per-method credit costs or rate limits use `heliusKnowledge.getRateLimitInfo` or `heliusKnowledge.getHeliusCreditsInfo`.\n- Read queries stay on domain tools; sends and staking mutations use `heliusWrite`.\n- Heavy content is summary-first. Use `expandResult` with the returned `resultId` for sections, ranges, pages, or continuation.\n- Set `_feedback` to a short reason for the call or takeaway from the previous result. Avoid placeholders like `first_call`.\n- Set `_feedbackTool` to the current `publicTool.action`, e.g. `heliusWallet.getBalance`. Always send `_model`.";

package/dist/router/instructions.js

@@ -0,0 +1,25 @@
+export const ROUTER_INSTRUCTIONS = `Helius MCP exposes 10 public tools total: 9 routed domain tools plus \`expandResult\`.
+
+Choose tools by user intent, not by name similarity.
+
+Routing:
+- Account setup, API keys, signup, plans, billing: \`heliusAccount\`
+- Wallet-centric balances, holdings, identity, wallet history: \`heliusWallet\`
+- Assets, NFTs, collections, token holders: \`heliusAsset\`
+- Parsed transactions or wallet transaction history: \`heliusTransaction\`
+- Raw chain state, token accounts, stake reads, blocks, network status, priority fees: \`heliusChain\`
+- Webhook CRUD or live subscription configuration: \`heliusStreaming\`
+- Docs, guides, pricing references, troubleshooting, source, blog, SIMDs: \`heliusKnowledge\`
+- SOL/token transfers or staking mutations: \`heliusWrite\`
+- Compressed account, proof, balance, compression history: \`heliusCompression\`
+
+Rules:
+- Use the chosen routed tool plus the Helius action name in \`action\`.
+- Wallet holdings use \`heliusWallet.getTokenBalances\`; raw token accounts use \`heliusChain.getTokenAccounts\`.
+- Parsed transaction details use \`heliusTransaction.parseTransactions\`; wallet activity listing uses \`heliusTransaction.getTransactionHistory\`; per-transfer rows (token + SOL with mint/direction/counterparty filters) use \`heliusTransaction.getTransfersByAddress\`.
+- Streaming or webhook setup guides live under \`heliusKnowledge\`; actual webhook/subscription config lives under \`heliusStreaming\`.
+- Pricing and plan selection start with \`heliusAccount.getHeliusPlanInfo\`; per-method credit costs or rate limits use \`heliusKnowledge.getRateLimitInfo\` or \`heliusKnowledge.getHeliusCreditsInfo\`.
+- Read queries stay on domain tools; sends and staking mutations use \`heliusWrite\`.
+- Heavy content is summary-first. Use \`expandResult\` with the returned \`resultId\` for sections, ranges, pages, or continuation.
+- Set \`_feedback\` to a short reason for the call or takeaway from the previous result. Avoid placeholders like \`first_call\`.
+- Set \`_feedbackTool\` to the current \`publicTool.action\`, e.g. \`heliusWallet.getBalance\`. Always send \`_model\`.`;

package/dist/router/register.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerRouterTools(server: McpServer): void;

package/dist/router/register.js

@@ -0,0 +1,15 @@
+import { dispatchRoutedTool, expandStoredResult } from './dispatch.js';
+import { withTelemetryHandler } from './telemetry.js';
+import { EXPAND_RESULT_SCHEMA, HELIUS_ACCOUNT_SCHEMA, HELIUS_ASSET_SCHEMA, HELIUS_CHAIN_SCHEMA, HELIUS_COMPRESSION_SCHEMA, HELIUS_KNOWLEDGE_SCHEMA, HELIUS_STREAMING_SCHEMA, HELIUS_TRANSACTION_SCHEMA, HELIUS_WALLET_SCHEMA, HELIUS_WRITE_SCHEMA, } from './schemas.js';
+export function registerRouterTools(server) {
+    server.tool('heliusAccount', 'Account setup, API keys, signup, plans, and billing. Use for pricing or account state, not per-method rate limits.', HELIUS_ACCOUNT_SCHEMA, withTelemetryHandler('heliusAccount', (params, extra) => dispatchRoutedTool('heliusAccount', params, extra)));
+    server.tool('heliusWallet', 'Wallet-centric balances, holdings, identity, and wallet history. Use for portfolio views, not raw token accounts.', HELIUS_WALLET_SCHEMA, withTelemetryHandler('heliusWallet', (params, extra) => dispatchRoutedTool('heliusWallet', params, extra)));
+    server.tool('heliusAsset', 'Assets, NFTs, collections, proofs, and token holders. Use for DAS ownership or metadata, not transaction history.', HELIUS_ASSET_SCHEMA, withTelemetryHandler('heliusAsset', (params, extra) => dispatchRoutedTool('heliusAsset', params, extra)));
+    server.tool('heliusTransaction', 'Parsed transactions and wallet transaction history. Use for activity analysis, not raw account state.', HELIUS_TRANSACTION_SCHEMA, withTelemetryHandler('heliusTransaction', (params, extra) => dispatchRoutedTool('heliusTransaction', params, extra)));
+    server.tool('heliusChain', 'Raw chain state, token accounts, stake reads, blocks, network status, and priority fees. Use for token accounts or blocks, not wallet portfolio summaries.', HELIUS_CHAIN_SCHEMA, withTelemetryHandler('heliusChain', (params, extra) => dispatchRoutedTool('heliusChain', params, extra)));
+    server.tool('heliusStreaming', 'Webhook CRUD and live subscription configuration. Use for actual webhook/subscription setup, not how-to guides.', HELIUS_STREAMING_SCHEMA, withTelemetryHandler('heliusStreaming', (params, extra) => dispatchRoutedTool('heliusStreaming', params, extra)));
+    server.tool('heliusKnowledge', 'Docs, guides, pricing references, troubleshooting, source, blog, and SIMD research. Use for guides, rate limits, or errors, not live mutations.', HELIUS_KNOWLEDGE_SCHEMA, withTelemetryHandler('heliusKnowledge', (params, extra) => dispatchRoutedTool('heliusKnowledge', params, extra)));
+    server.tool('heliusWrite', 'Mutating SOL/token transfer and staking actions. Use for sends or staking, not read-only queries.', HELIUS_WRITE_SCHEMA, withTelemetryHandler('heliusWrite', (params, extra) => dispatchRoutedTool('heliusWrite', params, extra)));
+    server.tool('heliusCompression', 'Compressed account, proof, balance, and compression history queries. Use for zk-compression state, not standard DAS assets.', HELIUS_COMPRESSION_SCHEMA, withTelemetryHandler('heliusCompression', (params, extra) => dispatchRoutedTool('heliusCompression', params, extra)));
+    server.tool('expandResult', 'Expand a prior summary-first result by resultId, section, range, page, or continuation.', EXPAND_RESULT_SCHEMA, withTelemetryHandler('expandResult', (params, extra) => expandStoredResult(params, extra)));
+}

package/dist/router/required-params.d.ts

@@ -0,0 +1,9 @@
+import type { ActionName } from './actions.js';
+/**
+ * Map of actions to their required top-level parameters.
+ *
+ * Only actions with unambiguous required fields are listed here.
+ * Actions with "one-of" requirements (e.g. getAsset needs `id` OR `ids`)
+ * or no required params are omitted — those rely on bespoke handler validation.
+ */
+export declare const ACTION_REQUIRED_PARAMS: Partial<Record<ActionName, string[]>>;

package/dist/router/required-params.js

@@ -0,0 +1,66 @@
+/**
+ * Map of actions to their required top-level parameters.
+ *
+ * Only actions with unambiguous required fields are listed here.
+ * Actions with "one-of" requirements (e.g. getAsset needs `id` OR `ids`)
+ * or no required params are omitted — those rely on bespoke handler validation.
+ */
+export const ACTION_REQUIRED_PARAMS = {
+    // Wallet
+    getBalance: ['address'],
+    getTokenBalances: ['address'],
+    getWalletBalances: ['address'],
+    getWalletHistory: ['address'],
+    getWalletTransfers: ['address'],
+    getWalletIdentity: ['address'],
+    batchWalletIdentity: ['addresses'],
+    getWalletFundedBy: ['address'],
+    // Transaction
+    parseTransactions: ['signatures'],
+    getTransactionHistory: ['address'],
+    getTransfersByAddress: ['address'],
+    // Asset
+    getAssetsByOwner: ['address'],
+    getAssetsByGroup: ['groupKey', 'groupValue'],
+    getAssetProof: ['id'],
+    getAssetProofBatch: ['ids'],
+    getSignaturesForAsset: ['id'],
+    getNftEditions: ['mint'],
+    // Chain
+    getTokenHolders: ['mint'],
+    getProgramAccounts: ['programId'],
+    getBlock: ['slot'],
+    getWithdrawableAmount: ['stakeAccount'],
+    // Streaming
+    createWebhook: ['webhookURL', 'accountAddresses'],
+    getWebhookByID: ['webhookID'],
+    updateWebhook: ['webhookID'],
+    deleteWebhook: ['webhookID'],
+    accountSubscribe: ['account'],
+    // Knowledge
+    troubleshootError: ['errorCode'],
+    recommendStack: ['description'],
+    getSIMD: ['number'],
+    searchSolanaDocs: ['query'],
+    readSolanaSourceFile: ['path'],
+    compareHeliusPlans: ['category'],
+    // Write
+    transferSol: ['recipientAddress'],
+    transferToken: ['recipientAddress', 'mintAddress'],
+    stakeSOL: ['amount'],
+    unstakeSOL: ['stakeAccount'],
+    withdrawStake: ['stakeAccount'],
+    // Compression
+    getCompressedAccountsByOwner: ['owner'],
+    getCompressedBalanceByOwner: ['owner'],
+    getCompressedMintTokenHolders: ['mint'],
+    getCompressedTokenAccountsByOwner: ['owner'],
+    getCompressedTokenAccountsByDelegate: ['delegate'],
+    getCompressedTokenBalancesByOwnerV2: ['owner'],
+    getCompressedAccountProof: ['hash'],
+    getCompressionSignaturesForAccount: ['hash'],
+    getCompressionSignaturesForAddress: ['address'],
+    getCompressionSignaturesForOwner: ['owner'],
+    getCompressionSignaturesForTokenOwner: ['owner'],
+    getTransactionWithCompressionInfo: ['signature'],
+};

package/dist/router/responses.d.ts

@@ -0,0 +1,29 @@
+import type { DetailLevel, ResponseFamily } from './types.js';
+export type RouterResponse = {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+    _meta?: Record<string, unknown>;
+};
+export declare function getFamilyLimit(family: ResponseFamily, detail: DetailLevel): number;
+export declare function toPlainText(response: {
+    content?: Array<{
+        type?: string;
+        text?: string;
+    }>;
+    structuredContent?: unknown;
+}): string;
+export declare function compactErrorText(text: string, maxChars?: number): string;
+export declare function cleanText(text: string): string;
+export declare function truncateText(text: string, limit: number): string;
+export declare function buildTextVariant(family: ResponseFamily, detail: DetailLevel, text: string): string;
+export declare function estimateRenderedSize(text: string): number;
+export declare function collectSectionHints(text: string): string[];
+export declare function applySectionSelection(text: string, section?: string): string;
+export declare function applyItemSelection(text: string, item?: number): string;
+export declare function applyRangeSelection(text: string, range?: string): string;
+export declare function mcpText(text: string, meta?: Record<string, unknown>): RouterResponse;
+export declare function mcpErrorCompact(text: string, meta?: Record<string, unknown>): RouterResponse;
+export declare function mcpResultHandle(summary: string, resultId: string, availableExpansions: string[], meta?: Record<string, unknown>): RouterResponse;

package/dist/router/responses.js

@@ -0,0 +1,186 @@
+import { extractSections } from '../utils/docs.js';
+const FAMILY_LIMITS = {
+    scalar: { summary: 800, standard: 1200, full: 1200 },
+    mutationReceipt: { summary: 1000, standard: 1500, full: 1500 },
+    record: { summary: 1500, standard: 3000, full: 8000 },
+    list: { summary: 2500, standard: 4500, full: 12000 },
+    history: { summary: 2500, standard: 4500, full: 12000 },
+    document: { summary: 2500, standard: 5000, full: 12000 },
+    streamingConfig: { summary: 2500, standard: 5000, full: 12000 },
+    catalog: { summary: 2500, standard: 5000, full: 12000 },
+};
+export function getFamilyLimit(family, detail) {
+    return FAMILY_LIMITS[family][detail];
+}
+export function toPlainText(response) {
+    const text = response.content
+        ?.filter((item) => item.type === 'text' || item.type === undefined)
+        .map((item) => item.text ?? '')
+        .join('\n\n')
+        .trim();
+    if (text) {
+        return text;
+    }
+    if (response.structuredContent !== undefined) {
+        return JSON.stringify(response.structuredContent, null, 2);
+    }
+    return '';
+}
+export function compactErrorText(text, maxChars = 1200) {
+    const withoutMeta = text
+        .replace(/^```json[\s\S]*?```\n*/i, '')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+    return truncateText(withoutMeta, maxChars);
+}
+export function cleanText(text) {
+    return text
+        .replace(/\r\n/g, '\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+export function truncateText(text, limit) {
+    if (text.length <= limit) {
+        return text;
+    }
+    const truncated = text.slice(0, limit);
+    const boundary = Math.max(truncated.lastIndexOf('\n## '), truncated.lastIndexOf('\n### '), truncated.lastIndexOf('\n---\n'), truncated.lastIndexOf('\n\n'));
+    const cut = boundary > limit * 0.55 ? boundary : limit;
+    return `${truncated.slice(0, cut).trim()}\n\n[truncated]`;
+}
+function stripExampleCode(text) {
+    const markers = ['**Example Code:**', '**Example:**', '```typescript', '```ts', '```javascript', '```js'];
+    let cut = text.length;
+    for (const marker of markers) {
+        const index = text.indexOf(marker);
+        if (index >= 0) {
+            cut = Math.min(cut, index);
+        }
+    }
+    return cut === text.length ? text : text.slice(0, cut).trim();
+}
+function summarizeDocument(text, limit) {
+    const headings = Array.from(text.matchAll(/^#{1,3}\s+.+$/gm))
+        .map((match) => match[0])
+        .slice(0, 5);
+    const intro = text
+        .split('\n\n')
+        .map((part) => part.trim())
+        .filter(Boolean)
+        .slice(0, 3)
+        .join('\n\n');
+    const body = headings.length > 0 ? `${headings.join('\n')}\n\n${intro}` : intro || text;
+    return truncateText(body, limit);
+}
+function summarizeListLike(text, limit) {
+    const sections = text.split(/\n---\n|\n\n(?=\*\*|\p{Emoji_Presentation}|\p{Emoji}\s)/u);
+    const picked = [];
+    let current = 0;
+    for (const section of sections) {
+        const trimmed = section.trim();
+        if (!trimmed) {
+            continue;
+        }
+        const nextLength = current + trimmed.length + 2;
+        if (picked.length > 0 && nextLength > limit) {
+            break;
+        }
+        picked.push(trimmed);
+        current = nextLength;
+    }
+    const summary = picked.join('\n\n');
+    return truncateText(summary || text, limit);
+}
+export function buildTextVariant(family, detail, text) {
+    const limit = getFamilyLimit(family, detail);
+    const cleaned = cleanText(text);
+    if (!cleaned) {
+        return '';
+    }
+    if (detail === 'full') {
+        return truncateText(cleaned, limit);
+    }
+    switch (family) {
+        case 'streamingConfig':
+            return truncateText(stripExampleCode(cleaned), limit);
+        case 'document':
+            return summarizeDocument(stripExampleCode(cleaned), limit);
+        case 'list':
+        case 'history':
+        case 'catalog':
+            return summarizeListLike(stripExampleCode(cleaned), limit);
+        case 'scalar':
+        case 'mutationReceipt':
+        case 'record':
+        default:
+            return truncateText(stripExampleCode(cleaned), limit);
+    }
+}
+export function estimateRenderedSize(text) {
+    return cleanText(text).length;
+}
+export function collectSectionHints(text) {
+    return Array.from(text.matchAll(/^#{1,3}\s+(.+)$/gm))
+        .map((match) => match[1].trim())
+        .filter(Boolean)
+        .slice(0, 12);
+}
+export function applySectionSelection(text, section) {
+    if (!section) {
+        return text;
+    }
+    const extracted = extractSections(text, section, { includeLooseMatches: true });
+    if (extracted) {
+        return extracted;
+    }
+    return `No section matching "${section}" was found.\n\n${text}`;
+}
+export function applyItemSelection(text, item) {
+    if (item === undefined) {
+        return text;
+    }
+    const sections = text
+        .split(/\n---\n|\n\n(?=\*\*|\p{Emoji_Presentation}|\p{Emoji}\s)/u)
+        .map((part) => part.trim())
+        .filter(Boolean);
+    const index = item - 1;
+    if (index < 0 || index >= sections.length) {
+        return `Item ${item} was not found.\n\n${text}`;
+    }
+    return sections[index];
+}
+export function applyRangeSelection(text, range) {
+    if (!range) {
+        return text;
+    }
+    const match = range.match(/^(\d+):(\d+)$/);
+    if (!match) {
+        return `Invalid range "${range}". Expected "start:end".\n\n${text}`;
+    }
+    const start = Number(match[1]);
+    const end = Number(match[2]);
+    if (!Number.isInteger(start) || !Number.isInteger(end) || start < 0 || end <= start) {
+        return `Invalid range "${range}". Expected "start:end" with start >= 0 and end > start.\n\n${text}`;
+    }
+    return text.slice(start, end);
+}
+export function mcpText(text, meta) {
+    return {
+        content: [{ type: 'text', text }],
+        ...(meta === undefined ? {} : { _meta: meta }),
+    };
+}
+export function mcpErrorCompact(text, meta) {
+    return {
+        content: [{ type: 'text', text }],
+        isError: true,
+        ...(meta === undefined ? {} : { _meta: meta }),
+    };
+}
+export function mcpResultHandle(summary, resultId, availableExpansions, meta) {
+    const lines = [summary, '', `resultId: ${resultId}`];
+    if (availableExpansions.length > 0) {
+        lines.push(`expand: ${availableExpansions.join(', ')}`);
+    }
+    return mcpText(lines.join('\n'), meta);
+}