mcp-researchpowerpack 3.6.9

package/dist/tools/utils.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Shared Tool Utilities
+ * Extracted from individual handlers to eliminate duplication
+ */
+export { mcpLog, safeLog as safeLogSimple, createToolLogger, type LogLevel, type ToolLogger as SimpleToolLogger, } from '../utils/logger.js';
+export { formatSuccess, formatError, formatBatchHeader, formatList, formatDuration, truncateText, type SuccessOptions, type ErrorOptions, type BatchHeaderOptions, type ListItem, } from '../utils/response.js';
+/**
+ * Centralized token budgets for all tools
+ */
+export declare const TOKEN_BUDGETS: {
+    /** Deep research total budget */
+    readonly RESEARCH: 32000;
+    /** Web scraper total budget */
+    readonly SCRAPER: 32000;
+    /** Reddit comment budget per batch */
+    readonly REDDIT_COMMENTS: 1000;
+};
+/**
+ * Logger function type used by tools
+ */
+export type ToolLogger = (level: 'info' | 'error' | 'debug', message: string, sessionId: string) => Promise<void>;
+/**
+ * Standard tool options passed to handlers
+ */
+export interface ToolOptions {
+    sessionId?: string;
+    logger?: ToolLogger;
+}
+/**
+ * Safe logger wrapper - NEVER throws
+ * Logs to provided logger or falls back to console.error
+ *
+ * @param logger - Optional logger function
+ * @param sessionId - Session ID for logging context
+ * @param level - Log level
+ * @param message - Message to log
+ * @param toolName - Name of the tool for prefixing
+ */
+export declare function safeLog(logger: ToolLogger | undefined, sessionId: string | undefined, level: 'info' | 'error' | 'debug', message: string, toolName: string): Promise<void>;
+/**
+ * Calculate token allocation for batch operations
+ * Distributes a fixed budget across multiple items
+ *
+ * @param count - Number of items to distribute budget across
+ * @param budget - Total token budget
+ * @returns Tokens per item
+ */
+export declare function calculateTokenAllocation(count: number, budget: number): number;
+/**
+ * Format retry hint based on error retryability
+ *
+ * @param retryable - Whether the error is retryable
+ * @returns Hint string or empty string
+ */
+export declare function formatRetryHint(retryable: boolean): string;
+/**
+ * Create a standard error markdown response
+ *
+ * @param toolName - Name of the tool that errored
+ * @param errorCode - Error code
+ * @param message - Error message
+ * @param retryable - Whether error is retryable
+ * @param tip - Optional tip for resolution
+ * @returns Formatted markdown error string
+ */
+export declare function formatToolError(toolName: string, errorCode: string, message: string, retryable: boolean, tip?: string): string;
+/**
+ * Validate that a value is a non-empty array
+ *
+ * @param value - Value to check
+ * @param fieldName - Field name for error message
+ * @returns Error message or undefined if valid
+ */
+export declare function validateNonEmptyArray(value: unknown, fieldName: string): string | undefined;
+/**
+ * Validate array length is within bounds
+ *
+ * @param arr - Array to check
+ * @param min - Minimum length
+ * @param max - Maximum length
+ * @param fieldName - Field name for error message
+ * @returns Error message or undefined if valid
+ */
+export declare function validateArrayBounds(arr: unknown[], min: number, max: number, fieldName: string): string | undefined;
+/**
+ * Build standard header for batch operation results
+ *
+ * @param title - Title of the results section
+ * @param count - Number of items processed
+ * @param tokensPerItem - Tokens allocated per item
+ * @param totalBudget - Total token budget
+ * @returns Formatted header string
+ */
+export declare function buildBatchHeader(title: string, count: number, tokensPerItem: number, totalBudget: number): string;
+/**
+ * Build status line for batch results
+ *
+ * @param successful - Number of successful items
+ * @param failed - Number of failed items
+ * @param batches - Number of batches processed
+ * @param extras - Optional extra status items
+ * @returns Formatted status line
+ */
+export declare function buildStatusLine(successful: number, failed: number, batches: number, extras?: string[]): string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/tools/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/tools/utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EACL,MAAM,EACN,OAAO,IAAI,aAAa,EACxB,gBAAgB,EAChB,KAAK,QAAQ,EACb,KAAK,UAAU,IAAI,gBAAgB,GACpC,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,UAAU,EACV,cAAc,EACd,YAAY,EACZ,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,QAAQ,GACd,MAAM,sBAAsB,CAAC;AAM9B;;GAEG;AACH,eAAO,MAAM,aAAa;IACxB,iCAAiC;;IAEjC,+BAA+B;;IAE/B,sCAAsC;;CAE9B,CAAC;AAMX;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,CACvB,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,EACjC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,KACd,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAMD;;;;;;;;;GASG;AACH,wBAAsB,OAAO,CAC3B,MAAM,EAAE,UAAU,GAAG,SAAS,EAC9B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,EACjC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAQf;AAMD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAG9E;AAMD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,CAI1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,OAAO,EAClB,GAAG,CAAC,EAAE,MAAM,GACX,MAAM,CAIR;AAMD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CAQpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,OAAO,EAAE,EACd,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CAQpB;AAMD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,MAAM,GAClB,MAAM,CAER;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,EAAE,GAChB,MAAM,CAMR"}

