@j0hanz/fetch-url-mcp 1.3.1 → 1.5.0

package/dist/lib/utils.d.ts

@@ -0,0 +1,58 @@
+export declare function throwIfAborted(signal: AbortSignal | undefined, url: string, stage: string): void;
+export declare function createAbortError(url: string, stage: string): FetchError;
+export declare function timingSafeEqualUtf8(a: string, b: string): boolean;
+export declare function sha256Hex(input: string | Uint8Array): string;
+export declare function hmacSha256Hex(key: string | Uint8Array, input: string | Uint8Array): string;
+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 function getErrorMessage(error: unknown): string;
+export declare function toError(error: unknown): Error;
+export declare function isAbortError(error: unknown): boolean;
+export declare function createErrorWithCode(message: string, code: string, options?: ErrorOptions): NodeJS.ErrnoException;
+export declare function isSystemError(error: unknown): error is NodeJS.ErrnoException;
+export declare const RESOURCE_NOT_FOUND_ERROR_CODE = -32002;
+export declare function stableStringify(obj: unknown, depth?: number, seen?: WeakSet<WeakKey>): string;
+interface HttpServerTuningTarget {
+    headersTimeout?: number;
+    requestTimeout?: number;
+    keepAliveTimeout?: number;
+    keepAliveTimeoutBuffer?: number;
+    maxHeadersCount?: number | null;
+    maxConnections?: number;
+    on?: (event: string, listener: (...args: unknown[]) => void) => void;
+    closeIdleConnections?: () => void;
+    closeAllConnections?: () => void;
+}
+export declare function applyHttpServerTuning(server: HttpServerTuningTarget): void;
+export declare function drainConnectionsOnShutdown(server: HttpServerTuningTarget): void;
+export interface CancellableTimeout<T> {
+    promise: Promise<T>;
+    cancel: () => void;
+}
+interface IntervalLoopOptions<T> {
+    signal: AbortSignal;
+    onTick: (value: T) => void | Promise<void>;
+    onError?: (error: unknown) => void;
+}
+export declare function createUnrefTimeout<T>(timeoutMs: number, value: T): CancellableTimeout<T>;
+export declare function startAbortableIntervalLoop<T>(intervalMs: number, value: T, options: IntervalLoopOptions<T>): void;
+export declare function isObject(value: unknown): value is Record<PropertyKey, unknown>;
+export declare function isError(value: unknown): value is Error;
+interface LikeNode {
+    readonly tagName?: string | undefined;
+    readonly nodeName?: string | undefined;
+    readonly nodeType?: number | undefined;
+    readonly textContent?: string | null | undefined;
+    readonly innerHTML?: string | undefined;
+    readonly parentNode?: unknown;
+    readonly childNodes?: ArrayLike<unknown>;
+    readonly rawTagName?: string | undefined;
+    getAttribute?(name: string): string | null;
+}
+export declare function isLikeNode(value: unknown): value is LikeNode;
+export {};

package/dist/lib/utils.js

