@j0hanz/fetch-url-mcp 1.12.7 → 1.12.8

package/dist/index.js

@@ -1,12 +1,73 @@
 #!/usr/bin/env node
 import process from 'node:process';
-import { serverVersion } from './lib/core.js';
-import { logError } from './lib/core.js';
-import { Loggers } from './lib/logger-names.js';
-import { toError } from './lib/utils.js';
-import { parseCliArgs, renderCliUsage } from './cli.js';
-import { startHttpServer } from './http/native.js';
+import { parseArgs } from 'node:util';
+import { logError, Loggers, serverVersion } from './lib/core.js';
+import { getErrorMessage, toError } from './lib/error/index.js';
+import { startHttpServer } from './http/index.js';
 import { startStdioServer } from './server.js';
+const usageLines = [
+    'Fetch URL MCP server',
+    '',
+    'Usage:',
+    '  fetch-url-mcp [--stdio|-s | --http] [--help|-h] [--version|-v]',
+    '',
+    'Options:',
+    '  --stdio, -s   Run in stdio mode (default).',
+    '  --http        Run in Streamable HTTP mode.',
+    '  --help, -h    Show this help message.',
+    '  --version, -v Show server version.',
+    '',
+];
+const optionSchema = {
+    stdio: { type: 'boolean', short: 's', default: false },
+    http: { type: 'boolean', default: false },
+    help: { type: 'boolean', short: 'h', default: false },
+    version: { type: 'boolean', short: 'v', default: false },
+};
+function toBoolean(value) {
+    return value === true;
+}
+function readCliFlag(values, key) {
+    return toBoolean(values[key]);
+}
+function buildCliValues(values) {
+    return {
+        stdio: readCliFlag(values, 'stdio'),
+        http: readCliFlag(values, 'http'),
+        help: readCliFlag(values, 'help'),
+        version: readCliFlag(values, 'version'),
+    };
+}
+export function renderCliUsage() {
+    return `${usageLines.join('\n')}\n`;
+}
+export function parseCliArgs(args) {
+    try {
+        const { values } = parseArgs({
+            args: [...args],
+            options: optionSchema,
+            strict: true,
+            allowPositionals: false,
+        });
+        const cliValues = buildCliValues(values);
+        if (cliValues.stdio && cliValues.http) {
+            return {
+                ok: false,
+                message: 'Choose either --stdio or --http, not both',
+            };
+        }
+        return {
+            ok: true,
+            values: cliValues,
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            message: getErrorMessage(error),
+        };
+    }
+}
 const FORCE_EXIT_TIMEOUT_MS = 10_000;
 let forcedExitTimer;
 function writeAndExit(stream, text, code) {

package/dist/lib/config.js

@@ -2,8 +2,8 @@ import { readFileSync } from 'node:fs';
 import { findPackageJSON } from 'node:module';
 import process from 'node:process';
 import { z } from 'zod';
-import { buildIpv4, isIP, normalizeHostname, stripTrailingDots, } from './url.js';
-import { getErrorMessage } from './utils.js';
+import { getErrorMessage } from './error/index.js';
+import { buildIpv4, isIP, normalizeHostname, stripTrailingDots, } from './net/url.js';
 // ── Version ─────────────────────────────────────────────────────────
 function getObjectProperty(value, key) {
     return value[key];

package/dist/lib/core.d.ts

@@ -1,6 +1,5 @@
 import { type McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { SessionEntry } from './session.js';
-import type { SessionStore } from './session.js';
+import type { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 export { config, enableHttpMode, serverVersion } from './config.js';
 type LogMetadata = Record<string, unknown>;
 interface RequestContext {
@@ -27,10 +26,63 @@ export declare function logError(message: string, error?: Error | LogMetadata, l
 export declare function logCritical(message: string, error?: Error | LogMetadata, logger?: string): void;
 export declare function setLogLevel(level: string, sessionId?: string): void;
 export declare function redactUrl(rawUrl: string): string;
-export type { SessionEntry, SessionStore } from './session.js';
-export { composeCloseHandlers, createSessionStore, createSlotTracker, ensureSessionCapacity, reserveSessionSlot, } from './session.js';
 export declare function startSessionCleanupLoop(store: SessionStore, sessionTtlMs: number, options?: {
     onEvictSession?: (session: SessionEntry) => Promise<void> | void;
     cleanupIntervalMs?: number;
 }): AbortController;
+/**
+ * Logger names for different components of the application.
+ */
+export declare const Loggers: {
+    readonly LOG_AUTH: "auth";
+    readonly LOG_HTTP: "http";
+    readonly LOG_SESSION: "session";
+    readonly LOG_SERVER: "server";
+    readonly LOG_FETCH: "fetch";
+    readonly LOG_TRANSFORM: "transform";
+    readonly LOG_TASKS: "tasks";
+    readonly LOG_RATE_LIMIT: "rate-limit";
+    readonly LOG_MCP: "mcp";
+    readonly LOG_FETCH_URL: "fetch-url";
+};
+export interface SessionEntry {
+    readonly server: McpServer;
+    readonly transport: StreamableHTTPServerTransport;
+    createdAt: number;
+    lastSeen: number;
+    protocolInitialized: boolean;
+    negotiatedProtocolVersion: string;
+    authFingerprint: string;
+}
+export interface SessionStore {
+    get: (sessionId: string) => SessionEntry | undefined;
+    touch: (sessionId: string) => void;
+    set: (sessionId: string, entry: SessionEntry) => void;
+    remove: (sessionId: string) => SessionEntry | undefined;
+    size: () => number;
+    inFlight: () => number;
+    incrementInFlight: () => void;
+    decrementInFlight: () => void;
+    clear: () => SessionEntry[];
+    evictExpired: () => {
+        id: string;
+        entry: SessionEntry;
+    }[];
+    evictOldest: () => SessionEntry | undefined;
+}
+interface SlotTracker {
+    readonly releaseSlot: () => void;
+    readonly markInitialized: () => void;
+    readonly isInitialized: () => boolean;
+}
+type CloseHandler = (() => void) | undefined;
+export declare function composeCloseHandlers(first: CloseHandler, second: CloseHandler): CloseHandler;
+export declare function createSessionStore(sessionTtlMs: number): SessionStore;
+export declare function createSlotTracker(store: SessionStore): SlotTracker;
+export declare function reserveSessionSlot(store: SessionStore, maxSessions: number): boolean;
+export declare function ensureSessionCapacity({ store, maxSessions, evictOldest, }: {
+    store: SessionStore;
+    maxSessions: number;
+    evictOldest: (store: SessionStore) => boolean;
+}): boolean;
 //# sourceMappingURL=core.d.ts.map

package/dist/lib/core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/lib/core.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIzE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAOjD,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAYpE,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC3C,UAAU,cAAc;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AA6BD,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAKpD;AACD,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,SAAS,GAChB,IAAI,CAGN;AACD,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,IAAI,CAGN;AACD,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAKlE;AACD,wBAAgB,kCAAkC,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAO1E;AACD,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CAEpB;AACD,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,SAAS,GAChB,MAAM,GAAG,SAAS,CAKpB;AACD,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,OAAO,EAAE,cAAc,EACvB,EAAE,EAAE,MAAM,CAAC,GACV,CAAC,CAEH;AAID,wBAAgB,YAAY,IAAI,MAAM,GAAG,SAAS,CAGjD;AACD,wBAAgB,YAAY,IAAI,MAAM,GAAG,SAAS,CAEjD;AACD,wBAAgB,cAAc,IAAI,MAAM,GAAG,SAAS,CAEnD;AAscD,wBAAgB,OAAO,CACrB,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,WAAW,EAClB,MAAM,CAAC,EAAE,MAAM,GACd,IAAI,CAEN;AACD,wBAAgB,QAAQ,CACtB,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,WAAW,EAClB,MAAM,CAAC,EAAE,MAAM,GACd,IAAI,CAEN;AACD,wBAAgB,SAAS,CACvB,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,WAAW,EAClB,MAAM,CAAC,EAAE,MAAM,GACd,IAAI,CAEN;AACD,wBAAgB,OAAO,CACrB,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,WAAW,EAClB,MAAM,CAAC,EAAE,MAAM,GACd,IAAI,CAEN;AAcD,wBAAgB,QAAQ,CACtB,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,KAAK,GAAG,WAAW,EAC3B,MAAM,CAAC,EAAE,MAAM,GACd,IAAI,CAIN;AACD,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,KAAK,GAAG,WAAW,EAC3B,MAAM,CAAC,EAAE,MAAM,GACd,IAAI,CAIN;AACD,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAUnE;AACD,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAQhD;AACD,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,cAAc,CAAC;AA+KtB,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,YAAY,EACnB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE;IACR,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACjE,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,GACA,eAAe,CAQjB"}
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/lib/core.ts"],"names":[],"mappings":"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"}

package/dist/lib/core.js

@@ -1,10 +1,10 @@
+import {} from '@modelcontextprotocol/sdk/server/mcp.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import process from 'node:process';
 import { getSystemErrorMessage, inspect, stripVTControlCharacters, } from 'node:util';
-import {} from '@modelcontextprotocol/sdk/server/mcp.js';
 import { config } from './config.js';
-import { Loggers } from './logger-names.js';
-import { getErrorMessage, isAbortError, startAbortableIntervalLoop, } from './utils.js';
+import { getErrorMessage, isAbortError } from './error/index.js';
+import { startAbortableIntervalLoop } from './utils.js';
 export { config, enableHttpMode, serverVersion } from './config.js';
 const requestContext = new AsyncLocalStorage({
     name: 'requestContext',
@@ -502,7 +502,6 @@ export function redactUrl(rawUrl) {
     url.search = '';
     return url.toString();
 }
-export { composeCloseHandlers, createSessionStore, createSlotTracker, ensureSessionCapacity, reserveSessionSlot, } from './session.js';
 const MIN_CLEANUP_INTERVAL_MS = 10_000;
 const MAX_CLEANUP_INTERVAL_MS = 60_000;
 const SESSION_CLOSE_BATCH_SIZE = 10;
@@ -626,3 +625,155 @@ export function startSessionCleanupLoop(store, sessionTtlMs, options) {
     const loop = new SessionCleanupLoop(store, sessionTtlMs, options?.onEvictSession, options?.cleanupIntervalMs);
     return loop.start();
 }
+/**
+ * Logger names for different components of the application.
+ */
+export const Loggers = {
+    LOG_AUTH: 'auth',
+    LOG_HTTP: 'http',
+    LOG_SESSION: 'session',
+    LOG_SERVER: 'server',
+    LOG_FETCH: 'fetch',
+    LOG_TRANSFORM: 'transform',
+    LOG_TASKS: 'tasks',
+    LOG_RATE_LIMIT: 'rate-limit',
+    LOG_MCP: 'mcp',
+    LOG_FETCH_URL: 'fetch-url',
+};
+export function composeCloseHandlers(first, second) {
+    if (!first)
+        return second;
+    if (!second)
+        return first;
+    return () => {
+        try {
+            first();
+        }
+        finally {
+            second();
+        }
+    };
+}
+/* -------------------------------------------------------------------------------------------------
+ * In-memory session store
+ * ------------------------------------------------------------------------------------------------- */
+class InMemorySessionStore {
+    sessionTtlMs;
+    sessions = new Map();
+    inflight = 0;
+    constructor(sessionTtlMs) {
+        this.sessionTtlMs = sessionTtlMs;
+    }
+    get(sessionId) {
+        if (sessionId.length === 0)
+            return undefined;
+        return this.sessions.get(sessionId);
+    }
+    touch(sessionId) {
+        if (sessionId.length === 0)
+            return;
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return;
+        session.lastSeen = Date.now();
+        this.sessions.delete(sessionId);
+        this.sessions.set(sessionId, session);
+    }
+    set(sessionId, entry) {
+        if (sessionId.length === 0)
+            return;
+        this.sessions.delete(sessionId);
+        this.sessions.set(sessionId, entry);
+    }
+    remove(sessionId) {
+        if (sessionId.length === 0)
+            return undefined;
+        const session = this.sessions.get(sessionId);
+        this.sessions.delete(sessionId);
+        return session;
+    }
+    size() {
+        return this.sessions.size;
+    }
+    inFlight() {
+        return this.inflight;
+    }
+    incrementInFlight() {
+        this.inflight += 1;
+    }
+    decrementInFlight() {
+        if (this.inflight === 0)
+            return;
+        this.inflight -= 1;
+    }
+    clear() {
+        const entries = [...this.sessions.values()];
+        this.sessions.clear();
+        return entries;
+    }
+    evictExpired() {
+        const now = Date.now();
+        const evicted = [];
+        for (const [id, session] of this.sessions.entries()) {
+            if (this.sessionTtlMs > 0 && now - session.lastSeen > this.sessionTtlMs) {
+                this.sessions.delete(id);
+                evicted.push({ id, entry: session });
+            }
+            else {
+                break;
+            }
+        }
+        return evicted;
+    }
+    evictOldest() {
+        const oldest = this.sessions.keys().next();
+        if (oldest.done)
+            return undefined;
+        const session = this.sessions.get(oldest.value);
+        this.sessions.delete(oldest.value);
+        return session;
+    }
+}
+export function createSessionStore(sessionTtlMs) {
+    const store = new InMemorySessionStore(sessionTtlMs);
+    return store;
+}
+/* -------------------------------------------------------------------------------------------------
+ * Slot tracking and capacity
+ * ------------------------------------------------------------------------------------------------- */
+export function createSlotTracker(store) {
+    let slotReleased = false;
+    let initialized = false;
+    return {
+        releaseSlot() {
+            if (slotReleased)
+                return;
+            slotReleased = true;
+            store.decrementInFlight();
+        },
+        markInitialized() {
+            initialized = true;
+        },
+        isInitialized() {
+            return initialized;
+        },
+    };
+}
+export function reserveSessionSlot(store, maxSessions) {
+    if (maxSessions <= 0)
+        return false;
+    if (store.size() + store.inFlight() >= maxSessions)
+        return false;
+    store.incrementInFlight();
+    return true;
+}
+export function ensureSessionCapacity({ store, maxSessions, evictOldest, }) {
+    if (maxSessions <= 0)
+        return false;
+    if (store.size() + store.inFlight() < maxSessions)
+        return true;
+    if (store.size() > 0 && evictOldest(store)) {
+        return store.size() + store.inFlight() < maxSessions;
+    }
+    return false;
+}

package/dist/lib/error/classes.d.ts

@@ -0,0 +1,19 @@
+export declare function isError(value: unknown): value is Error;
+export declare class FetchError extends Error {
+    readonly url: string;
+    readonly statusCode: number;
+    readonly code: string;
+    readonly details: Readonly<Record<string, unknown>>;
+    constructor(message: string, url: string, httpStatus?: number, details?: Record<string, unknown>, options?: ErrorOptions);
+}
+export declare class CodedError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string, options?: ErrorOptions);
+}
+export declare function isAbortError(error: unknown): boolean;
+export declare function isSystemError(error: unknown): error is NodeJS.ErrnoException;
+export declare function getErrorMessage(error: unknown): string;
+export declare function toError(error: unknown): Error;
+export declare function throwIfAborted(signal: AbortSignal | undefined, url: string, stage: string): void;
+export declare function createAbortError(url: string, stage: string): FetchError;
+//# sourceMappingURL=classes.d.ts.map

package/dist/lib/error/classes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classes.d.ts","sourceRoot":"","sources":["../../../src/lib/error/classes.ts"],"names":[],"mappings":"AAWA,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,CAQtD;AAMD,qBAAa,UAAW,SAAQ,KAAK;IAOjC,QAAQ,CAAC,GAAG,EAAE,MAAM;IANtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;gBAGlD,OAAO,EAAE,MAAM,EACN,GAAG,EAAE,MAAM,EACpB,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACrC,OAAO,CAAC,EAAE,YAAY;CAezB;AAED,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAKlE;AAID,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEpD;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,cAAc,CAK5E;AAMD,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAsBtD;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAE7C;AAID,wBAAgB,cAAc,CAC5B,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,GACZ,IAAI,CAYN;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,CAMvE"}

package/dist/lib/error/classes.js

@@ -0,0 +1,107 @@
+import { inspect } from 'node:util';
+import { isObject } from '../utils.js';
+import { SystemErrors } from './codes.js';
+export function isError(value) {
+    const maybeIsError = Error.isError;
+    if (typeof maybeIsError === 'function') {
+        const result = maybeIsError(value);
+        if (typeof result === 'boolean')
+            return result;
+    }
+    return value instanceof Error;
+}
+// ── Error classes ──────────────────────────────────────────────────
+const DEFAULT_HTTP_STATUS = 502;
+export class FetchError extends Error {
+    url;
+    statusCode;
+    code;
+    details;
+    constructor(message, url, httpStatus, details = {}, options) {
+        super(message, options);
+        this.url = url;
+        this.name = 'FetchError';
+        this.statusCode = httpStatus ?? DEFAULT_HTTP_STATUS;
+        this.details = Object.freeze({ url, httpStatus, ...details });
+        const explicitCode = this.details['code'];
+        if (typeof explicitCode === 'string') {
+            this.code = explicitCode;
+        }
+        else if (httpStatus) {
+            this.code = `HTTP_${httpStatus}`;
+        }
+        else {
+            this.code = SystemErrors.FETCH_ERROR;
+        }
+    }
+}
+export class CodedError extends Error {
+    code;
+    constructor(message, code, options) {
+        super(message, options);
+        this.code = code;
+        this.name = 'CodedError';
+    }
+}
+// ── Error guards ───────────────────────────────────────────────────
+export function isAbortError(error) {
+    return isError(error) && error.name === 'AbortError';
+}
+export function isSystemError(error) {
+    if (!isError(error))
+        return false;
+    if (!('code' in error))
+        return false;
+    const { code } = error;
+    return typeof code === 'string';
+}
+// ── Error extraction ───────────────────────────────────────────────
+const UNKNOWN_ERROR_MESSAGE = 'Unknown error';
+export function getErrorMessage(error) {
+    if (isError(error))
+        return error.message;
+    if (typeof error === 'string' && error.length > 0)
+        return error;
+    if (isObject(error) &&
+        typeof error['message'] === 'string' &&
+        error['message'].length > 0) {
+        return error['message'];
+    }
+    if (error === null || error === undefined)
+        return UNKNOWN_ERROR_MESSAGE;
+    try {
+        return inspect(error, {
+            depth: 2,
+            maxStringLength: 200,
+            breakLength: Infinity,
+            compact: true,
+            colors: false,
+        });
+    }
+    catch {
+        return UNKNOWN_ERROR_MESSAGE;
+    }
+}
+export function toError(error) {
+    return isError(error) ? error : new Error(getErrorMessage(error));
+}
+// ── Abort helpers ──────────────────────────────────────────────────
+export function throwIfAborted(signal, url, stage) {
+    if (!signal?.aborted)
+        return;
+    if (signal.reason instanceof Error && signal.reason.name === 'TimeoutError') {
+        const error = new FetchError('Request timeout', url, 504, {
+            reason: 'timeout',
+            stage,
+        });
+        throw error;
+    }
+    throw createAbortError(url, stage);
+}
+export function createAbortError(url, stage) {
+    const error = new FetchError('Request was canceled', url, 499, {
+        reason: 'aborted',
+        stage,
+    });
+    return error;
+}

package/dist/lib/error/classify.d.ts

@@ -0,0 +1,4 @@
+import { type ToolErrorLogMeta, type ToolErrorResponse } from './payload.js';
+export declare function handleToolError(error: unknown, url: string, fallbackMessage?: string): ToolErrorResponse;
+export declare function classifyAndLogToolError(error: unknown, meta: ToolErrorLogMeta, loggerName: string, toolName: string, fallbackMessage: string): ToolErrorResponse;
+//# sourceMappingURL=classify.d.ts.map

package/dist/lib/error/classify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify.d.ts","sourceRoot":"","sources":["../../../src/lib/error/classify.ts"],"names":[],"mappings":"AAKA,OAAO,EAIL,KAAK,gBAAgB,EAErB,KAAK,iBAAiB,EACvB,MAAM,cAAc,CAAC;AA4JtB,wBAAgB,eAAe,CAC7B,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,MAAM,EACX,eAAe,SAAqB,GACnC,iBAAiB,CAInB;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,gBAAgB,EACtB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,GACtB,iBAAiB,CAuCnB"}

package/dist/lib/error/classify.js

@@ -0,0 +1,154 @@
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { logError, logWarn } from '../core.js';
+import { FetchError, isAbortError, isSystemError } from './classes.js';
+import { ErrorCategory, SystemErrors } from './codes.js';
+import { createToolErrorResponse, sanitizeToolErrorDetails, stripMcpErrorPrefix, } from './payload.js';
+function toToolErrorResponse(payload) {
+    return createToolErrorResponse(payload.error, payload.url, payload);
+}
+function isValidationError(error) {
+    return (error instanceof Error &&
+        isSystemError(error) &&
+        error.code === SystemErrors.VALIDATION_ERROR);
+}
+function buildUpstreamHttpMessage(error) {
+    const { statusCode } = error;
+    if (statusCode === 404) {
+        return `We couldn't find the resource at the target URL.`;
+    }
+    return `An error occurred when communicating with the target URL.`;
+}
+function mapFetchToolError(error, fallbackUrl) {
+    const { code: detailsCode, reason } = error.details;
+    let { code } = error;
+    if (typeof detailsCode === 'string') {
+        code = detailsCode;
+    }
+    else if (reason === SystemErrors.QUEUE_FULL) {
+        code = SystemErrors.QUEUE_FULL;
+    }
+    const url = error.url || fallbackUrl;
+    const details = sanitizeToolErrorDetails(error.details);
+    if (reason === 'timeout') {
+        return {
+            error: 'The request to the target timed out.',
+            url,
+            category: ErrorCategory.UPSTREAM_TIMEOUT,
+            code,
+            statusCode: error.statusCode,
+            upstreamMessage: error.message,
+            ...(details ? { details } : {}),
+        };
+    }
+    if (reason === 'aborted') {
+        return {
+            error: 'The request to the target was cancelled.',
+            url,
+            category: ErrorCategory.UPSTREAM_ABORTED,
+            code,
+            statusCode: error.statusCode,
+            upstreamMessage: error.message,
+            ...(details ? { details } : {}),
+        };
+    }
+    if (reason === SystemErrors.QUEUE_FULL) {
+        return {
+            error: error.message,
+            url,
+            category: ErrorCategory.QUEUE_FULL,
+            code,
+            statusCode: error.statusCode,
+            ...(details ? { details } : {}),
+        };
+    }
+    const isRealHttpError = typeof error.details['httpStatus'] === 'number';
+    if (isRealHttpError && error.statusCode >= 400) {
+        return {
+            error: buildUpstreamHttpMessage(error),
+            url,
+            category: error.statusCode === 429
+                ? ErrorCategory.UPSTREAM_RATE_LIMITED
+                : ErrorCategory.UPSTREAM_HTTP_ERROR,
+            code,
+            statusCode: error.statusCode,
+            upstreamMessage: error.message,
+            ...(details ? { details } : {}),
+        };
+    }
+    return {
+        error: error.message,
+        url,
+        category: ErrorCategory.FETCH_ERROR,
+        code,
+        statusCode: error.statusCode,
+        ...(details ? { details } : {}),
+    };
+}
+function mapGenericToolError(error, url, fallbackMessage) {
+    if (isValidationError(error)) {
+        return {
+            error: error.message,
+            url,
+            category: ErrorCategory.VALIDATION_ERROR,
+            code: SystemErrors.VALIDATION_ERROR,
+        };
+    }
+    const isAborted = isAbortError(error);
+    return {
+        error: error instanceof Error
+            ? error.message
+            : `${fallbackMessage}: unknown error`,
+        url,
+        category: isAborted
+            ? ErrorCategory.UPSTREAM_ABORTED
+            : ErrorCategory.FETCH_ERROR,
+        code: isAborted ? SystemErrors.ABORTED : SystemErrors.FETCH_ERROR,
+    };
+}
+function mapMcpToolError(error, url) {
+    return {
+        error: stripMcpErrorPrefix(error.message),
+        url,
+        category: ErrorCategory.MCP_ERROR,
+        code: error.code,
+        statusCode: error.code,
+        ...(error.data !== undefined ? { data: error.data } : {}),
+    };
+}
+function resolveToolErrorPayload(error, url, fallbackMessage) {
+    if (error instanceof FetchError) {
+        return mapFetchToolError(error, url);
+    }
+    if (error instanceof McpError) {
+        return mapMcpToolError(error, url);
+    }
+    return mapGenericToolError(error, url, fallbackMessage);
+}
+export function handleToolError(error, url, fallbackMessage = 'Operation failed') {
+    return toToolErrorResponse(resolveToolErrorPayload(error, url, fallbackMessage));
+}
+export function classifyAndLogToolError(error, meta, loggerName, toolName, fallbackMessage) {
+    if (error instanceof McpError) {
+        if (error.code === ErrorCode.MethodNotFound) {
+            logError(`${toolName} tool protocol error`, { url: meta.url, durationMs: meta.durationMs, error }, loggerName);
+            throw error;
+        }
+        logWarn(`${toolName} tool error`, { url: meta.url, durationMs: meta.durationMs, error }, loggerName);
+        return handleToolError(error, meta.url, fallbackMessage);
+    }
+    if (error instanceof FetchError || isAbortError(error)) {
+        logWarn(`${toolName} request failed`, {
+            url: meta.url,
+            error: error instanceof Error ? error.message : String(error),
+            durationMs: meta.durationMs,
+        }, loggerName);
+    }
+    else {
+        logError(`${toolName} request failed unexpectedly`, {
+            url: meta.url,
+            error: error instanceof Error ? error.message : String(error),
+            durationMs: meta.durationMs,
+        }, loggerName);
+    }
+    return handleToolError(error, meta.url, fallbackMessage);
+}

package/dist/lib/error/codes.d.ts

@@ -0,0 +1,23 @@
+export declare const SystemErrors: {
+    readonly EBLOCKED: "EBLOCKED";
+    readonly ETIMEOUT: "ETIMEOUT";
+    readonly EINVAL: "EINVAL";
+    readonly ENODATA: "ENODATA";
+    readonly EBADREDIRECT: "EBADREDIRECT";
+    readonly EUNSUPPORTEDPROTOCOL: "EUNSUPPORTEDPROTOCOL";
+    readonly FETCH_ERROR: "FETCH_ERROR";
+    readonly ABORTED: "ABORTED";
+    readonly QUEUE_FULL: "queue_full";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+};
+export declare const ErrorCategory: {
+    readonly UPSTREAM_TIMEOUT: "upstream_timeout";
+    readonly UPSTREAM_ABORTED: "upstream_aborted";
+    readonly UPSTREAM_RATE_LIMITED: "upstream_rate_limited";
+    readonly UPSTREAM_HTTP_ERROR: "upstream_http_error";
+    readonly QUEUE_FULL: "queue_full";
+    readonly FETCH_ERROR: "fetch_error";
+    readonly VALIDATION_ERROR: "validation_error";
+    readonly MCP_ERROR: "mcp_error";
+};
+//# sourceMappingURL=codes.d.ts.map