package/dist/tools/utils.js

@@ -0,0 +1,159 @@
+/**
+ * Shared Tool Utilities
+ * Extracted from individual handlers to eliminate duplication
+ */
+// Re-export from centralized modules
+export { mcpLog, safeLog as safeLogSimple, createToolLogger, } from '../utils/logger.js';
+export { formatSuccess, formatError, formatBatchHeader, formatList, formatDuration, truncateText, } from '../utils/response.js';
+// ============================================================================
+// Token Budget Constants
+// ============================================================================
+/**
+ * Centralized token budgets for all tools
+ */
+export const TOKEN_BUDGETS = {
+    /** Deep research total budget */
+    RESEARCH: 32_000,
+    /** Web scraper total budget */
+    SCRAPER: 32_000,
+    /** Reddit comment budget per batch */
+    REDDIT_COMMENTS: 1_000,
+};
+// ============================================================================
+// Logging Utilities
+// ============================================================================
+/**
+ * Safe logger wrapper - NEVER throws
+ * Logs to provided logger or falls back to console.error
+ *
+ * @param logger - Optional logger function
+ * @param sessionId - Session ID for logging context
+ * @param level - Log level
+ * @param message - Message to log
+ * @param toolName - Name of the tool for prefixing
+ */
+export async function safeLog(logger, sessionId, level, message, toolName) {
+    if (!logger || !sessionId)
+        return;
+    try {
+        await logger(level, `[${toolName}] ${message}`, sessionId);
+    }
+    catch {
+        // Silently ignore logger errors - they should never crash the tool
+        console.error(`[${toolName}] Logger failed: ${message}`);
+    }
+}
+// ============================================================================
+// Token Allocation
+// ============================================================================
+/**
+ * Calculate token allocation for batch operations
+ * Distributes a fixed budget across multiple items
+ *
+ * @param count - Number of items to distribute budget across
+ * @param budget - Total token budget
+ * @returns Tokens per item
+ */
+export function calculateTokenAllocation(count, budget) {
+    if (count <= 0)
+        return budget;
+    return Math.floor(budget / count);
+}
+// ============================================================================
+// Error Formatting
+// ============================================================================
+/**
+ * Format retry hint based on error retryability
+ *
+ * @param retryable - Whether the error is retryable
+ * @returns Hint string or empty string
+ */
+export function formatRetryHint(retryable) {
+    return retryable
+        ? '\n\n💡 This error may be temporary. Try again in a moment.'
+        : '';
+}
+/**
+ * Create a standard error markdown response
+ *
+ * @param toolName - Name of the tool that errored
+ * @param errorCode - Error code
+ * @param message - Error message
+ * @param retryable - Whether error is retryable
+ * @param tip - Optional tip for resolution
+ * @returns Formatted markdown error string
+ */
+export function formatToolError(toolName, errorCode, message, retryable, tip) {
+    const retryHint = formatRetryHint(retryable);
+    const tipSection = tip ? `\n\n**Tip:** ${tip}` : '';
+    return `# ❌ ${toolName}: Operation Failed\n\n**${errorCode}:** ${message}${retryHint}${tipSection}`;
+}
+// ============================================================================
+// Validation Helpers
+// ============================================================================
+/**
+ * Validate that a value is a non-empty array
+ *
+ * @param value - Value to check
+ * @param fieldName - Field name for error message
+ * @returns Error message or undefined if valid
+ */
+export function validateNonEmptyArray(value, fieldName) {
+    if (!Array.isArray(value)) {
+        return `${fieldName} must be an array`;
+    }
+    if (value.length === 0) {
+        return `${fieldName} must not be empty`;
+    }
+    return undefined;
+}
+/**
+ * Validate array length is within bounds
+ *
+ * @param arr - Array to check
+ * @param min - Minimum length
+ * @param max - Maximum length
+ * @param fieldName - Field name for error message
+ * @returns Error message or undefined if valid
+ */
+export function validateArrayBounds(arr, min, max, fieldName) {
+    if (arr.length < min) {
+        return `${fieldName} requires at least ${min} items. Received: ${arr.length}`;
+    }
+    if (arr.length > max) {
+        return `${fieldName} allows at most ${max} items. Received: ${arr.length}. Please remove ${arr.length - max} item(s).`;
+    }
+    return undefined;
+}
+// ============================================================================
+// Response Builders
+// ============================================================================
+/**
+ * Build standard header for batch operation results
+ *
+ * @param title - Title of the results section
+ * @param count - Number of items processed
+ * @param tokensPerItem - Tokens allocated per item
+ * @param totalBudget - Total token budget
+ * @returns Formatted header string
+ */
+export function buildBatchHeader(title, count, tokensPerItem, totalBudget) {
+    return `# ${title} (${count} items)\n\n**Token Allocation:** ${tokensPerItem.toLocaleString()} tokens/item (${count} items, ${totalBudget.toLocaleString()} total budget)`;
+}
+/**
+ * Build status line for batch results
+ *
+ * @param successful - Number of successful items
+ * @param failed - Number of failed items
+ * @param batches - Number of batches processed
+ * @param extras - Optional extra status items
+ * @returns Formatted status line
+ */
+export function buildStatusLine(successful, failed, batches, extras) {
+    let status = `**Status:** ✅ ${successful} successful | ❌ ${failed} failed | 📦 ${batches} batch(es)`;
+    if (extras && extras.length > 0) {
+        status += ` | ${extras.join(' | ')}`;
+    }
+    return status;
+}
+//# sourceMappingURL=utils.js.map