@@ -0,0 +1,304 @@
+import { Buffer } from 'node:buffer';
+import { createHash, createHmac, hash as oneShotHash, timingSafeEqual, } from 'node:crypto';
+import { setInterval as setIntervalPromise, setTimeout as setTimeoutPromise, } from 'node:timers/promises';
+import { inspect } from 'node:util';
+import { config, logDebug, logWarn } from './core.js';
+const UNKNOWN_ERROR_MESSAGE = 'Unknown error';
+function getAbortReason(signal) {
+    const record = isObject(signal) ? signal : null;
+    return record && 'reason' in record ? record['reason'] : undefined;
+}
+function isTimeoutAbortReason(reason) {
+    return reason instanceof Error && reason.name === 'TimeoutError';
+}
+export function throwIfAborted(signal, url, stage) {
+    if (!signal?.aborted)
+        return;
+    const reason = getAbortReason(signal);
+    if (isTimeoutAbortReason(reason)) {
+        throw new FetchError('Request timeout', url, 504, {
+            reason: 'timeout',
+            stage,
+        });
+    }
+    throw new FetchError('Request was canceled', url, 499, {
+        reason: 'aborted',
+        stage,
+    });
+}
+export function createAbortError(url, stage) {
+    return new FetchError('Request was canceled', url, 499, {
+        reason: 'aborted',
+        stage,
+    });
+}
+const MAX_HASH_INPUT_BYTES = 5 * 1024 * 1024;
+const ALLOWED_HASH_ALGORITHMS = new Set([
+    'sha256',
+    'sha512',
+]);
+function byteLengthUtf8(input) {
+    // Avoid allocating (unlike TextEncoder().encode()).
+    return Buffer.byteLength(input, 'utf8');
+}
+function byteLength(input) {
+    return typeof input === 'string' ? byteLengthUtf8(input) : input.byteLength;
+}
+function assertAllowedAlgorithm(algorithm) {
+    // Defensive: protects against `any` / unchecked external inputs.
+    if (!ALLOWED_HASH_ALGORITHMS.has(algorithm)) {
+        throw new Error(`Hash algorithm not allowed: ${algorithm}`);
+    }
+}
+function padBuffer(buffer, length) {
+    const padded = Buffer.alloc(length);
+    buffer.copy(padded);
+    return padded;
+}
+function equalWithPadding(aBuffer, bBuffer, paddedLength) {
+    const paddedA = padBuffer(aBuffer, paddedLength);
+    const paddedB = padBuffer(bBuffer, paddedLength);
+    return timingSafeEqual(paddedA, paddedB) && aBuffer.length === bBuffer.length;
+}
+export function timingSafeEqualUtf8(a, b) {
+    const aBuffer = Buffer.from(a, 'utf8');
+    const bBuffer = Buffer.from(b, 'utf8');
+    if (aBuffer.length === bBuffer.length) {
+        return timingSafeEqual(aBuffer, bBuffer);
+    }
+    // Avoid early return timing differences on length mismatch.
+    const maxLength = Math.max(aBuffer.length, bBuffer.length);
+    return equalWithPadding(aBuffer, bBuffer, maxLength);
+}
+function hashHex(algorithm, input) {
+    assertAllowedAlgorithm(algorithm);
+    if (byteLength(input) <= MAX_HASH_INPUT_BYTES) {
+        return oneShotHash(algorithm, input, 'hex');
+    }
+    const hasher = createHash(algorithm);
+    hasher.update(input);
+    return hasher.digest('hex');
+}
+export function sha256Hex(input) {
+    return hashHex('sha256', input);
+}
+export function hmacSha256Hex(key, input) {
+    return createHmac('sha256', key).update(input).digest('hex');
+}
+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.code = httpStatus ? `HTTP_${httpStatus}` : 'FETCH_ERROR';
+        this.details = Object.freeze({ url, httpStatus, ...details });
+        Error.captureStackTrace(this, this.constructor);
+    }
+}
+export function getErrorMessage(error) {
+    if (isError(error))
+        return error.message;
+    if (isNonEmptyString(error))
+        return error;
+    if (isErrorWithMessage(error))
+        return error.message;
+    return formatUnknownError(error);
+}
+export function toError(error) {
+    return isError(error) ? error : new Error(getErrorMessage(error));
+}
+export function isAbortError(error) {
+    return isError(error) && error.name === 'AbortError';
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function isErrorWithMessage(error) {
+    if (!isObject(error))
+        return false;
+    const { message } = error;
+    return typeof message === 'string' && message.length > 0;
+}
+function formatUnknownError(error) {
+    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 createErrorWithCode(message, code, options) {
+    const error = new Error(message, options);
+    return Object.assign(error, { code });
+}
+export function isSystemError(error) {
+    if (!isError(error))
+        return false;
+    if (!('code' in error))
+        return false;
+    const { code } = error;
+    return typeof code === 'string';
+}
+export const RESOURCE_NOT_FOUND_ERROR_CODE = -32002;
+const MAX_DEPTH = 20;
+const MAX_DEPTH_ERROR = `stableStringify: Max depth (${MAX_DEPTH}) exceeded`;
+const CIRCULAR_ERROR = 'stableStringify: Circular reference detected';
+function compareObjectKeys(a, b) {
+    if (a === b)
+        return 0;
+    return a < b ? -1 : 1;
+}
+function getSortedObjectKeys(obj) {
+    return Object.keys(obj).sort(compareObjectKeys);
+}
+function processValue(obj, depth, seen) {
+    if (typeof obj !== 'object' || obj === null) {
+        return obj;
+    }
+    // Depth guard
+    if (depth > MAX_DEPTH) {
+        throw new Error(MAX_DEPTH_ERROR);
+    }
+    // Cycle detection (track active recursion stack only).
+    if (seen.has(obj)) {
+        throw new Error(CIRCULAR_ERROR);
+    }
+    seen.add(obj);
+    try {
+        if (Array.isArray(obj)) {
+            return obj.map((item) => processValue(item, depth + 1, seen));
+        }
+        const keys = getSortedObjectKeys(obj);
+        const record = obj;
+        const sortedObj = {};
+        for (const key of keys) {
+            sortedObj[key] = processValue(record[key], depth + 1, seen);
+        }
+        return sortedObj;
+    }
+    finally {
+        seen.delete(obj);
+    }
+}
+export function stableStringify(obj, depth = 0, seen = new WeakSet()) {
+    const processed = processValue(obj, depth, seen);
+    return JSON.stringify(processed);
+}
+const DROP_LOG_INTERVAL_MS = 10_000;
+function setIfDefined(value, setter) {
+    if (value === undefined)
+        return;
+    setter(value);
+}
+function assignServerValue(server, key, value) {
+    setIfDefined(value, (resolved) => {
+        server[key] = resolved;
+    });
+}
+export function applyHttpServerTuning(server) {
+    const { headersTimeoutMs, requestTimeoutMs, keepAliveTimeoutMs, keepAliveTimeoutBufferMs, maxHeadersCount, maxConnections, } = config.server.http;
+    const tuningValues = [
+        ['headersTimeout', headersTimeoutMs],
+        ['requestTimeout', requestTimeoutMs],
+        ['keepAliveTimeout', keepAliveTimeoutMs],
+        ['keepAliveTimeoutBuffer', keepAliveTimeoutBufferMs],
+        ['maxHeadersCount', maxHeadersCount],
+    ];
+    for (const [key, value] of tuningValues) {
+        assignServerValue(server, key, value);
+    }
+    if (typeof maxConnections === 'number' && maxConnections > 0) {
+        server.maxConnections = maxConnections;
+        if (typeof server.on === 'function') {
+            let lastLoggedAt = 0;
+            let droppedSinceLastLog = 0;
+            const onDrop = (data) => {
+                droppedSinceLastLog += 1;
+                const now = Date.now();
+                if (now - lastLoggedAt < DROP_LOG_INTERVAL_MS)
+                    return;
+                logWarn('Incoming connection dropped (maxConnections reached)', {
+                    maxConnections,
+                    dropped: droppedSinceLastLog,
+                    data,
+                });
+                lastLoggedAt = now;
+                droppedSinceLastLog = 0;
+            };
+            server.on('drop', onDrop);
+        }
+    }
+}
+export function drainConnectionsOnShutdown(server) {
+    if (typeof server.closeIdleConnections === 'function') {
+        server.closeIdleConnections();
+        logDebug('Closed idle HTTP connections during shutdown');
+    }
+}
+function createAbortSafeTimeoutPromise(timeoutMs, value, signal) {
+    return setTimeoutPromise(timeoutMs, value, {
+        ref: false,
+        signal,
+    }).catch((err) => {
+        if (isAbortError(err)) {
+            return new Promise(() => { });
+        }
+        throw err;
+    });
+}
+export function createUnrefTimeout(timeoutMs, value) {
+    const controller = new AbortController();
+    const promise = createAbortSafeTimeoutPromise(timeoutMs, value, controller.signal);
+    return {
+        promise,
+        cancel: () => {
+            controller.abort();
+        },
+    };
+}
+export function startAbortableIntervalLoop(intervalMs, value, options) {
+    const ticks = setIntervalPromise(intervalMs, value, {
+        signal: options.signal,
+        ref: false,
+    });
+    void (async () => {
+        try {
+            for await (const tickValue of ticks) {
+                await options.onTick(tickValue);
+                if (options.signal.aborted)
+                    return;
+            }
+        }
+        catch (error) {
+            if (isAbortError(error))
+                return;
+            options.onError?.(error);
+        }
+    })();
+}
+export function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function isError(value) {
+    const { isError: isErrorFn } = Error;
+    return typeof isErrorFn === 'function'
+        ? isErrorFn(value)
+        : value instanceof Error;
+}
+export function isLikeNode(value) {
+    return isObject(value);
+}

package/dist/{prompts.d.ts → prompts/index.d.ts}

@@ -5,4 +5,3 @@ interface IconInfo {
 }
 export declare function registerGetHelpPrompt(server: McpServer, instructions: string, iconInfo?: IconInfo): void;
 export {};
-//# sourceMappingURL=prompts.d.ts.map

package/dist/{prompts.js → prompts/index.js}

@@ -20,7 +20,7 @@ export function registerGetHelpPrompt(server, instructions, iconInfo) {
         description,
         messages: [
             {
-                role: 'user',
+                role: 'assistant',
                 content: {
                     type: 'text',
                     text: instructions,
@@ -29,4 +29,3 @@ export function registerGetHelpPrompt(server, instructions, iconInfo) {
         ],
     }));
 }
-//# sourceMappingURL=prompts.js.map

package/dist/{resources.d.ts → resources/index.d.ts}

@@ -6,4 +6,3 @@ interface IconInfo {
 export declare function registerInstructionResource(server: McpServer, instructions: string, iconInfo?: IconInfo): void;
 export declare function registerCacheResourceTemplate(server: McpServer, iconInfo?: IconInfo): void;
 export {};
-//# sourceMappingURL=resources.d.ts.map

package/dist/{resources.js → resources/index.js}

@@ -1,16 +1,23 @@
 import { ResourceTemplate, } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { ErrorCode, McpError, SubscribeRequestSchema, UnsubscribeRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { get as getCacheEntry, getEntryMeta, keys as listCacheKeys, onCacheUpdate, parseCachedPayload, parseCacheKey, resolveCachedPayloadContent, } from './cache.js';
-import { logWarn } from './observability.js';
-import { isObject } from './type-guards.js';
+import { get as getCacheEntry, getEntryMeta, keys as listCacheKeys, onCacheUpdate, parseCachedPayload, parseCacheKey, resolveCachedPayloadContent, } from '../lib/core.js';
+import { logWarn } from '../lib/core.js';
+import { registerServerLifecycleCleanup } from '../lib/mcp-tools.js';
+import { RESOURCE_NOT_FOUND_ERROR_CODE } from '../lib/utils.js';
+import { isObject } from '../lib/utils.js';
 const CACHE_RESOURCE_TEMPLATE_URI = 'internal://cache/{namespace}/{hash}';
 const CACHE_RESOURCE_PREFIX = 'internal://cache/';
 const CACHE_NAMESPACE_PATTERN = /^[a-z0-9_-]{1,64}$/i;
 const CACHE_HASH_PATTERN = /^[a-f0-9.]{8,64}$/i;
-// -32002 is the MCP extension code for resource-not-found. The SDK ErrorCode enum
-// does not export this value, so it is defined locally.
-const RESOURCE_NOT_FOUND_ERROR_CODE = -32002;
 const MAX_COMPLETION_VALUES = 100;
+function normalizeCompletionPrefix(value) {
+    return value.trim().toLowerCase();
+}
+function sortAndLimitValues(values) {
+    return [...values]
+        .sort((left, right) => left.localeCompare(right))
+        .slice(0, MAX_COMPLETION_VALUES);
+}
 function buildOptionalIcons(iconInfo) {
     if (!iconInfo)
         return {};
@@ -51,17 +58,20 @@ function firstVariableValue(value) {
     }
     return undefined;
 }
-function parseCacheResourceFromVariables(variables) {
-    const namespace = firstVariableValue(variables['namespace']);
-    const hash = firstVariableValue(variables['hash']);
-    if (!namespace || !hash)
-        return null;
+function validateCacheResourceParts(namespace, hash) {
     const decoded = {
         namespace: decodeSegment(namespace),
         hash: decodeSegment(hash),
     };
     return isValidCacheResourceParts(decoded) ? decoded : null;
 }
+function parseCacheResourceFromVariables(variables) {
+    const namespace = firstVariableValue(variables['namespace']);
+    const hash = firstVariableValue(variables['hash']);
+    if (!namespace || !hash)
+        return null;
+    return validateCacheResourceParts(namespace, hash);
+}
 function parseCacheResourceFromUri(uri) {
     if (!uri.href.startsWith(CACHE_RESOURCE_PREFIX))
         return null;
@@ -75,50 +85,75 @@ function parseCacheResourceFromUri(uri) {
     const hash = segments[1];
     if (!namespace || !hash)
         return null;
-    const decoded = {
-        namespace: decodeSegment(namespace),
-        hash: decodeSegment(hash),
-    };
-    return isValidCacheResourceParts(decoded) ? decoded : null;
+    return validateCacheResourceParts(namespace, hash);
 }
 function toCacheResourceUri(parts) {
     const namespace = encodeURIComponent(parts.namespace);
     const hash = encodeURIComponent(parts.hash);
     return `${CACHE_RESOURCE_PREFIX}${namespace}/${hash}`;
 }
-function listCacheNamespaces() {
-    const namespaces = new Set();
-    for (const key of listCacheKeys()) {
-        const parsed = parseCacheKey(key);
-        if (!parsed)
-            continue;
-        namespaces.add(parsed.namespace);
+class CompletionIndex {
+    namespaces = null;
+    hashIndex = null;
+    invalidate() {
+        this.namespaces = null;
+        this.hashIndex = null;
+    }
+    getNamespaces() {
+        if (!this.namespaces) {
+            const seen = new Set();
+            for (const key of listCacheKeys()) {
+                const parsed = parseCacheKey(key);
+                if (parsed)
+                    seen.add(parsed.namespace);
+            }
+            this.namespaces = [...seen].sort((a, b) => a.localeCompare(b));
+        }
+        return this.namespaces;
+    }
+    getHashes(namespace) {
+        if (!this.hashIndex) {
+            const index = new Map();
+            for (const key of listCacheKeys()) {
+                const parsed = parseCacheKey(key);
+                if (!parsed)
+                    continue;
+                let set = index.get(parsed.namespace);
+                if (!set) {
+                    set = new Set();
+                    index.set(parsed.namespace, set);
+                }
+                set.add(parsed.urlHash);
+            }
+            this.hashIndex = new Map();
+            for (const [ns, set] of index) {
+                this.hashIndex.set(ns, [...set].sort((a, b) => a.localeCompare(b)));
+            }
+        }
+        if (namespace)
+            return this.hashIndex.get(namespace) ?? [];
+        const all = [];
+        for (const hashes of this.hashIndex.values()) {
+            all.push(...hashes);
+        }
+        return all.sort((a, b) => a.localeCompare(b));
     }
-    return [...namespaces].sort((left, right) => left.localeCompare(right));
 }
+const completionIndex = new CompletionIndex();
 function completeCacheNamespaces(value) {
-    const normalized = value.trim().toLowerCase();
-    return listCacheNamespaces()
-        .filter((namespace) => namespace.toLowerCase().startsWith(normalized))
-        .slice(0, MAX_COMPLETION_VALUES);
+    const normalized = normalizeCompletionPrefix(value);
+    const namespaces = completionIndex
+        .getNamespaces()
+        .filter((ns) => ns.toLowerCase().startsWith(normalized));
+    return sortAndLimitValues(namespaces);
 }
 function completeCacheHashes(value, context) {
-    const normalized = value.trim().toLowerCase();
+    const normalized = normalizeCompletionPrefix(value);
     const namespace = context?.arguments?.['namespace']?.trim();
-    const hashes = new Set();
-    for (const key of listCacheKeys()) {
-        const parsed = parseCacheKey(key);
-        if (!parsed)
-            continue;
-        if (namespace && parsed.namespace !== namespace)
-            continue;
-        if (!parsed.urlHash.toLowerCase().startsWith(normalized))
-            continue;
-        hashes.add(parsed.urlHash);
-    }
-    return [...hashes]
-        .sort((left, right) => left.localeCompare(right))
-        .slice(0, MAX_COMPLETION_VALUES);
+    const hashes = completionIndex
+        .getHashes(namespace)
+        .filter((h) => h.toLowerCase().startsWith(normalized));
+    return sortAndLimitValues(hashes);
 }
 function listCacheResources() {
     const resources = listCacheKeys()
@@ -158,7 +193,14 @@ function normalizeSubscriptionUri(uri) {
         return toCacheResourceUri(cacheParts);
     return parsedUri.href;
 }
+// Must only be called once per server instance; duplicate calls would register
+// redundant Subscribe/Unsubscribe handlers and create a second onCacheUpdate
+// listener, causing duplicate notifications.
+let cacheNotificationsRegistered = false;
 function registerCacheResourceNotifications(server) {
+    if (cacheNotificationsRegistered)
+        return;
+    cacheNotificationsRegistered = true;
     const subscribedResourceUris = new Set();
     const setSubscription = (uri, subscribed) => {
         const normalized = normalizeSubscriptionUri(uri);
@@ -178,6 +220,7 @@ function registerCacheResourceNotifications(server) {
         return Promise.resolve({});
     });
     const unsubscribe = onCacheUpdate((event) => {
+        completionIndex.invalidate();
         const changedUri = toCacheResourceUri({
             namespace: event.namespace,
             hash: event.urlHash,
@@ -210,26 +253,7 @@ function registerCacheResourceNotifications(server) {
         cleanedUp = true;
         unsubscribe();
     };
-    // Both patches are intentional and handle distinct disconnection scenarios:
-    // • `server.server.onclose` fires when the transport closes unexpectedly
-    //   (e.g., client drops the connection) — the SDK calls it directly from
-    //   `_onclose()` without going through `server.close()`.
-    // • `server.close()` fires when the application shuts the server down
-    //   gracefully. The `server.close()` path also eventually triggers `onclose`,
-    //   so the `cleanedUp` guard below prevents double-invocation.
-    const originalOnClose = server.server.onclose;
-    server.server.onclose = () => {
-        cleanup();
-        originalOnClose?.();
-    };
-    // FIXME: Monkey-patching server.close is fragile if other modules wrap it.
-    // A proper fix requires a first-class lifecycle hook or cleanup registration API
-    // in the SDK. Until then, the cleanedUp guard prevents double-invocation.
-    const originalClose = server.close.bind(server);
-    server.close = async () => {
-        cleanup();
-        await originalClose();
-    };
+    registerServerLifecycleCleanup(server, cleanup);
 }
 function normalizeTemplateVariables(variables) {
     if (!isObject(variables))
@@ -317,4 +341,3 @@ export function registerCacheResourceTemplate(server, iconInfo) {
     }, (uri, variables) => readCacheResource(uri, normalizeTemplateVariables(variables)));
     registerCacheResourceNotifications(server);
 }
-//# sourceMappingURL=resources.js.map

package/dist/{instructions.d.ts → resources/instructions.d.ts}

@@ -1,2 +1 @@
 export declare function buildServerInstructions(): string;
-//# sourceMappingURL=instructions.d.ts.map

package/dist/{instructions.js → resources/instructions.js}

@@ -1,5 +1,5 @@
-import { config } from './config.js';
-import { FETCH_URL_TOOL_NAME } from './tools.js';
+import { config } from '../lib/core.js';
+import { FETCH_URL_TOOL_NAME } from '../tools/fetch-url.js';
 export function buildServerInstructions() {
     const maxHtmlSizeMb = config.constants.maxHtmlSize / 1024 / 1024;
     const cacheSizeMb = config.cache.maxSizeBytes / 1024 / 1024;
@@ -24,10 +24,13 @@ export function buildServerInstructions() {
 - Blocked: localhost, private IPs (10.x, 172.16-31.x, 192.168.x), metadata endpoints (169.254.169.254), .local/.internal.
 - Limits: Max HTML ${maxHtmlSizeMb}MB. Max ${config.fetcher.maxRedirects} redirects.
 - Cache: ${config.cache.maxKeys} entries, ${cacheSizeMb}MB, ${cacheTtlHours}h TTL.
+- Cache scope: process-local and ephemeral. Cache URIs are invalid across server restarts or separate CLI invocations (-32002).
 - No JS: Client-side rendered pages may be incomplete.
 - Binary: Not supported.
 - Batch JSON-RPC: Array requests (\`[{...}]\`) are rejected with HTTP 400.
 - Tasks API: Experimental (SDK v1.26). \`tasks/get\`, \`tasks/result\`, \`tasks/list\`, \`tasks/cancel\` may change.
+- Notifications: Optional non-spec extension. Set \`TASKS_STATUS_NOTIFICATIONS=true\` to emit \`notifications/tasks/status\`.
+- URI scheme: \`internal://\` is a server-scoped custom scheme for cache resources. Not IANA-registered; valid only within this server's session lifetime.
 </constraints>
 
 <error_handling>
@@ -38,4 +41,3 @@ export function buildServerInstructions() {
 - queue_full: Worker pool busy. Wait and retry, or use task mode.
 </error_handling>`;
 }
-//# sourceMappingURL=instructions.js.map

package/dist/schemas/inputs.d.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+export declare const fetchUrlInputSchema: z.ZodObject<{
+    url: z.ZodURL;
+    skipNoiseRemoval: z.ZodOptional<z.ZodBoolean>;
+    forceRefresh: z.ZodOptional<z.ZodBoolean>;
+    maxInlineChars: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;

package/dist/schemas/inputs.js

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import { config } from '../lib/core.js';
+export const fetchUrlInputSchema = z.strictObject({
+    url: z
+        .httpUrl()
+        .min(1)
+        .max(config.constants.maxUrlLength)
+        .describe(`Target URL. Max ${config.constants.maxUrlLength} chars.`),
+    skipNoiseRemoval: z
+        .boolean()
+        .optional()
+        .describe('Preserve navigation/footers (disable noise filtering).'),
+    forceRefresh: z
+        .boolean()
+        .optional()
+        .describe('Bypass cache and fetch fresh content.'),
+    maxInlineChars: z
+        .number()
+        .int()
+        .min(0)
+        .max(config.constants.maxHtmlSize)
+        .optional()
+        .describe(`Inline markdown limit (0-${config.constants.maxHtmlSize}, 0=unlimited). Lower of this or global limit applies.`),
+});