@j0hanz/fetch-url-mcp 1.4.0 → 1.5.0

package/dist/lib/core.js

@@ -0,0 +1,1228 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { EventEmitter } from 'node:events';
+import { accessSync, constants as fsConstants, readFileSync } from 'node:fs';
+import { findPackageJSON } from 'node:module';
+import { isIP } from 'node:net';
+import process from 'node:process';
+import { domainToASCII } from 'node:url';
+import { inspect, stripVTControlCharacters } from 'node:util';
+import {} from '@modelcontextprotocol/sdk/server/mcp.js';
+import {} from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { z } from 'zod';
+import { getErrorMessage, isAbortError, sha256Hex, stableStringify as stableJsonStringify, startAbortableIntervalLoop, } from './utils.js';
+export const serverVersion = readServerVersion(import.meta.url);
+const LOG_LEVELS = ['debug', 'info', 'warn', 'error'];
+const ALLOWED_LOG_LEVELS = new Set(LOG_LEVELS);
+const DEFAULT_HEADING_KEYWORDS = [
+    'overview',
+    'introduction',
+    'summary',
+    'conclusion',
+    'prerequisites',
+    'requirements',
+    'installation',
+    'configuration',
+    'usage',
+    'features',
+    'limitations',
+    'troubleshooting',
+    'faq',
+    'resources',
+    'references',
+    'changelog',
+    'license',
+    'acknowledgments',
+    'appendix',
+];
+class ConfigError extends Error {
+    name = 'ConfigError';
+}
+function isMissingEnvFileError(error) {
+    if (!error || typeof error !== 'object')
+        return false;
+    const { code } = error;
+    return code === 'ENOENT' || code === 'ERR_ENV_FILE_NOT_FOUND';
+}
+function loadEnvFileIfAvailable() {
+    if (typeof process.loadEnvFile !== 'function')
+        return;
+    try {
+        process.loadEnvFile();
+    }
+    catch (error) {
+        if (isMissingEnvFileError(error))
+            return;
+        throw error;
+    }
+}
+loadEnvFileIfAvailable();
+const { env } = process;
+function buildIpv4(parts) {
+    return parts.join('.');
+}
+function stripTrailingDots(value) {
+    let result = value;
+    while (result.endsWith('.'))
+        result = result.slice(0, -1);
+    return result;
+}
+function formatHostForUrl(hostname) {
+    if (hostname.includes(':') && !hostname.startsWith('['))
+        return `[${hostname}]`;
+    return hostname;
+}
+function normalizeHostname(value) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        return null;
+    const lowered = trimmed.toLowerCase();
+    const ipType = isIP(lowered);
+    if (ipType)
+        return stripTrailingDots(lowered);
+    const ascii = domainToASCII(lowered);
+    return ascii ? stripTrailingDots(ascii) : null;
+}
+function normalizeHostValue(value) {
+    const raw = value.trim();
+    if (!raw)
+        return null;
+    // Full URL
+    if (raw.includes('://')) {
+        if (!URL.canParse(raw))
+            return null;
+        return normalizeHostname(new URL(raw).hostname);
+    }
+    // host[:port]
+    const candidateUrl = `http://${raw}`;
+    if (URL.canParse(candidateUrl)) {
+        return normalizeHostname(new URL(candidateUrl).hostname);
+    }
+    const lowered = raw.toLowerCase();
+    // [::1]:port
+    if (lowered.startsWith('[')) {
+        const end = lowered.indexOf(']');
+        if (end === -1)
+            return null;
+        return normalizeHostname(lowered.slice(1, end));
+    }
+    // Bare IPv6
+    if (isIP(lowered) === 6)
+        return stripTrailingDots(lowered);
+    // Split host:port (single colon only)
+    const firstColon = lowered.indexOf(':');
+    if (firstColon === -1)
+        return normalizeHostname(lowered);
+    if (lowered.includes(':', firstColon + 1))
+        return null;
+    const host = lowered.slice(0, firstColon);
+    return host ? normalizeHostname(host) : null;
+}
+function parseIntegerValue(envValue, min, max) {
+    if (!envValue)
+        return null;
+    const parsed = Number.parseInt(envValue, 10);
+    if (Number.isNaN(parsed))
+        return null;
+    if (min !== undefined && parsed < min)
+        return null;
+    if (max !== undefined && parsed > max)
+        return null;
+    return parsed;
+}
+function parseOptionalInteger(envValue, min, max) {
+    return parseIntegerValue(envValue, min, max) ?? undefined;
+}
+function parseInteger(envValue, defaultValue, min, max) {
+    return parseIntegerValue(envValue, min, max) ?? defaultValue;
+}
+function parseBoolean(envValue, defaultValue) {
+    if (!envValue)
+        return defaultValue;
+    return envValue.trim().toLowerCase() !== 'false';
+}
+function parseList(envValue) {
+    if (!envValue)
+        return [];
+    return envValue
+        .split(/[\s,]+/)
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+}
+function parseListOrDefault(envValue, defaultValue) {
+    const parsed = parseList(envValue);
+    return parsed.length > 0 ? parsed : [...defaultValue];
+}
+function normalizeLocale(value) {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return undefined;
+    const lowered = trimmed.toLowerCase();
+    if (lowered === 'system' || lowered === 'default')
+        return undefined;
+    return trimmed;
+}
+function isLogLevel(value) {
+    return ALLOWED_LOG_LEVELS.has(value);
+}
+function parseLogLevel(envValue) {
+    if (!envValue)
+        return 'info';
+    const level = envValue.toLowerCase();
+    return isLogLevel(level) ? level : 'info';
+}
+function parseTransformWorkerMode(envValue) {
+    if (!envValue)
+        return 'threads';
+    const normalized = envValue.trim().toLowerCase();
+    if (normalized === 'process' || normalized === 'fork')
+        return 'process';
+    return 'threads';
+}
+function parsePort(envValue) {
+    if (envValue?.trim() === '0')
+        return 0;
+    return parseInteger(envValue, 3000, 1024, 65535);
+}
+function parseUrlEnv(value, name) {
+    if (!value)
+        return undefined;
+    if (!URL.canParse(value)) {
+        throw new ConfigError(`Invalid ${name} value: ${value}`);
+    }
+    return new URL(value);
+}
+function readUrlEnv(name) {
+    return parseUrlEnv(env[name], name);
+}
+function parseAllowedHosts(envValue) {
+    const hosts = new Set();
+    for (const entry of parseList(envValue)) {
+        const normalized = normalizeHostValue(entry);
+        if (normalized)
+            hosts.add(normalized);
+    }
+    return hosts;
+}
+function readOptionalFilePath(value) {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function assertFileReadable(filePath, envVar) {
+    try {
+        accessSync(filePath, fsConstants.R_OK);
+    }
+    catch {
+        throw new ConfigError(`${envVar} points to "${filePath}" which does not exist or is not readable`);
+    }
+}
+const MAX_HTML_BYTES = 10 * 1024 * 1024;
+const MAX_INLINE_CONTENT_CHARS = parseInteger(env['MAX_INLINE_CONTENT_CHARS'], 0, 0, MAX_HTML_BYTES);
+const DEFAULT_SESSION_TTL_MS = 30 * 60 * 1000;
+const DEFAULT_SESSION_INIT_TIMEOUT_MS = 10000;
+const DEFAULT_MAX_SESSIONS = 200;
+const DEFAULT_USER_AGENT = `fetch-url-mcp/${serverVersion}`;
+const DEFAULT_TOOL_TIMEOUT_PADDING_MS = 5000;
+const DEFAULT_TRANSFORM_TIMEOUT_MS = 30000;
+const DEFAULT_FETCH_TIMEOUT_MS = parseInteger(env['FETCH_TIMEOUT_MS'], 15000, 1000, 60000);
+const DEFAULT_TOOL_TIMEOUT_MS = DEFAULT_FETCH_TIMEOUT_MS +
+    DEFAULT_TRANSFORM_TIMEOUT_MS +
+    DEFAULT_TOOL_TIMEOUT_PADDING_MS;
+const DEFAULT_TASKS_MAX_TOTAL = parseInteger(env['TASKS_MAX_TOTAL'], 5000, 1);
+const DEFAULT_TASKS_MAX_PER_OWNER = parseInteger(env['TASKS_MAX_PER_OWNER'], 1000, 1);
+const RESOLVED_TASKS_MAX_PER_OWNER = Math.min(DEFAULT_TASKS_MAX_PER_OWNER, DEFAULT_TASKS_MAX_TOTAL);
+function resolveWorkerResourceLimits() {
+    const limits = {};
+    let hasAny = false;
+    const entries = [
+        [
+            'maxOldGenerationSizeMb',
+            parseOptionalInteger(env['TRANSFORM_WORKER_MAX_OLD_GENERATION_MB'], 1),
+        ],
+        [
+            'maxYoungGenerationSizeMb',
+            parseOptionalInteger(env['TRANSFORM_WORKER_MAX_YOUNG_GENERATION_MB'], 1),
+        ],
+        [
+            'codeRangeSizeMb',
+            parseOptionalInteger(env['TRANSFORM_WORKER_CODE_RANGE_MB'], 1),
+        ],
+        ['stackSizeMb', parseOptionalInteger(env['TRANSFORM_WORKER_STACK_MB'], 1)],
+    ];
+    for (const [key, value] of entries) {
+        if (value === undefined)
+            continue;
+        limits[key] = value;
+        hasAny = true;
+    }
+    return hasAny ? limits : undefined;
+}
+function readOAuthUrls(baseUrl) {
+    const issuerUrl = readUrlEnv('OAUTH_ISSUER_URL');
+    const authorizationUrl = readUrlEnv('OAUTH_AUTHORIZATION_URL');
+    const tokenUrl = readUrlEnv('OAUTH_TOKEN_URL');
+    const revocationUrl = readUrlEnv('OAUTH_REVOCATION_URL');
+    const registrationUrl = readUrlEnv('OAUTH_REGISTRATION_URL');
+    const introspectionUrl = readUrlEnv('OAUTH_INTROSPECTION_URL');
+    const resourceUrl = new URL('/mcp', baseUrl);
+    return {
+        issuerUrl,
+        authorizationUrl,
+        tokenUrl,
+        revocationUrl,
+        registrationUrl,
+        introspectionUrl,
+        resourceUrl,
+    };
+}
+function resolveAuthMode(urls) {
+    const oauthConfigured = [
+        urls.issuerUrl,
+        urls.authorizationUrl,
+        urls.tokenUrl,
+        urls.introspectionUrl,
+    ].some((value) => value !== undefined);
+    return oauthConfigured ? 'oauth' : 'static';
+}
+function collectStaticTokens() {
+    const staticTokens = new Set(parseList(env['ACCESS_TOKENS']));
+    if (env['API_KEY'])
+        staticTokens.add(env['API_KEY']);
+    return [...staticTokens];
+}
+function buildAuthConfig(baseUrl) {
+    const urls = readOAuthUrls(baseUrl);
+    const mode = resolveAuthMode(urls);
+    return {
+        mode,
+        ...urls,
+        requiredScopes: parseList(env['OAUTH_REQUIRED_SCOPES']),
+        clientId: env['OAUTH_CLIENT_ID'],
+        clientSecret: env['OAUTH_CLIENT_SECRET'],
+        introspectionTimeoutMs: 5000,
+        staticTokens: collectStaticTokens(),
+    };
+}
+function buildHttpsConfig() {
+    const keyFile = readOptionalFilePath(env['SERVER_TLS_KEY_FILE']);
+    const certFile = readOptionalFilePath(env['SERVER_TLS_CERT_FILE']);
+    const caFile = readOptionalFilePath(env['SERVER_TLS_CA_FILE']);
+    if (keyFile)
+        assertFileReadable(keyFile, 'SERVER_TLS_KEY_FILE');
+    if (certFile)
+        assertFileReadable(certFile, 'SERVER_TLS_CERT_FILE');
+    if (caFile)
+        assertFileReadable(caFile, 'SERVER_TLS_CA_FILE');
+    if ((keyFile && !certFile) || (!keyFile && certFile)) {
+        throw new ConfigError('Both SERVER_TLS_KEY_FILE and SERVER_TLS_CERT_FILE must be set together');
+    }
+    return {
+        enabled: Boolean(keyFile && certFile),
+        keyFile,
+        certFile,
+        caFile,
+    };
+}
+const LOOPBACK_V4 = buildIpv4([127, 0, 0, 1]);
+const ANY_V4 = buildIpv4([0, 0, 0, 0]);
+const METADATA_V4_AWS = buildIpv4([169, 254, 169, 254]);
+const METADATA_V4_AZURE = buildIpv4([100, 100, 100, 200]);
+const BLOCKED_HOSTS = new Set([
+    'localhost',
+    LOOPBACK_V4,
+    ANY_V4,
+    '::1',
+    METADATA_V4_AWS,
+    'metadata.google.internal',
+    'metadata.azure.com',
+    METADATA_V4_AZURE,
+    'instance-data',
+]);
+const host = (env['HOST'] ?? LOOPBACK_V4).trim();
+const port = parsePort(env['PORT']);
+const httpsConfig = buildHttpsConfig();
+const maxConnections = parseInteger(env['SERVER_MAX_CONNECTIONS'], 0, 0);
+const headersTimeoutMs = parseOptionalInteger(env['SERVER_HEADERS_TIMEOUT_MS'], 1);
+const requestTimeoutMs = parseOptionalInteger(env['SERVER_REQUEST_TIMEOUT_MS'], 0);
+const keepAliveTimeoutMs = parseOptionalInteger(env['SERVER_KEEP_ALIVE_TIMEOUT_MS'], 1);
+const keepAliveTimeoutBufferMs = parseOptionalInteger(env['SERVER_KEEP_ALIVE_TIMEOUT_BUFFER_MS'], 0);
+const maxHeadersCount = parseOptionalInteger(env['SERVER_MAX_HEADERS_COUNT'], 1);
+const blockPrivateConnections = parseBoolean(env['SERVER_BLOCK_PRIVATE_CONNECTIONS'], false);
+const allowRemote = parseBoolean(env['ALLOW_REMOTE'], false);
+const requireProtocolVersionHeaderOnSessionInit = parseBoolean(env['MCP_STRICT_PROTOCOL_VERSION_HEADER'], true);
+const baseUrl = new URL(`${httpsConfig.enabled ? 'https' : 'http'}://${formatHostForUrl(host)}:${port}`);
+const runtimeState = {
+    httpMode: false,
+};
+export const config = {
+    server: {
+        name: 'fetch-url-mcp',
+        version: serverVersion,
+        port,
+        host,
+        https: httpsConfig,
+        sessionTtlMs: DEFAULT_SESSION_TTL_MS,
+        sessionInitTimeoutMs: DEFAULT_SESSION_INIT_TIMEOUT_MS,
+        maxSessions: DEFAULT_MAX_SESSIONS,
+        http: {
+            headersTimeoutMs,
+            requestTimeoutMs,
+            keepAliveTimeoutMs,
+            keepAliveTimeoutBufferMs,
+            maxHeadersCount,
+            maxConnections,
+            blockPrivateConnections,
+            requireProtocolVersionHeaderOnSessionInit,
+            shutdownCloseIdleConnections: true,
+            shutdownCloseAllConnections: false,
+        },
+    },
+    fetcher: {
+        timeout: DEFAULT_FETCH_TIMEOUT_MS,
+        maxRedirects: 5,
+        userAgent: env['USER_AGENT'] ?? DEFAULT_USER_AGENT,
+        maxContentLength: MAX_HTML_BYTES,
+    },
+    transform: {
+        timeoutMs: DEFAULT_TRANSFORM_TIMEOUT_MS,
+        stageWarnRatio: 0.5,
+        metadataFormat: 'markdown',
+        maxWorkerScale: 4,
+        cancelAckTimeoutMs: parseInteger(env['TRANSFORM_CANCEL_ACK_TIMEOUT_MS'], 200, 50, 5000),
+        workerMode: parseTransformWorkerMode(env['TRANSFORM_WORKER_MODE']),
+        workerResourceLimits: resolveWorkerResourceLimits(),
+    },
+    tools: {
+        enabled: ['fetch-url'],
+        timeoutMs: DEFAULT_TOOL_TIMEOUT_MS,
+    },
+    tasks: {
+        maxTotal: DEFAULT_TASKS_MAX_TOTAL,
+        maxPerOwner: RESOLVED_TASKS_MAX_PER_OWNER,
+        emitStatusNotifications: parseBoolean(env['TASKS_STATUS_NOTIFICATIONS'], false),
+    },
+    cache: {
+        enabled: parseBoolean(env['CACHE_ENABLED'], true),
+        ttl: 86400,
+        maxKeys: 100,
+        maxSizeBytes: 50 * 1024 * 1024, // 50MB
+    },
+    extraction: {
+        maxBlockLength: 5000,
+        minParagraphLength: 10,
+    },
+    noiseRemoval: {
+        extraTokens: parseList(env['FETCH_URL_MCP_EXTRA_NOISE_TOKENS']),
+        extraSelectors: parseList(env['FETCH_URL_MCP_EXTRA_NOISE_SELECTORS']),
+        enabledCategories: [
+            'cookie-banners',
+            'newsletters',
+            'social-share',
+            'nav-footer',
+        ],
+        debug: false,
+        aggressiveMode: false,
+        preserveSvgCanvas: false,
+        weights: {
+            hidden: 50,
+            structural: 50,
+            promo: 35,
+            stickyFixed: 30,
+            threshold: 50,
+        },
+    },
+    markdownCleanup: {
+        promoteOrphanHeadings: true,
+        removeSkipLinks: true,
+        removeTocBlocks: true,
+        removeTypeDocComments: true,
+        headingKeywords: parseListOrDefault(env['MARKDOWN_HEADING_KEYWORDS'], DEFAULT_HEADING_KEYWORDS),
+    },
+    i18n: {
+        locale: normalizeLocale(env['FETCH_URL_MCP_LOCALE']),
+    },
+    logging: {
+        level: parseLogLevel(env['LOG_LEVEL']),
+        format: env['LOG_FORMAT']?.toLowerCase() === 'json' ? 'json' : 'text',
+    },
+    constants: {
+        maxHtmlSize: MAX_HTML_BYTES,
+        maxUrlLength: 2048,
+        maxInlineContentChars: MAX_INLINE_CONTENT_CHARS,
+    },
+    security: {
+        blockedHosts: BLOCKED_HOSTS,
+        allowedHosts: parseAllowedHosts(env['ALLOWED_HOSTS']),
+        apiKey: env['API_KEY'],
+        allowRemote,
+    },
+    auth: buildAuthConfig(baseUrl),
+    rateLimit: {
+        enabled: true,
+        maxRequests: 100,
+        windowMs: 60000,
+        cleanupIntervalMs: 60000,
+    },
+    runtime: runtimeState,
+};
+export function enableHttpMode() {
+    runtimeState.httpMode = true;
+}
+const CachedPayloadSchema = z.strictObject({
+    content: z.string().optional(),
+    markdown: z.string().optional(),
+    title: z.string().optional(),
+});
+const CACHE_CONSTANTS = {
+    URL_HASH_LENGTH: 32,
+    VARY_HASH_LENGTH: 16,
+};
+export function parseCachedPayload(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        return CachedPayloadSchema.parse(parsed);
+    }
+    catch {
+        return null;
+    }
+}
+export function resolveCachedPayloadContent(payload) {
+    return payload.markdown ?? payload.content ?? null;
+}
+function createHashFragment(input, length) {
+    return sha256Hex(input).substring(0, length);
+}
+function buildCacheKey(namespace, urlHash, varyHash) {
+    return varyHash
+        ? `${namespace}:${urlHash}.${varyHash}`
+        : `${namespace}:${urlHash}`;
+}
+function resolveVaryString(vary) {
+    if (typeof vary === 'string')
+        return vary;
+    try {
+        return stableJsonStringify(vary);
+    }
+    catch {
+        return null;
+    }
+}
+export function createCacheKey(namespace, url, vary) {
+    if (!namespace || !url)
+        return null;
+    const urlHash = createHashFragment(url, CACHE_CONSTANTS.URL_HASH_LENGTH);
+    let varyHash;
+    if (vary) {
+        const varyString = resolveVaryString(vary);
+        if (varyString === null)
+            return null;
+        if (varyString) {
+            varyHash = createHashFragment(varyString, CACHE_CONSTANTS.VARY_HASH_LENGTH);
+        }
+    }
+    return buildCacheKey(namespace, urlHash, varyHash);
+}
+export function parseCacheKey(cacheKey) {
+    if (!cacheKey)
+        return null;
+    const separatorIndex = cacheKey.indexOf(':');
+    if (separatorIndex === -1)
+        return null;
+    const namespace = cacheKey.slice(0, separatorIndex);
+    const urlHash = cacheKey.slice(separatorIndex + 1);
+    if (!namespace || !urlHash)
+        return null;
+    return { namespace, urlHash };
+}
+class InMemoryCacheStore {
+    max = config.cache.maxKeys;
+    maxBytes = config.cache.maxSizeBytes;
+    ttlMs = config.cache.ttl * 1000;
+    entries = new Map();
+    updateEmitter = new EventEmitter();
+    currentBytes = 0;
+    isEnabled() {
+        return config.cache.enabled;
+    }
+    isExpired(entry, now = Date.now()) {
+        return entry.expiresAtMs <= now;
+    }
+    keys() {
+        if (!this.isEnabled())
+            return [];
+        const now = Date.now();
+        const result = [];
+        for (const [key, entry] of this.entries) {
+            if (!this.isExpired(entry, now))
+                result.push(key);
+        }
+        return result;
+    }
+    onUpdate(listener) {
+        const wrapped = (event) => {
+            try {
+                const result = listener(event);
+                if (result instanceof Promise) {
+                    void result.catch((error) => {
+                        this.logError('Cache update listener failed (async)', event.cacheKey, error);
+                    });
+                }
+            }
+            catch (error) {
+                this.logError('Cache update listener failed', event.cacheKey, error);
+            }
+        };
+        this.updateEmitter.on('update', wrapped);
+        return () => {
+            this.updateEmitter.off('update', wrapped);
+        };
+    }
+    get(cacheKey, options) {
+        if (!cacheKey || (!this.isEnabled() && !options?.force))
+            return undefined;
+        const entry = this.entries.get(cacheKey);
+        if (!entry)
+            return undefined;
+        const now = Date.now();
+        if (this.isExpired(entry, now)) {
+            this.delete(cacheKey);
+            // listChanged=false: lazy eviction on read is silent — only writes change
+            // the list. Clients must not rely on list-changed events from reads.
+            this.notify(cacheKey, false);
+            return undefined;
+        }
+        // Refresh LRU position
+        this.entries.delete(cacheKey);
+        this.entries.set(cacheKey, entry);
+        return entry;
+    }
+    delete(cacheKey) {
+        const entry = this.entries.get(cacheKey);
+        if (entry) {
+            this.currentBytes -= entry.content.length;
+            this.entries.delete(cacheKey);
+            return true;
+        }
+        return false;
+    }
+    evictOldestEntry() {
+        const firstKey = this.entries.keys().next();
+        return !firstKey.done && this.delete(firstKey.value);
+    }
+    set(cacheKey, content, metadata, options) {
+        if (!cacheKey || !content)
+            return;
+        if (!this.isEnabled() && !options?.force)
+            return;
+        const now = Date.now();
+        const expiresAtMs = now + this.ttlMs;
+        // Check size limit before insertion
+        const entrySize = content.length;
+        if (entrySize > this.maxBytes) {
+            logWarn('Cache entry exceeds max size', {
+                key: cacheKey,
+                size: entrySize,
+                max: this.maxBytes,
+            });
+            return;
+        }
+        let listChanged = !this.entries.has(cacheKey);
+        // Evict if needed (size-based)
+        while (this.currentBytes + entrySize > this.maxBytes) {
+            if (this.evictOldestEntry()) {
+                listChanged = true;
+            }
+            else {
+                break;
+            }
+        }
+        const entry = {
+            url: metadata.url,
+            content,
+            fetchedAt: new Date(now).toISOString(),
+            expiresAt: new Date(expiresAtMs).toISOString(),
+            expiresAtMs,
+            ...(metadata.title ? { title: metadata.title } : {}),
+        };
+        if (this.entries.has(cacheKey)) {
+            this.delete(cacheKey);
+        }
+        this.entries.set(cacheKey, entry);
+        this.currentBytes += entrySize;
+        // Eviction (LRU: first insertion-order key) - Count based
+        if (this.entries.size > this.max && this.evictOldestEntry()) {
+            listChanged = true;
+        }
+        this.notify(cacheKey, listChanged);
+    }
+    notify(cacheKey, listChanged) {
+        if (this.updateEmitter.listenerCount('update') === 0)
+            return;
+        const parts = parseCacheKey(cacheKey);
+        if (!parts)
+            return;
+        this.updateEmitter.emit('update', { cacheKey, ...parts, listChanged });
+    }
+    /**
+     * Read an entry without updating its LRU position.
+     * Use this for metadata access (e.g. resource listing) to avoid polluting the
+     * eviction order; expired entries are treated as absent but not evicted here.
+     */
+    peek(cacheKey) {
+        if (!cacheKey)
+            return undefined;
+        const entry = this.entries.get(cacheKey);
+        if (!entry)
+            return undefined;
+        if (this.isExpired(entry))
+            return undefined;
+        return entry;
+    }
+    logError(message, cacheKey, error) {
+        logWarn(message, {
+            key: cacheKey.length > 100 ? cacheKey.slice(0, 100) : cacheKey,
+            error: getErrorMessage(error),
+        });
+    }
+}
+const store = new InMemoryCacheStore();
+export function onCacheUpdate(listener) {
+    return store.onUpdate(listener);
+}
+export function get(cacheKey, options) {
+    return store.get(cacheKey, options);
+}
+export function set(cacheKey, content, metadata, options) {
+    store.set(cacheKey, content, metadata, options);
+}
+export function keys() {
+    return store.keys();
+}
+export function getEntryMeta(cacheKey) {
+    const entry = store.peek(cacheKey);
+    if (!entry)
+        return undefined;
+    return entry.title !== undefined
+        ? { url: entry.url, title: entry.title }
+        : { url: entry.url };
+}
+export function isEnabled() {
+    return store.isEnabled();
+}
+function hasPackageJsonVersion(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const record = value;
+    return typeof record.version === 'string';
+}
+function readServerVersion(moduleUrl) {
+    const packageJsonPath = findPackageJSON(moduleUrl);
+    if (!packageJsonPath)
+        throw new Error('package.json not found');
+    let packageJson;
+    try {
+        packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+    }
+    catch (error) {
+        throw new Error(`Failed to parse package.json at ${packageJsonPath}: ${getErrorMessage(error)}`, { cause: error });
+    }
+    if (!hasPackageJsonVersion(packageJson)) {
+        throw new Error(`package.json version is missing at ${packageJsonPath}`);
+    }
+    return packageJson.version;
+}
+const requestContext = new AsyncLocalStorage({
+    name: 'requestContext',
+});
+let mcpServer;
+const sessionServers = new Map();
+let stderrAvailable = true;
+process.stderr.on('error', () => {
+    stderrAvailable = false;
+});
+export function setMcpServer(server) {
+    mcpServer = server;
+}
+export function registerMcpSessionServer(sessionId, server) {
+    if (!sessionId)
+        return;
+    sessionServers.set(sessionId, server);
+}
+export function unregisterMcpSessionServer(sessionId) {
+    if (!sessionId)
+        return;
+    sessionServers.delete(sessionId);
+}
+export function unregisterMcpSessionServerByServer(server) {
+    for (const [sessionId, mappedServer] of sessionServers.entries()) {
+        if (mappedServer !== server)
+            continue;
+        sessionServers.delete(sessionId);
+    }
+}
+export function resolveMcpSessionIdByServer(server) {
+    for (const [sessionId, mappedServer] of sessionServers.entries()) {
+        if (mappedServer === server)
+            return sessionId;
+    }
+    return undefined;
+}
+export function runWithRequestContext(context, fn) {
+    return requestContext.run(context, fn);
+}
+function getRequestContext() {
+    return requestContext.getStore();
+}
+export function getRequestId() {
+    const context = getRequestContext();
+    return context?.requestId;
+}
+function getSessionId() {
+    return getRequestContext()?.sessionId;
+}
+export function getOperationId() {
+    return getRequestContext()?.operationId;
+}
+function isDebugEnabled() {
+    return config.logging.level === 'debug';
+}
+function buildContextMetadata() {
+    const ctx = requestContext.getStore();
+    if (!ctx)
+        return undefined;
+    const { requestId, operationId, sessionId } = ctx;
+    const includeSession = sessionId && isDebugEnabled();
+    if (!requestId && !operationId && !includeSession)
+        return undefined;
+    const meta = {};
+    if (requestId)
+        meta['requestId'] = requestId;
+    if (operationId)
+        meta['operationId'] = operationId;
+    if (includeSession)
+        meta['sessionId'] = sessionId;
+    return meta;
+}
+function mergeMetadata(meta) {
+    const contextMeta = buildContextMetadata();
+    const hasMeta = meta && Object.keys(meta).length > 0;
+    if (!contextMeta && !hasMeta)
+        return undefined;
+    if (!contextMeta)
+        return meta;
+    if (!hasMeta)
+        return contextMeta;
+    return { ...contextMeta, ...meta };
+}
+function formatMetadata(meta) {
+    const merged = mergeMetadata(meta);
+    if (!merged)
+        return '';
+    return ` ${inspect(merged, { breakLength: Infinity, colors: false, compact: true, sorted: true })}`;
+}
+function createTimestamp() {
+    return new Date().toISOString();
+}
+function formatLogEntry(level, message, meta) {
+    if (config.logging.format === 'json') {
+        const merged = mergeMetadata(meta);
+        const entry = {
+            timestamp: createTimestamp(),
+            level: level.toUpperCase(),
+            message,
+        };
+        if (merged) {
+            Object.assign(entry, merged);
+        }
+        return JSON.stringify(entry);
+    }
+    return `[${createTimestamp()}] ${level.toUpperCase()}: ${message}${formatMetadata(meta)}`;
+}
+const LEVEL_PRIORITY = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+function shouldLog(level) {
+    return LEVEL_PRIORITY[level] >= LEVEL_PRIORITY[config.logging.level];
+}
+function mapToMcpLevel(level) {
+    switch (level) {
+        case 'warn':
+            return 'warning';
+        case 'error':
+            return 'error';
+        case 'debug':
+            return 'debug';
+        case 'info':
+        default:
+            return 'info';
+    }
+}
+function resolveErrorText(err) {
+    if (err instanceof Error)
+        return err.message;
+    if (typeof err === 'string')
+        return err;
+    return 'unknown error';
+}
+function safeWriteStderr(line) {
+    if (!stderrAvailable)
+        return;
+    if (process.stderr.destroyed || process.stderr.writableEnded) {
+        stderrAvailable = false;
+        return;
+    }
+    try {
+        process.stderr.write(line);
+    }
+    catch {
+        // Logging must never take down the process (e.g. EPIPE).
+        stderrAvailable = false;
+    }
+}
+function writeLog(level, message, meta) {
+    if (!shouldLog(level))
+        return;
+    const line = formatLogEntry(level, message, meta);
+    safeWriteStderr(`${stripVTControlCharacters(line)}\n`);
+    const sessionId = getSessionId();
+    const server = sessionId
+        ? (sessionServers.get(sessionId) ?? mcpServer)
+        : mcpServer;
+    if (!server)
+        return;
+    if (!server.isConnected())
+        return;
+    try {
+        server.server
+            .sendLoggingMessage({
+            level: mapToMcpLevel(level),
+            logger: 'fetch-url-mcp',
+            // Preserve existing behavior: MCP payload includes only message + provided meta (not ALS context meta).
+            data: meta ? { message, ...meta } : message,
+        }, sessionId)
+            .catch((err) => {
+            if (!isDebugEnabled())
+                return;
+            const errorText = resolveErrorText(err);
+            safeWriteStderr(`[${createTimestamp()}] WARN: Failed to forward log to MCP${sessionId ? ` (sessionId=${sessionId})` : ''}: ${errorText}\n`);
+        });
+    }
+    catch (err) {
+        if (!isDebugEnabled())
+            return;
+        const errorText = resolveErrorText(err);
+        safeWriteStderr(`[${createTimestamp()}] WARN: Failed to forward log to MCP (sync error): ${errorText}\n`);
+    }
+}
+export function logInfo(message, meta) {
+    writeLog('info', message, meta);
+}
+export function logDebug(message, meta) {
+    writeLog('debug', message, meta);
+}
+export function logWarn(message, meta) {
+    writeLog('warn', message, meta);
+}
+export function logError(message, error) {
+    const errorMeta = error instanceof Error
+        ? { error: error.message, stack: error.stack }
+        : (error ?? {});
+    writeLog('error', message, errorMeta);
+}
+export function setLogLevel(level) {
+    const normalized = level.toLowerCase();
+    // Map MCP logging levels (RFC 5424 subset) to internal levels.
+    if (normalized === 'debug') {
+        config.logging.level = 'debug';
+    }
+    else if (normalized === 'info' || normalized === 'notice') {
+        config.logging.level = 'info';
+    }
+    else if (normalized === 'warning' || normalized === 'warn') {
+        config.logging.level = 'warn';
+    }
+    else if (normalized === 'error' ||
+        normalized === 'critical' ||
+        normalized === 'alert' ||
+        normalized === 'emergency') {
+        config.logging.level = 'error';
+    }
+}
+export function redactUrl(rawUrl) {
+    try {
+        const url = new URL(rawUrl);
+        url.username = '';
+        url.password = '';
+        url.hash = '';
+        url.search = '';
+        return url.toString();
+    }
+    catch {
+        return rawUrl;
+    }
+}
+export function composeCloseHandlers(first, second) {
+    if (!first)
+        return second;
+    if (!second)
+        return first;
+    return () => {
+        try {
+            first();
+        }
+        finally {
+            second();
+        }
+    };
+}
+const MIN_CLEANUP_INTERVAL_MS = 10_000;
+const MAX_CLEANUP_INTERVAL_MS = 60_000;
+const SESSION_CLOSE_BATCH_SIZE = 10;
+function getCleanupIntervalMs(sessionTtlMs) {
+    return Math.min(Math.max(Math.floor(sessionTtlMs / 2), MIN_CLEANUP_INTERVAL_MS), MAX_CLEANUP_INTERVAL_MS);
+}
+function handleSessionCleanupError(error) {
+    if (isAbortError(error))
+        return;
+    logWarn('Session cleanup loop failed', { error: getErrorMessage(error) });
+}
+function getRejectedSettledResult(result) {
+    return result.status === 'rejected' ? result : undefined;
+}
+function logRejectedSettledResults(results, message) {
+    for (const result of results) {
+        const rejected = getRejectedSettledResult(result);
+        if (!rejected)
+            continue;
+        logWarn(message, { error: getErrorMessage(rejected.reason) });
+    }
+}
+function isSessionExpired(session, now, sessionTtlMs) {
+    if (sessionTtlMs <= 0)
+        return false;
+    return now - session.lastSeen > sessionTtlMs;
+}
+function chunkArray(items, size) {
+    const chunks = [];
+    for (let index = 0; index < items.length; index += size) {
+        chunks.push(items.slice(index, index + size));
+    }
+    return chunks;
+}
+class SessionCleanupLoop {
+    store;
+    sessionTtlMs;
+    onEvictSession;
+    cleanupIntervalMsOverride;
+    constructor(store, sessionTtlMs, onEvictSession, cleanupIntervalMsOverride) {
+        this.store = store;
+        this.sessionTtlMs = sessionTtlMs;
+        this.onEvictSession = onEvictSession;
+        this.cleanupIntervalMsOverride = cleanupIntervalMsOverride;
+    }
+    start() {
+        const controller = new AbortController();
+        const intervalMs = this.cleanupIntervalMsOverride ?? getCleanupIntervalMs(this.sessionTtlMs);
+        startAbortableIntervalLoop(intervalMs, Date.now, {
+            signal: controller.signal,
+            onTick: async (getNow) => {
+                await this.handleTick(getNow(), controller.signal);
+            },
+            onError: handleSessionCleanupError,
+        });
+        return controller;
+    }
+    async handleTick(now, signal) {
+        const evicted = this.store.evictExpired();
+        for (const batch of chunkArray(evicted, SESSION_CLOSE_BATCH_SIZE)) {
+            const results = await Promise.allSettled(batch.map(async (session) => this.closeExpiredSession(session)));
+            logRejectedSettledResults(results, 'Failed to process expired session cleanup task');
+            if (signal.aborted)
+                return;
+        }
+        if (evicted.length > 0) {
+            logInfo('Expired sessions evicted', {
+                evicted: evicted.length,
+                timestamp: new Date(now).toISOString(),
+            });
+        }
+    }
+    async closeExpiredSession(session) {
+        if (this.onEvictSession) {
+            try {
+                await this.onEvictSession(session);
+            }
+            catch (error) {
+                logWarn('Expired session pre-close hook failed', {
+                    error: getErrorMessage(error),
+                });
+            }
+        }
+        try {
+            unregisterMcpSessionServerByServer(session.server);
+        }
+        catch (error) {
+            logWarn('Failed to unregister session server', {
+                error: getErrorMessage(error),
+            });
+        }
+        const [transportResult, serverResult] = await Promise.allSettled([
+            session.transport.close(),
+            session.server.close(),
+        ]);
+        const transportRejected = getRejectedSettledResult(transportResult);
+        const serverRejected = getRejectedSettledResult(serverResult);
+        this.logCloseFailure('transport', transportRejected?.reason);
+        this.logCloseFailure('server', serverRejected?.reason);
+    }
+    logCloseFailure(target, error) {
+        if (error == null)
+            return;
+        logWarn(`Failed to close expired session ${target}`, {
+            error: getErrorMessage(error),
+        });
+    }
+}
+export function startSessionCleanupLoop(store, sessionTtlMs, options) {
+    return new SessionCleanupLoop(store, sessionTtlMs, options?.onEvictSession, options?.cleanupIntervalMs).start();
+}
+function moveSessionToEnd(sessions, sessionId, session) {
+    sessions.delete(sessionId);
+    sessions.set(sessionId, session);
+}
+function removeSessionById(sessions, sessionId) {
+    const session = sessions.get(sessionId);
+    sessions.delete(sessionId);
+    return session;
+}
+function isBlankSessionId(sessionId) {
+    return sessionId.length === 0;
+}
+class InMemorySessionStore {
+    sessionTtlMs;
+    sessions = new Map();
+    inflight = 0;
+    constructor(sessionTtlMs) {
+        this.sessionTtlMs = sessionTtlMs;
+    }
+    get(sessionId) {
+        if (isBlankSessionId(sessionId))
+            return undefined;
+        return this.sessions.get(sessionId);
+    }
+    touch(sessionId) {
+        if (isBlankSessionId(sessionId))
+            return;
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return;
+        session.lastSeen = Date.now();
+        moveSessionToEnd(this.sessions, sessionId, session);
+    }
+    set(sessionId, entry) {
+        if (isBlankSessionId(sessionId))
+            return;
+        moveSessionToEnd(this.sessions, sessionId, entry);
+    }
+    remove(sessionId) {
+        if (isBlankSessionId(sessionId))
+            return undefined;
+        return removeSessionById(this.sessions, sessionId);
+    }
+    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 (!isSessionExpired(session, now, this.sessionTtlMs))
+                continue;
+            this.sessions.delete(id);
+            evicted.push(session);
+        }
+        return evicted;
+    }
+    evictOldest() {
+        const oldest = this.sessions.keys().next();
+        if (oldest.done)
+            return undefined;
+        return removeSessionById(this.sessions, oldest.value);
+    }
+}
+export function createSessionStore(sessionTtlMs) {
+    return new InMemorySessionStore(sessionTtlMs);
+}
+class SessionSlotTracker {
+    store;
+    slotReleased = false;
+    initialized = false;
+    constructor(store) {
+        this.store = store;
+    }
+    releaseSlot() {
+        if (this.slotReleased)
+            return;
+        this.slotReleased = true;
+        this.store.decrementInFlight();
+    }
+    markInitialized() {
+        this.initialized = true;
+    }
+    isInitialized() {
+        return this.initialized;
+    }
+}
+export function createSlotTracker(store) {
+    return new SessionSlotTracker(store);
+}
+function currentLoad(store) {
+    return store.size() + store.inFlight();
+}
+export function reserveSessionSlot(store, maxSessions) {
+    if (maxSessions <= 0)
+        return false;
+    if (currentLoad(store) >= maxSessions)
+        return false;
+    store.incrementInFlight();
+    return true;
+}
+function isAtCapacity(store, maxSessions) {
+    return currentLoad(store) >= maxSessions;
+}
+export function ensureSessionCapacity({ store, maxSessions, evictOldest, }) {
+    if (maxSessions <= 0)
+        return false;
+    const currentSize = store.size();
+    const inflight = store.inFlight();
+    if (currentSize + inflight < maxSessions)
+        return true;
+    const canFreeSlot = currentSize >= maxSessions && currentSize - 1 + inflight < maxSessions;
+    if (!canFreeSlot)
+        return false;
+    if (!evictOldest(store))
+        return false;
+    return !isAtCapacity(store, maxSessions);
+}