package/dist/tools/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/tools/utils.ts"],"names":[],"mappings":"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"}

package/dist/utils/concurrency.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Concurrency utilities for bounded parallel execution
+ * Prevents CPU spikes and API rate limiting from unbounded Promise.all
+ */
+/**
+ * Execute async tasks with a concurrency limit (like p-map).
+ * Processes items from the input array through the mapper function,
+ * running at most `concurrency` tasks simultaneously.
+ *
+ * NEVER throws - if the mapper throws, the error propagates per-item
+ * (caller should handle via try/catch in mapper or use Promise.allSettled pattern).
+ *
+ * @param items - Array of items to process
+ * @param mapper - Async function to apply to each item
+ * @param concurrency - Maximum number of concurrent tasks (default: 6)
+ * @returns Array of results in the same order as input items
+ */
+export declare function pMap<T, R>(items: T[], mapper: (item: T, index: number) => Promise<R>, concurrency?: number): Promise<R[]>;
+/**
+ * Like pMap but uses Promise.allSettled semantics — never rejects,
+ * returns PromiseSettledResult for each item.
+ *
+ * @param items - Array of items to process
+ * @param mapper - Async function to apply to each item
+ * @param concurrency - Maximum number of concurrent tasks (default: 6)
+ * @returns Array of PromiseSettledResult in the same order as input items
+ */
+export declare function pMapSettled<T, R>(items: T[], mapper: (item: T, index: number) => Promise<R>, concurrency?: number): Promise<PromiseSettledResult<R>[]>;
+//# sourceMappingURL=concurrency.d.ts.map

