@j0hanz/fetch-url-mcp 1.0.0 → 1.1.0

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) {