@j0hanz/fetch-url-mcp 1.0.1 → 1.1.0

package/dist/AGENTS.md

@@ -81,6 +81,7 @@ All commands verified from `.github/workflows/release.yml` (CI) and `package.jso
 
 - `strict: true`
 - `noUncheckedIndexedAccess: true`
+- `noPropertyAccessFromIndexSignature: true`
 - `exactOptionalPropertyTypes: true`
 - `verbatimModuleSyntax: true`
 - `isolatedModules: true`

package/dist/cache.d.ts

@@ -31,6 +31,7 @@ interface CacheUpdateEvent {
     cacheKey: string;
     namespace: string;
     urlHash: string;
+    listChanged: boolean;
 }
 type CacheUpdateListener = (event: CacheUpdateEvent) => unknown;
 export declare function parseCachedPayload(raw: string): CachedPayload | null;

package/dist/cache.js

@@ -132,6 +132,7 @@ class InMemoryCacheStore {
         const now = Date.now();
         if (entry.expiresAtMs <= now) {
             this.delete(cacheKey);
+            this.notify(cacheKey, true);
             return undefined;
         }
         // Refresh LRU position
@@ -144,7 +145,9 @@ class InMemoryCacheStore {
         if (entry) {
             this.currentBytes -= entry.content.length;
             this.entries.delete(cacheKey);
+            return true;
         }
+        return false;
     }
     set(cacheKey, content, metadata, options) {
         if (!cacheKey || !content)
@@ -163,12 +166,15 @@ class InMemoryCacheStore {
             });
             return;
         }
+        let listChanged = !this.entries.has(cacheKey);
         // Evict if needed (size-based)
         while (this.currentBytes + entrySize > this.maxBytes) {
             const firstKey = this.entries.keys().next();
             if (firstKey.done)
                 break;
-            this.delete(firstKey.value);
+            if (this.delete(firstKey.value)) {
+                listChanged = true;
+            }
         }
         const entry = {
             url: metadata.url,
@@ -186,18 +192,19 @@ class InMemoryCacheStore {
         // Eviction (LRU: first insertion-order key) - Count based
         if (this.entries.size > this.max) {
             const firstKey = this.entries.keys().next();
-            if (!firstKey.done)
-                this.delete(firstKey.value);
+            if (!firstKey.done && this.delete(firstKey.value)) {
+                listChanged = true;
+            }
         }
-        this.notify(cacheKey);
+        this.notify(cacheKey, listChanged);
     }
-    notify(cacheKey) {
+    notify(cacheKey, listChanged) {
         if (this.updateEmitter.listenerCount('update') === 0)
             return;
         const parts = parseCacheKey(cacheKey);
         if (!parts)
             return;
-        this.updateEmitter.emit('update', { cacheKey, ...parts });
+        this.updateEmitter.emit('update', { cacheKey, ...parts, listChanged });
     }
     logError(message, cacheKey, error) {
         logWarn(message, {

package/dist/config.js

@@ -216,27 +216,27 @@ function readOptionalFilePath(value) {
     return trimmed.length > 0 ? trimmed : undefined;
 }
 const MAX_HTML_BYTES = 10 * 1024 * 1024; // 10 MB
-const MAX_INLINE_CONTENT_CHARS = parseInteger(env.MAX_INLINE_CONTENT_CHARS, 0, 0, MAX_HTML_BYTES);
+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_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 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 maxOldGenerationSizeMb = parseOptionalInteger(env.TRANSFORM_WORKER_MAX_OLD_GENERATION_MB, 1);
-    const maxYoungGenerationSizeMb = parseOptionalInteger(env.TRANSFORM_WORKER_MAX_YOUNG_GENERATION_MB, 1);
-    const codeRangeSizeMb = parseOptionalInteger(env.TRANSFORM_WORKER_CODE_RANGE_MB, 1);
-    const stackSizeMb = parseOptionalInteger(env.TRANSFORM_WORKER_STACK_MB, 1);
+    const maxOldGenerationSizeMb = parseOptionalInteger(env['TRANSFORM_WORKER_MAX_OLD_GENERATION_MB'], 1);
+    const maxYoungGenerationSizeMb = parseOptionalInteger(env['TRANSFORM_WORKER_MAX_YOUNG_GENERATION_MB'], 1);
+    const codeRangeSizeMb = parseOptionalInteger(env['TRANSFORM_WORKER_CODE_RANGE_MB'], 1);
+    const stackSizeMb = parseOptionalInteger(env['TRANSFORM_WORKER_STACK_MB'], 1);
     if (maxOldGenerationSizeMb !== undefined) {
         limits.maxOldGenerationSizeMb = maxOldGenerationSizeMb;
         hasAny = true;
@@ -283,9 +283,9 @@ function resolveAuthMode(urls) {
     return oauthConfigured ? 'oauth' : 'static';
 }
 function collectStaticTokens() {
-    const staticTokens = new Set(parseList(env.ACCESS_TOKENS));
-    if (env.API_KEY)
-        staticTokens.add(env.API_KEY);
+    const staticTokens = new Set(parseList(env['ACCESS_TOKENS']));
+    if (env['API_KEY'])
+        staticTokens.add(env['API_KEY']);
     return [...staticTokens];
 }
 function buildAuthConfig(baseUrl) {
@@ -294,17 +294,17 @@ function buildAuthConfig(baseUrl) {
     return {
         mode,
         ...urls,
-        requiredScopes: parseList(env.OAUTH_REQUIRED_SCOPES),
-        clientId: env.OAUTH_CLIENT_ID,
-        clientSecret: env.OAUTH_CLIENT_SECRET,
+        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);
+    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 && !certFile) || (!keyFile && certFile)) {
         throw new ConfigError('Both SERVER_TLS_KEY_FILE and SERVER_TLS_CERT_FILE must be set together');
     }
@@ -349,17 +349,17 @@ const BLOCKED_IP_PATTERNS = [
 ];
 const BLOCKED_IP_PATTERN = /^(?:10\.|172\.(?:1[6-9]|2\d|3[01])\.|192\.168\.|127\.|0\.|169\.254\.|100\.64\.|fc00:|fd00:|fe80:)/i;
 const BLOCKED_IPV4_MAPPED_PATTERN = /^::ffff:(?:127\.|10\.|172\.(?:1[6-9]|2\d|3[01])\.|192\.168\.|169\.254\.)/i;
-const host = (env.HOST ?? LOOPBACK_V4).trim();
-const port = parsePort(env.PORT);
+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 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 baseUrl = new URL(`${httpsConfig.enabled ? 'https' : 'http'}://${formatHostForUrl(host)}:${port}`);
 const runtimeState = {
     httpMode: false,
@@ -389,7 +389,7 @@ export const config = {
     fetcher: {
         timeout: DEFAULT_FETCH_TIMEOUT_MS,
         maxRedirects: 5,
-        userAgent: env.USER_AGENT ?? DEFAULT_USER_AGENT,
+        userAgent: env['USER_AGENT'] ?? DEFAULT_USER_AGENT,
         maxContentLength: MAX_HTML_BYTES,
     },
     transform: {
@@ -397,7 +397,7 @@ export const config = {
         stageWarnRatio: 0.5,
         metadataFormat: 'markdown',
         maxWorkerScale: 4,
-        workerMode: parseTransformWorkerMode(env.TRANSFORM_WORKER_MODE),
+        workerMode: parseTransformWorkerMode(env['TRANSFORM_WORKER_MODE']),
         workerResourceLimits: resolveWorkerResourceLimits(),
     },
     tools: {
@@ -409,7 +409,7 @@ export const config = {
         maxPerOwner: RESOLVED_TASKS_MAX_PER_OWNER,
     },
     cache: {
-        enabled: parseBoolean(env.CACHE_ENABLED, true),
+        enabled: parseBoolean(env['CACHE_ENABLED'], true),
         ttl: 86400,
         maxKeys: 100,
         maxSizeBytes: 50 * 1024 * 1024, // 50MB
@@ -419,8 +419,8 @@ export const config = {
         minParagraphLength: 10,
     },
     noiseRemoval: {
-        extraTokens: parseList(env.FETCH_URL_MCP_EXTRA_NOISE_TOKENS),
-        extraSelectors: parseList(env.FETCH_URL_MCP_EXTRA_NOISE_SELECTORS),
+        extraTokens: parseList(env['FETCH_URL_MCP_EXTRA_NOISE_TOKENS']),
+        extraSelectors: parseList(env['FETCH_URL_MCP_EXTRA_NOISE_SELECTORS']),
         enabledCategories: [
             'cookie-banners',
             'newsletters',
@@ -443,14 +443,14 @@ export const config = {
         removeSkipLinks: true,
         removeTocBlocks: true,
         removeTypeDocComments: true,
-        headingKeywords: parseListOrDefault(env.MARKDOWN_HEADING_KEYWORDS, DEFAULT_HEADING_KEYWORDS),
+        headingKeywords: parseListOrDefault(env['MARKDOWN_HEADING_KEYWORDS'], DEFAULT_HEADING_KEYWORDS),
     },
     i18n: {
-        locale: normalizeLocale(env.FETCH_URL_MCP_LOCALE),
+        locale: normalizeLocale(env['FETCH_URL_MCP_LOCALE']),
     },
     logging: {
-        level: parseLogLevel(env.LOG_LEVEL),
-        format: env.LOG_FORMAT?.toLowerCase() === 'json' ? 'json' : 'text',
+        level: parseLogLevel(env['LOG_LEVEL']),
+        format: env['LOG_FORMAT']?.toLowerCase() === 'json' ? 'json' : 'text',
     },
     constants: {
         maxHtmlSize: MAX_HTML_BYTES,
@@ -462,8 +462,8 @@ export const config = {
         blockedIpPatterns: BLOCKED_IP_PATTERNS,
         blockedIpPattern: BLOCKED_IP_PATTERN,
         blockedIpv4MappedPattern: BLOCKED_IPV4_MAPPED_PATTERN,
-        allowedHosts: parseAllowedHosts(env.ALLOWED_HOSTS),
-        apiKey: env.API_KEY,
+        allowedHosts: parseAllowedHosts(env['ALLOWED_HOSTS']),
+        apiKey: env['API_KEY'],
         allowRemote,
     },
     auth: buildAuthConfig(baseUrl),

package/dist/fetch.js

@@ -26,6 +26,23 @@ const defaultRedactor = {
     redact: redactUrl,
 };
 const defaultFetch = (input, init) => globalThis.fetch(input, init);
+function assertReadableStreamLike(stream, url, stage) {
+    if (isObject(stream) && typeof stream['getReader'] === 'function')
+        return;
+    throw new FetchError('Invalid response stream', url, 500, {
+        reason: 'invalid_stream',
+        stage,
+    });
+}
+function toNodeReadableStream(stream, url, stage) {
+    assertReadableStreamLike(stream, url, stage);
+    return stream;
+}
+function toWebReadableStream(stream, url, stage) {
+    const converted = Readable.toWeb(stream);
+    assertReadableStreamLike(converted, url, stage);
+    return converted;
+}
 class IpBlocker {
     security;
     blockList = createDefaultBlockList();
@@ -653,9 +670,9 @@ class FetchTelemetry {
             url: ctx.url,
         };
         if (ctx.contextRequestId)
-            logData.contextRequestId = ctx.contextRequestId;
+            logData['contextRequestId'] = ctx.contextRequestId;
         if (ctx.operationId)
-            logData.operationId = ctx.operationId;
+            logData['operationId'] = ctx.operationId;
         this.logger.debug('HTTP Request', logData);
         return ctx;
     }
@@ -685,13 +702,13 @@ class FetchTelemetry {
             duration: durationLabel,
         };
         if (context.contextRequestId)
-            logData.contextRequestId = context.contextRequestId;
+            logData['contextRequestId'] = context.contextRequestId;
         if (context.operationId)
-            logData.operationId = context.operationId;
+            logData['operationId'] = context.operationId;
         if (contentType)
-            logData.contentType = contentType;
+            logData['contentType'] = contentType;
         if (size)
-            logData.size = size;
+            logData['size'] = size;
         this.logger.debug('HTTP Response', logData);
         if (duration > SLOW_REQUEST_THRESHOLD_MS) {
             const warnData = {
@@ -700,9 +717,9 @@ class FetchTelemetry {
                 duration: durationLabel,
             };
             if (context.contextRequestId)
-                warnData.contextRequestId = context.contextRequestId;
+                warnData['contextRequestId'] = context.contextRequestId;
             if (context.operationId)
-                warnData.operationId = context.operationId;
+                warnData['operationId'] = context.operationId;
             this.logger.warn('Slow HTTP request detected', warnData);
         }
     }
@@ -735,9 +752,9 @@ class FetchTelemetry {
             error: err.message,
         };
         if (context.contextRequestId)
-            logData.contextRequestId = context.contextRequestId;
+            logData['contextRequestId'] = context.contextRequestId;
         if (context.operationId)
-            logData.operationId = context.operationId;
+            logData['operationId'] = context.operationId;
         if (status === 429) {
             this.logger.warn('HTTP Request Error', logData);
             return;
@@ -839,7 +856,7 @@ class RedirectFollower {
     annotateRedirectError(error, url) {
         if (!isObject(error))
             return;
-        error.requestUrl = url;
+        error['requestUrl'] = url;
     }
     async withRedirectErrorContext(url, fn) {
         try {
@@ -1072,7 +1089,7 @@ class ResponseTextReader {
         let encodingResolved = false;
         let total = 0;
         const chunks = [];
-        const source = Readable.fromWeb(stream);
+        const source = Readable.fromWeb(toNodeReadableStream(stream, url, 'response:read-stream-buffer'));
         const guard = new Transform({
             transform(chunk, _encoding, callback) {
                 try {
@@ -1377,7 +1394,7 @@ async function decodeResponseIfNeeded(response, url, signal) {
         });
     }
     const decompressors = decodeOrder.map((encoding) => createDecompressor(encoding));
-    const sourceStream = Readable.fromWeb(createPumpedStream(initialChunk, reader));
+    const sourceStream = Readable.fromWeb(toNodeReadableStream(createPumpedStream(initialChunk, reader), url, 'response:decode-content-encoding'));
     const decodedNodeStream = new PassThrough();
     const pipelinePromise = pipeline([
         sourceStream,
@@ -1397,7 +1414,7 @@ async function decodeResponseIfNeeded(response, url, signal) {
     void pipelinePromise.catch((error) => {
         decodedNodeStream.destroy(error instanceof Error ? error : new Error(String(error)));
     });
-    const decodedBody = Readable.toWeb(decodedNodeStream);
+    const decodedBody = toWebReadableStream(decodedNodeStream, url, 'response:decode-content-encoding');
     const headers = new Headers(response.headers);
     headers.delete('content-encoding');
     headers.delete('content-length');

package/dist/http-native.js

@@ -617,7 +617,7 @@ class AuthService {
             'content-type': 'application/x-www-form-urlencoded',
         };
         if (clientId) {
-            headers.authorization = this.buildBasicAuthHeader(clientId, clientSecret);
+            headers['authorization'] = this.buildBasicAuthHeader(clientId, clientSecret);
         }
         return { body, headers };
     }
@@ -641,12 +641,13 @@ class AuthService {
         return response.json();
     }
     buildIntrospectionAuthInfo(token, payload) {
-        const expiresAt = typeof payload.exp === 'number' ? payload.exp : undefined;
-        const clientId = typeof payload.client_id === 'string' ? payload.client_id : 'unknown';
+        const { exp, client_id: clientIdRaw, scope: scopeRaw } = payload;
+        const expiresAt = typeof exp === 'number' ? exp : undefined;
+        const clientId = typeof clientIdRaw === 'string' ? clientIdRaw : 'unknown';
         const info = {
             token,
             clientId,
-            scopes: typeof payload.scope === 'string' ? payload.scope.split(' ') : [],
+            scopes: typeof scopeRaw === 'string' ? scopeRaw.split(' ') : [],
             resource: config.auth.resourceUrl,
         };
         if (expiresAt !== undefined)
@@ -659,7 +660,7 @@ class AuthService {
         }
         const req = this.buildIntrospectionRequest(token, config.auth.resourceUrl, config.auth.clientId, config.auth.clientSecret);
         const payload = await this.requestIntrospection(config.auth.introspectionUrl, req, config.auth.introspectionTimeoutMs, signal);
-        if (!isObject(payload) || payload.active !== true) {
+        if (!isObject(payload) || payload['active'] !== true) {
             throw new InvalidTokenError('Token is inactive');
         }
         return this.buildIntrospectionAuthInfo(token, payload);
@@ -1245,6 +1246,7 @@ function resolveListeningPort(server, fallback) {
     return fallback;
 }
 function createShutdownHandler(options) {
+    const closeBatchSize = 10;
     return async (signal) => {
         logInfo(`Stopping HTTP server (${signal})...`);
         options.rateLimiter.stop();
@@ -1252,16 +1254,19 @@ function createShutdownHandler(options) {
         drainConnectionsOnShutdown(options.server);
         eventLoopDelay.disable();
         const sessions = options.sessionStore.clear();
-        await Promise.all(sessions.map(async (session) => {
-            const sessionId = resolveMcpSessionIdByServer(session.server);
-            if (sessionId) {
-                cancelTasksForOwner(`session:${sessionId}`, 'The task was cancelled because the HTTP server is shutting down.');
-                unregisterMcpSessionServer(sessionId);
-            }
-            unregisterMcpSessionServerByServer(session.server);
-            await closeTransportBestEffort(session.transport, 'shutdown-session-close');
-            await closeMcpServerBestEffort(session.server, 'shutdown-session-close');
-        }));
+        for (let i = 0; i < sessions.length; i += closeBatchSize) {
+            const batch = sessions.slice(i, i + closeBatchSize);
+            await Promise.all(batch.map(async (session) => {
+                const sessionId = resolveMcpSessionIdByServer(session.server);
+                if (sessionId) {
+                    cancelTasksForOwner(`session:${sessionId}`, 'The task was cancelled because the HTTP server is shutting down.');
+                    unregisterMcpSessionServer(sessionId);
+                }
+                unregisterMcpSessionServerByServer(session.server);
+                await closeTransportBestEffort(session.transport, 'shutdown-session-close');
+                await closeMcpServerBestEffort(session.server, 'shutdown-session-close');
+            }));
+        }
         await new Promise((resolve, reject) => {
             options.server.close((err) => {
                 if (err)

package/dist/instructions.md

@@ -22,7 +22,9 @@ Available as resource (`internal://instructions`) or prompt (`get-help`). Load w
 
 - `internal://instructions`: This document.
 - `internal://cache/{namespace}/{hash}`: Immutable cached Markdown snapshots from previous `fetch-url` calls. Ephemeral — lost when the server process restarts.
+- `fetch-url` responses include a `resource_link` content block when cache is enabled; use that URI directly with `resources/read`/`resources/subscribe`.
 - If inline Markdown is truncated (ends with `...[truncated]`), the full content may be available via the cache resource. Use `resources/read` with the cache URI to retrieve it.
+- Clients can subscribe to cache resource URIs via `resources/subscribe` and receive `notifications/resources/updated` when that specific cache entry changes.
 
 ---
 
@@ -44,7 +46,7 @@ Available as resource (`internal://instructions`) or prompt (`get-help`). Load w
 
 1. Call `fetch-url` with `{ "url": "https://..." }`.
 2. Read the `markdown` field from `structuredContent`.
-3. If `truncated` is `true`: use the cache resource URI or paginated access to get full content.
+3. If `truncated` is `true`: use `cacheResourceUri` from `structuredContent` with `resources/read` to get full content.
    NOTE: Never guess URIs; always use values returned in responses.
 
 ### WORKFLOW B: FRESH CONTENT (BYPASS CACHE)
@@ -77,13 +79,14 @@ Available as resource (`internal://instructions`) or prompt (`get-help`). Load w
   - `skipNoiseRemoval` (bool): Keeps navigation, footers, and other elements normally filtered.
   - `forceRefresh` (bool): Bypasses the cache and fetches live.
   - `maxInlineChars` (int, 0–10485760): Per-call inline limit. `0` means unlimited. If a global limit is configured, the lower value wins.
-- Output: `{ url, inputUrl, resolvedUrl, finalUrl, title, metadata, markdown, fromCache, fetchedAt, contentSize, truncated, error, statusCode, details }`
+- Output: `{ url, inputUrl, resolvedUrl, finalUrl, cacheResourceUri, title, metadata, markdown, fromCache, fetchedAt, contentSize, truncated, error, statusCode, details }`
   - `metadata`: Extracted page metadata — `title`, `description`, `author`, `image`, `favicon`, `publishedAt`, `modifiedAt`.
   - `markdown`: The extracted content. May be absent on error.
   - `truncated`: `true` when inline content was cut. Full content stored in cache.
   - `resolvedUrl`: The normalized/raw-transformed URL actually fetched (GitHub/GitLab/Bitbucket URLs auto-convert to raw content URLs).
   - `finalUrl`: The URL after following redirects.
 - Side effects: None (read-only, idempotent). Populates the in-memory cache automatically.
+- `cacheResourceUri`: Present when cache key generation succeeds; use with `resources/read` for full content retrieval.
 - Gotcha: Inline Markdown may be truncated when `MAX_INLINE_CONTENT_CHARS` is configured. Check the `truncated` field and use the cache resource for full content.
 - Gotcha: GitHub, GitLab, and Bitbucket URLs are auto-transformed to raw content endpoints. Check `resolvedUrl` to see the actual fetched URL.
 - Gotcha: Does not execute client-side JavaScript. Content requiring JS rendering may be incomplete.

package/dist/mcp.js

@@ -71,6 +71,48 @@ function parseExtendedCallToolRequest(request) {
 function isRecord(value) {
     return isObject(value);
 }
+function parseHandlerExtra(extra) {
+    if (!isObject(extra))
+        return undefined;
+    const parsed = {};
+    const { sessionId, authInfo, signal, requestId, sendNotification } = extra;
+    if (typeof sessionId === 'string')
+        parsed.sessionId = sessionId;
+    if (isObject(authInfo)) {
+        const { clientId, token } = authInfo;
+        const normalized = {};
+        if (typeof clientId === 'string')
+            normalized.clientId = clientId;
+        if (typeof token === 'string')
+            normalized.token = token;
+        if (normalized.clientId || normalized.token)
+            parsed.authInfo = normalized;
+    }
+    if (signal instanceof AbortSignal)
+        parsed.signal = signal;
+    if (typeof requestId === 'string' || typeof requestId === 'number') {
+        parsed.requestId = requestId;
+    }
+    if (typeof sendNotification === 'function') {
+        const notify = sendNotification;
+        parsed.sendNotification = async (notification) => {
+            await Promise.resolve(notify(notification));
+        };
+    }
+    return parsed;
+}
+function isServerResult(value) {
+    return (isObject(value) && Array.isArray(value.content));
+}
+function tryReadToolStructuredError(value) {
+    if (!isObject(value))
+        return undefined;
+    const record = value;
+    if (!isObject(record.structuredContent))
+        return undefined;
+    const structured = record.structuredContent;
+    return typeof structured.error === 'string' ? structured.error : undefined;
+}
 function resolveTaskOwnerKey(extra) {
     if (extra?.sessionId)
         return `session:${extra.sessionId}`;
@@ -221,13 +263,12 @@ async function runFetchTaskExecution(params) {
                 },
             });
             const isToolError = isRecord(result) &&
-                typeof result.isError === 'boolean' &&
-                result.isError;
+                typeof result['isError'] === 'boolean' &&
+                result['isError'];
             taskManager.updateTask(taskId, {
                 status: isToolError ? 'failed' : 'completed',
                 statusMessage: isToolError
-                    ? (result
-                        .structuredContent?.error ?? 'Tool execution failed')
+                    ? (tryReadToolStructuredError(result) ?? 'Tool execution failed')
                     : 'Task completed successfully.',
                 result,
             });
@@ -313,11 +354,12 @@ async function handleToolCallRequest(server, request, context) {
  * ------------------------------------------------------------------------------------------------- */
 export function registerTaskHandlers(server) {
     server.server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
-        const context = resolveToolCallContext(extra);
+        const parsedExtra = parseHandlerExtra(extra);
+        const context = resolveToolCallContext(parsedExtra);
         const requestId = context.requestId !== undefined
             ? String(context.requestId)
             : randomUUID();
-        const sessionId = extra?.sessionId;
+        const sessionId = parsedExtra?.sessionId;
         return runWithRequestContext({
             requestId,
             operationId: requestId,
@@ -329,7 +371,8 @@ export function registerTaskHandlers(server) {
     });
     server.server.setRequestHandler(TaskGetSchema, async (request, extra) => {
         const { taskId } = request.params;
-        const ownerKey = resolveTaskOwnerKey(extra);
+        const parsedExtra = parseHandlerExtra(extra);
+        const ownerKey = resolveTaskOwnerKey(parsedExtra);
         const task = taskManager.getTask(taskId, ownerKey);
         if (!task)
             throwTaskNotFound();
@@ -345,8 +388,9 @@ export function registerTaskHandlers(server) {
     });
     server.server.setRequestHandler(TaskResultSchema, async (request, extra) => {
         const { taskId } = request.params;
-        const ownerKey = resolveTaskOwnerKey(extra);
-        const task = await taskManager.waitForTerminalTask(taskId, ownerKey, extra?.signal);
+        const parsedExtra = parseHandlerExtra(extra);
+        const ownerKey = resolveTaskOwnerKey(parsedExtra);
+        const task = await taskManager.waitForTerminalTask(taskId, ownerKey, parsedExtra?.signal);
         if (!task)
             throwTaskNotFound();
         if (task.status === 'failed') {
@@ -374,7 +418,9 @@ export function registerTaskHandlers(server) {
         if (task.status === 'cancelled') {
             throw new McpError(ErrorCode.InvalidRequest, 'Task was cancelled');
         }
-        const result = (task.result ?? { content: [] });
+        const result = isServerResult(task.result)
+            ? task.result
+            : { content: [] };
         return Promise.resolve({
             ...result,
             _meta: {
@@ -384,7 +430,8 @@ export function registerTaskHandlers(server) {
         });
     });
     server.server.setRequestHandler(TaskListSchema, async (request, extra) => {
-        const ownerKey = resolveTaskOwnerKey(extra);
+        const parsedExtra = parseHandlerExtra(extra);
+        const ownerKey = resolveTaskOwnerKey(parsedExtra);
         const cursor = request.params?.cursor;
         const { tasks, nextCursor } = taskManager.listTasks(cursor === undefined ? { ownerKey } : { ownerKey, cursor });
         return Promise.resolve({
@@ -401,7 +448,8 @@ export function registerTaskHandlers(server) {
     });
     server.server.setRequestHandler(TaskCancelSchema, async (request, extra) => {
         const { taskId } = request.params;
-        const ownerKey = resolveTaskOwnerKey(extra);
+        const parsedExtra = parseHandlerExtra(extra);
+        const ownerKey = resolveTaskOwnerKey(parsedExtra);
         const task = taskManager.cancelTask(taskId, ownerKey);
         if (!task)
             throwTaskNotFound();

package/dist/observability.js

@@ -66,11 +66,11 @@ function buildContextMetadata() {
         return undefined;
     const meta = {};
     if (requestId)
-        meta.requestId = requestId;
+        meta['requestId'] = requestId;
     if (operationId)
-        meta.operationId = operationId;
+        meta['operationId'] = operationId;
     if (includeSession)
-        meta.sessionId = sessionId;
+        meta['sessionId'] = sessionId;
     return meta;
 }
 function mergeMetadata(meta) {

package/dist/resources.js

@@ -1,6 +1,8 @@
 import { ResourceTemplate, } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { ErrorCode, McpError, } from '@modelcontextprotocol/sdk/types.js';
-import { get as getCacheEntry, keys as listCacheKeys, parseCachedPayload, parseCacheKey, resolveCachedPayloadContent, } from './cache.js';
+import { ErrorCode, McpError, SubscribeRequestSchema, UnsubscribeRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { get as getCacheEntry, keys as listCacheKeys, onCacheUpdate, parseCachedPayload, parseCacheKey, resolveCachedPayloadContent, } from './cache.js';
+import { logWarn } from './observability.js';
+import { isObject } from './type-guards.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;
@@ -34,8 +36,8 @@ function firstVariableValue(value) {
     return undefined;
 }
 function parseCacheResourceFromVariables(variables) {
-    const namespace = firstVariableValue(variables.namespace);
-    const hash = firstVariableValue(variables.hash);
+    const namespace = firstVariableValue(variables['namespace']);
+    const hash = firstVariableValue(variables['hash']);
     if (!namespace || !hash)
         return null;
     const decoded = {
@@ -86,7 +88,7 @@ function completeCacheNamespaces(value) {
 }
 function completeCacheHashes(value, context) {
     const normalized = value.trim().toLowerCase();
-    const namespace = context?.arguments?.namespace?.trim();
+    const namespace = context?.arguments?.['namespace']?.trim();
     const hashes = new Set();
     for (const key of listCacheKeys()) {
         const parsed = parseCacheKey(key);
@@ -106,7 +108,6 @@ function listCacheResources() {
     const resources = listCacheKeys()
         .map((key) => parseCacheKey(key))
         .filter((parts) => Boolean(parts))
-        .slice(0, MAX_COMPLETION_VALUES)
         .map((parts) => {
         const cacheParts = {
             namespace: parts.namespace,
@@ -126,6 +127,85 @@ function listCacheResources() {
     });
     return { resources };
 }
+function normalizeSubscriptionUri(uri) {
+    if (!URL.canParse(uri)) {
+        throw new McpError(ErrorCode.InvalidParams, 'Invalid resource URI');
+    }
+    const parsedUri = new URL(uri);
+    const cacheParts = parseCacheResourceFromUri(parsedUri);
+    if (cacheParts)
+        return toCacheResourceUri(cacheParts);
+    return parsedUri.href;
+}
+function registerCacheResourceNotifications(server) {
+    const subscribedResourceUris = new Set();
+    server.server.setRequestHandler(SubscribeRequestSchema, async (request) => {
+        subscribedResourceUris.add(normalizeSubscriptionUri(request.params.uri));
+        return Promise.resolve({});
+    });
+    server.server.setRequestHandler(UnsubscribeRequestSchema, async (request) => {
+        subscribedResourceUris.delete(normalizeSubscriptionUri(request.params.uri));
+        return Promise.resolve({});
+    });
+    const unsubscribe = onCacheUpdate((event) => {
+        const changedUri = toCacheResourceUri({
+            namespace: event.namespace,
+            hash: event.urlHash,
+        });
+        if (server.isConnected() && subscribedResourceUris.has(changedUri)) {
+            void server.server
+                .sendResourceUpdated({ uri: changedUri })
+                .catch((error) => {
+                logWarn('Failed to send resource updated notification', {
+                    uri: changedUri,
+                    error,
+                });
+            });
+        }
+        if (!event.listChanged)
+            return;
+        if (!server.isConnected())
+            return;
+        try {
+            server.sendResourceListChanged();
+        }
+        catch (error) {
+            logWarn('Failed to send resources list changed notification', { error });
+        }
+    });
+    let cleanedUp = false;
+    const cleanup = () => {
+        if (cleanedUp)
+            return;
+        cleanedUp = true;
+        unsubscribe();
+    };
+    const originalOnClose = server.server.onclose;
+    server.server.onclose = () => {
+        cleanup();
+        originalOnClose?.();
+    };
+    const originalClose = server.close.bind(server);
+    server.close = async () => {
+        cleanup();
+        await originalClose();
+    };
+}
+function normalizeTemplateVariables(variables) {
+    if (!isObject(variables))
+        return {};
+    const normalized = {};
+    for (const [key, value] of Object.entries(variables)) {
+        if (typeof value === 'string' || value === undefined) {
+            normalized[key] = value;
+            continue;
+        }
+        if (Array.isArray(value)) {
+            normalized[key] = value.filter((item) => typeof item === 'string');
+        }
+    }
+    return normalized;
+}
 function resolveCacheResourceParts(uri, variables) {
     const fromVariables = parseCacheResourceFromVariables(variables);
     if (fromVariables)
@@ -212,5 +292,6 @@ export function registerCacheResourceTemplate(server, iconInfo) {
                 ],
             }
             : {}),
-    }, (uri, variables) => readCacheResource(uri, variables));
+    }, (uri, variables) => readCacheResource(uri, normalizeTemplateVariables(variables)));
+    registerCacheResourceNotifications(server);
 }

package/dist/server.js

@@ -42,7 +42,10 @@ catch (error) {
 function createServerCapabilities() {
     return {
         logging: {},
-        resources: {},
+        resources: {
+            subscribe: true,
+            listChanged: true,
+        },
         tools: {},
         prompts: {},
         completions: {},

package/dist/session.js

@@ -56,12 +56,15 @@ class SessionCleanupLoop {
         for await (const getNow of ticks) {
             const now = getNow();
             const evicted = this.store.evictExpired();
-            for (const session of evicted) {
-                unregisterMcpSessionServerByServer(session.server);
-                void Promise.allSettled([
-                    session.transport.close(),
-                    session.server.close(),
-                ]).then((results) => {
+            const closeBatchSize = 10;
+            for (let i = 0; i < evicted.length; i += closeBatchSize) {
+                const batch = evicted.slice(i, i + closeBatchSize);
+                await Promise.allSettled(batch.map(async (session) => {
+                    unregisterMcpSessionServerByServer(session.server);
+                    const results = await Promise.allSettled([
+                        session.transport.close(),
+                        session.server.close(),
+                    ]);
                     const [transportResult, serverResult] = results;
                     if (transportResult.status === 'rejected') {
                         logWarn('Failed to close expired session transport', {
@@ -73,7 +76,9 @@ class SessionCleanupLoop {
                             error: formatError(serverResult.reason),
                         });
                     }
-                });
+                }));
+                if (signal.aborted)
+                    return;
             }
             if (evicted.length > 0) {
                 logInfo('Expired sessions evicted', {

package/dist/tools.js

@@ -53,6 +53,11 @@ const fetchUrlOutputSchema = z.strictObject({
         .max(config.constants.maxUrlLength)
         .optional()
         .describe('The final response URL after redirects'),
+    cacheResourceUri: z
+        .string()
+        .max(config.constants.maxUrlLength)
+        .optional()
+        .describe('Internal cache resource URI for retrieving full markdown via resources/read'),
     title: z.string().max(512).optional().describe('Page title'),
     metadata: z
         .strictObject({
@@ -413,8 +418,27 @@ function buildEmbeddedResource(content, url, title) {
         resource,
     };
 }
-function buildToolContentBlocks(structuredContent, embeddedResource) {
+function buildCacheResourceLink(cacheResourceUri, contentSize, fetchedAt) {
+    return {
+        type: 'resource_link',
+        uri: cacheResourceUri,
+        name: 'cached-markdown',
+        title: 'Cached Fetch Output',
+        description: 'Read full markdown via resources/read.',
+        mimeType: 'text/markdown',
+        ...(contentSize > 0 ? { size: contentSize } : {}),
+        annotations: {
+            audience: ['assistant'],
+            priority: 0.8,
+            lastModified: fetchedAt,
+        },
+    };
+}
+function buildToolContentBlocks(structuredContent, resourceLink, embeddedResource) {
     const blocks = [buildTextBlock(structuredContent)];
+    if (resourceLink) {
+        blocks.push(resourceLink);
+    }
     if (embeddedResource) {
         blocks.push(embeddedResource);
     }
@@ -434,7 +458,7 @@ function logRawUrlTransformation(resolvedUrl) {
 }
 function extractTitle(value) {
     const record = asRecord(value);
-    const title = record ? record.title : undefined;
+    const title = record ? record['title'] : undefined;
     return typeof title === 'string' ? title : undefined;
 }
 function logCacheMiss(reason, cacheNamespace, normalizedUrl, error) {
@@ -682,6 +706,7 @@ function serializeMarkdownResult(result) {
  * fetch-url tool implementation
  * ------------------------------------------------------------------------------------------------- */
 function buildStructuredContent(pipeline, inlineResult, inputUrl) {
+    const cacheResourceUri = resolveCacheResourceUri(pipeline.cacheKey);
     const truncated = inlineResult.truncated ?? pipeline.data.truncated;
     let markdown = inlineResult.content;
     if (pipeline.data.truncated &&
@@ -694,6 +719,7 @@ function buildStructuredContent(pipeline, inlineResult, inputUrl) {
         url: pipeline.originalUrl ?? pipeline.url,
         resolvedUrl: pipeline.url,
         ...(pipeline.finalUrl ? { finalUrl: pipeline.finalUrl } : {}),
+        ...(cacheResourceUri ? { cacheResourceUri } : {}),
         inputUrl,
         title: pipeline.data.title,
         ...(metadata ? { metadata } : {}),
@@ -704,14 +730,30 @@ function buildStructuredContent(pipeline, inlineResult, inputUrl) {
         ...(truncated ? { truncated: true } : {}),
     };
 }
+function resolveCacheResourceUri(cacheKey) {
+    if (!cacheKey)
+        return undefined;
+    if (!cache.isEnabled())
+        return undefined;
+    if (!cache.get(cacheKey))
+        return undefined;
+    const parsed = cache.parseCacheKey(cacheKey);
+    if (!parsed)
+        return undefined;
+    return `internal://cache/${encodeURIComponent(parsed.namespace)}/${encodeURIComponent(parsed.urlHash)}`;
+}
 function buildFetchUrlContentBlocks(structuredContent, pipeline, inlineResult) {
+    const cacheResourceUri = readString(structuredContent, 'cacheResourceUri');
     const contentToEmbed = config.runtime.httpMode
         ? inlineResult.content
         : pipeline.data.content;
+    const resourceLink = cacheResourceUri
+        ? buildCacheResourceLink(cacheResourceUri, inlineResult.contentSize, pipeline.fetchedAt)
+        : null;
     const embedded = contentToEmbed && pipeline.url
         ? buildEmbeddedResource(contentToEmbed, pipeline.url, pipeline.data.title)
         : null;
-    return buildToolContentBlocks(structuredContent, embedded);
+    return buildToolContentBlocks(structuredContent, resourceLink, embedded);
 }
 function buildResponse(pipeline, inlineResult, inputUrl) {
     const structuredContent = buildStructuredContent(pipeline, inlineResult, inputUrl);

package/dist/transform.js

@@ -44,7 +44,7 @@ function getTagName(node) {
 }
 function getAbortReason(signal) {
     const record = isObject(signal) ? signal : null;
-    return record && 'reason' in record ? record.reason : undefined;
+    return record && 'reason' in record ? record['reason'] : undefined;
 }
 function isTimeoutAbortReason(reason) {
     return reason instanceof Error && reason.name === 'TimeoutError';
@@ -424,6 +424,35 @@ function isReadabilityCompatible(doc) {
             'function' &&
         typeof record.querySelector === 'function');
 }
+function resolveCollapsedTextLengthUpTo(text, max) {
+    if (max <= 0)
+        return 0;
+    let length = 0;
+    let seenNonWhitespace = false;
+    let pendingSpace = false;
+    for (let i = 0; i < text.length; i += 1) {
+        const code = text.charCodeAt(i);
+        const isWhitespace = code <= 0x20;
+        if (isWhitespace) {
+            if (seenNonWhitespace)
+                pendingSpace = true;
+            continue;
+        }
+        if (!seenNonWhitespace) {
+            seenNonWhitespace = true;
+        }
+        else if (pendingSpace) {
+            length += 1;
+            pendingSpace = false;
+            if (length >= max)
+                return length;
+        }
+        length += 1;
+        if (length >= max)
+            return length;
+    }
+    return length;
+}
 function extractArticle(document, url, signal) {
     if (!isReadabilityCompatible(document)) {
         logWarn('Document not compatible with Readability');
@@ -436,7 +465,7 @@ function extractArticle(document, url, signal) {
         const rawText = doc.querySelector('body')?.textContent ??
             doc.documentElement.textContent ??
             '';
-        const textLength = rawText.replace(/\s+/g, ' ').trim().length;
+        const textLength = resolveCollapsedTextLengthUpTo(rawText, 401);
         if (textLength < 100) {
             logWarn('Very minimal server-rendered content detected (< 100 chars). ' +
                 'This might be a client-side rendered (SPA) application. ' +
@@ -1610,13 +1639,13 @@ function isWorkerErrorPayload(value) {
 function isWorkerResponse(raw) {
     if (!isObject(raw))
         return false;
-    if (typeof raw.id !== 'string')
+    if (typeof raw['id'] !== 'string')
         return false;
-    if (raw.type === 'result') {
-        return isWorkerResultPayload(raw.result);
+    if (raw['type'] === 'result') {
+        return isWorkerResultPayload(raw['result']);
     }
-    if (raw.type === 'error') {
-        return isWorkerErrorPayload(raw.error);
+    if (raw['type'] === 'error') {
+        return isWorkerErrorPayload(raw['error']);
     }
     return false;
 }
@@ -2287,7 +2316,7 @@ async function transformWithWorkerPool(htmlOrBuffer, url, options) {
     });
 }
 function resolveWorkerFallback(error, htmlOrBuffer, url, options) {
-    const isQueueFull = error instanceof FetchError && error.details.reason === 'queue_full';
+    const isQueueFull = error instanceof FetchError && error.details['reason'] === 'queue_full';
     if (isQueueFull) {
         logWarn('Transform worker queue full; falling back to in-process', {
             url: redactUrl(url),

package/dist/workers/transform-child.js

@@ -122,15 +122,16 @@ process.on('message', (raw) => {
     if (!raw || typeof raw !== 'object')
         return;
     const msg = raw;
-    if (msg.type === 'cancel') {
-        if (typeof msg.id !== 'string')
+    const { type, id } = msg;
+    if (type === 'cancel') {
+        if (typeof id !== 'string')
             return;
-        const controller = controllersById.get(msg.id);
+        const controller = controllersById.get(id);
         if (controller)
             controller.abort(new Error('Canceled'));
         return;
     }
-    if (msg.type === 'transform') {
+    if (type === 'transform') {
         handleTransform(msg);
     }
 });

package/dist/workers/transform-worker.js

@@ -114,15 +114,16 @@ port.on('message', (raw) => {
     if (!raw || typeof raw !== 'object')
         return;
     const msg = raw;
-    if (msg.type === 'cancel') {
-        if (typeof msg.id !== 'string')
+    const { type, id } = msg;
+    if (type === 'cancel') {
+        if (typeof id !== 'string')
             return;
-        const controller = controllersById.get(msg.id);
+        const controller = controllersById.get(id);
         if (controller)
             controller.abort(new Error('Canceled'));
         return;
     }
-    if (msg.type === 'transform') {
+    if (type === 'transform') {
         handleTransform(msg);
     }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@j0hanz/fetch-url-mcp",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "mcpName": "io.github.j0hanz/fetch-url-mcp",
   "description": "Intelligent web content fetcher MCP server that converts HTML to clean, AI-readable Markdown",
   "type": "module",