package/dist/utils/concurrency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.d.ts","sourceRoot":"","sources":["../../src/utils/concurrency.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAsB,IAAI,CAAC,CAAC,EAAE,CAAC,EAC7B,KAAK,EAAE,CAAC,EAAE,EACV,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC9C,WAAW,GAAE,MAAU,GACtB,OAAO,CAAC,CAAC,EAAE,CAAC,CAwBd;AAED;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,CAAC,EAAE,CAAC,EACpC,KAAK,EAAE,CAAC,EAAE,EACV,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC9C,WAAW,GAAE,MAAU,GACtB,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC,EAAE,CAAC,CA2BpC"}

package/dist/utils/concurrency.js

@@ -0,0 +1,73 @@
+/**
+ * Concurrency utilities for bounded parallel execution
+ * Prevents CPU spikes and API rate limiting from unbounded Promise.all
+ */
+/**
+ * Execute async tasks with a concurrency limit (like p-map).
+ * Processes items from the input array through the mapper function,
+ * running at most `concurrency` tasks simultaneously.
+ *
+ * NEVER throws - if the mapper throws, the error propagates per-item
+ * (caller should handle via try/catch in mapper or use Promise.allSettled pattern).
+ *
+ * @param items - Array of items to process
+ * @param mapper - Async function to apply to each item
+ * @param concurrency - Maximum number of concurrent tasks (default: 6)
+ * @returns Array of results in the same order as input items
+ */
+export async function pMap(items, mapper, concurrency = 6) {
+    if (items.length === 0)
+        return [];
+    // Clamp concurrency to reasonable bounds
+    const limit = Math.max(1, Math.min(concurrency, items.length));
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    async function worker() {
+        while (nextIndex < items.length) {
+            const index = nextIndex++;
+            results[index] = await mapper(items[index], index);
+        }
+    }
+    // Spawn `limit` workers that pull from the shared index
+    const workers = [];
+    for (let i = 0; i < limit; i++) {
+        workers.push(worker());
+    }
+    await Promise.all(workers);
+    return results;
+}
+/**
+ * Like pMap but uses Promise.allSettled semantics — never rejects,
+ * returns PromiseSettledResult for each item.
+ *
+ * @param items - Array of items to process
+ * @param mapper - Async function to apply to each item
+ * @param concurrency - Maximum number of concurrent tasks (default: 6)
+ * @returns Array of PromiseSettledResult in the same order as input items
+ */
+export async function pMapSettled(items, mapper, concurrency = 6) {
+    if (items.length === 0)
+        return [];
+    const limit = Math.max(1, Math.min(concurrency, items.length));
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    async function worker() {
+        while (nextIndex < items.length) {
+            const index = nextIndex++;
+            try {
+                const value = await mapper(items[index], index);
+                results[index] = { status: 'fulfilled', value };
+            }
+            catch (reason) {
+                results[index] = { status: 'rejected', reason };
+            }
+        }
+    }
+    const workers = [];
+    for (let i = 0; i < limit; i++) {
+        workers.push(worker());
+    }
+    await Promise.all(workers);
+    return results;
+}
+//# sourceMappingURL=concurrency.js.map

package/dist/utils/concurrency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.js","sourceRoot":"","sources":["../../src/utils/concurrency.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,IAAI,CACxB,KAAU,EACV,MAA8C,EAC9C,cAAsB,CAAC;IAEvB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAElC,yCAAyC;IACzC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IAE/D,MAAM,OAAO,GAAQ,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC7C,IAAI,SAAS,GAAG,CAAC,CAAC;IAElB,KAAK,UAAU,MAAM;QACnB,OAAO,SAAS,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;YAChC,MAAM,KAAK,GAAG,SAAS,EAAE,CAAC;YAC1B,OAAO,CAAC,KAAK,CAAC,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;IAED,wDAAwD;IACxD,MAAM,OAAO,GAAoB,EAAE,CAAC;IACpC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/B,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IACzB,CAAC;IAED,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC3B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,KAAU,EACV,MAA8C,EAC9C,cAAsB,CAAC;IAEvB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAElC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IAE/D,MAAM,OAAO,GAA8B,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACnE,IAAI,SAAS,GAAG,CAAC,CAAC;IAElB,KAAK,UAAU,MAAM;QACnB,OAAO,SAAS,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;YAChC,MAAM,KAAK,GAAG,SAAS,EAAE,CAAC;YAC1B,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;gBAChD,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;YAClD,CAAC;YAAC,OAAO,MAAM,EAAE,CAAC;gBAChB,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;YAClD,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAoB,EAAE,CAAC;IACpC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/B,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IACzB,CAAC;IAED,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC3B,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/utils/errors.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Robust error handling utilities for MCP server
+ * Ensures the server NEVER crashes and always returns structured responses
+ */
+export declare const ErrorCode: {
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly TIMEOUT: "TIMEOUT";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
+    readonly AUTH_ERROR: "AUTH_ERROR";
+    readonly INVALID_INPUT: "INVALID_INPUT";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly QUOTA_EXCEEDED: "QUOTA_EXCEEDED";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly PARSE_ERROR: "PARSE_ERROR";
+    readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
+};
+type ErrorCodeType = typeof ErrorCode[keyof typeof ErrorCode];
+export interface StructuredError {
+    code: ErrorCodeType;
+    message: string;
+    retryable: boolean;
+    statusCode?: number;
+    cause?: string;
+}
+/**
+ * Classify any error into a structured format
+ * NEVER throws - always returns a valid StructuredError
+ */
+export declare function classifyError(error: unknown): StructuredError;
+/**
+ * Sleep utility that respects abort signals
+ */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * Wrap a fetch call with timeout via AbortController
+ */
+export declare function fetchWithTimeout(url: string, options?: RequestInit & {
+    timeoutMs?: number;
+}): Promise<Response>;
+/**
+ * MCP-compliant error codes for tool responses
+ * These codes are exposed to clients for programmatic error handling
+ */
+export declare const MCP_ERROR_CODES: {
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly TIMEOUT: "TIMEOUT";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly AUTH_ERROR: "AUTH_ERROR";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
+};
+export type McpErrorCodeType = typeof MCP_ERROR_CODES[keyof typeof MCP_ERROR_CODES];
+/**
+ * Structured response type for MCP tool errors
+ * Per MCP spec: tools return isError:true for recoverable/tool-level failures
+ * Uses index signature for SDK compatibility with additional fields
+ */
+interface ToolErrorResponse {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError: true;
+    errorCode?: McpErrorCodeType;
+    retryAfter?: number;
+    [key: string]: unknown;
+}
+/**
+ * Create a tool error response from a StructuredError
+ * Automatically maps error codes and calculates retryAfter for rate limits
+ */
+export declare function createToolErrorFromStructured(structuredError: StructuredError, attempt?: number): ToolErrorResponse;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/utils/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,eAAO,MAAM,SAAS;;;;;;;;;;;;CAiBZ,CAAC;AAEX,KAAK,aAAa,GAAG,OAAO,SAAS,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAM9D,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAqBD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CA4F7D;AAkDD;;GAEG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAcrE;AAiDD;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,WAAW,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACjD,OAAO,CAAC,QAAQ,CAAC,CAcnB;AAsCD;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;;;;;;CASlB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,OAAO,eAAe,CAAC,MAAM,OAAO,eAAe,CAAC,CAAC;AAEpF;;;;GAIG;AACH,UAAU,iBAAiB;IACzB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,EAAE,IAAI,CAAC;IACd,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAyDD;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,eAAe,EAAE,eAAe,EAChC,OAAO,GAAE,MAAU,GAClB,iBAAiB,CAgBnB"}