@j0hanz/fetch-url-mcp 1.6.0 → 1.7.0

package/dist/cli.d.ts

@@ -16,3 +16,4 @@ type CliParseResult = CliParseSuccess | CliParseFailure;
 export declare function renderCliUsage(): string;
 export declare function parseCliArgs(args: readonly string[]): CliParseResult;
 export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAIA,UAAU,SAAS;IACjB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,UAAU,eAAe;IACvB,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;CAC5B;AAED,UAAU,eAAe;IACvB,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,KAAK,cAAc,GAAG,eAAe,GAAG,eAAe,CAAC;AA2CxD,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,cAAc,CA2BpE"}

package/dist/http/auth.d.ts

@@ -1,10 +1,16 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
+import { InvalidTokenError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
 import type { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
 import { type RequestContext } from './helpers.js';
 declare class CorsPolicy {
     handle(ctx: RequestContext): boolean;
 }
 export declare const corsPolicy: CorsPolicy;
+export declare class InsufficientScopeError extends InvalidTokenError {
+    readonly requiredScopes: readonly string[];
+    constructor(requiredScopes: readonly string[], message?: string);
+}
+export declare function isInsufficientScopeError(error: unknown): error is InsufficientScopeError;
 declare class HostOriginPolicy {
     validate(ctx: RequestContext): boolean;
     private resolveHostHeader;
@@ -21,6 +27,7 @@ interface McpProtocolVersionCheckOptions {
     expectedVersion?: string;
 }
 export declare function ensureMcpProtocolVersion(req: IncomingMessage, res: ServerResponse, options?: McpProtocolVersionCheckOptions): boolean;
+export declare function isOAuthMetadataEnabled(): boolean;
 export declare function buildAuthFingerprint(auth: AuthInfo | undefined): string | null;
 declare class AuthService {
     private readonly staticTokenDigests;
@@ -31,6 +38,9 @@ declare class AuthService {
     private buildStaticAuthInfo;
     private verifyStaticToken;
     private stripHash;
+    private canonicalizeResourceUri;
+    private readAudienceValues;
+    private assertTokenAudience;
     private buildBasicAuthHeader;
     private buildIntrospectionRequest;
     private requestIntrospection;
@@ -39,6 +49,7 @@ declare class AuthService {
     private verifyWithIntrospection;
 }
 export declare function applyUnauthorizedAuthHeaders(req: IncomingMessage, res: ServerResponse): void;
+export declare function applyInsufficientScopeAuthHeaders(req: IncomingMessage, res: ServerResponse, requiredScopes: readonly string[], message?: string): void;
 export declare function buildProtectedResourceMetadataDocument(req: IncomingMessage): {
     resource: string;
     resource_metadata: string;
@@ -49,3 +60,4 @@ export declare function buildProtectedResourceMetadataDocument(req: IncomingMess
 export declare function isProtectedResourceMetadataPath(pathname: string): boolean;
 export declare const authService: AuthService;
 export {};
+//# sourceMappingURL=auth.d.ts.map

package/dist/http/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/http/auth.ts"],"names":[],"mappings":"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"}

package/dist/http/auth.js

@@ -35,6 +35,17 @@ export const corsPolicy = new CorsPolicy();
 // ---------------------------------------------------------------------------
 const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1']);
 const WILDCARD_HOSTS = new Set(['0.0.0.0', '::']);
+export class InsufficientScopeError extends InvalidTokenError {
+    requiredScopes;
+    constructor(requiredScopes, message = 'Insufficient scope') {
+        super(message);
+        this.requiredScopes = requiredScopes;
+        this.name = 'InsufficientScopeError';
+    }
+}
+export function isInsufficientScopeError(error) {
+    return error instanceof InsufficientScopeError;
+}
 function hasConstantTimeMatch(candidates, input) {
     // Avoid leaking match index via early-return.
     let matched = 0;
@@ -158,6 +169,9 @@ export function assertHttpModeConfiguration() {
     if (isRemoteBinding && config.auth.mode !== 'oauth') {
         throw new Error('OAuth authentication is required for remote bindings');
     }
+    if (config.auth.mode === 'oauth' && !config.auth.issuerUrl) {
+        throw new Error('OAuth mode requires OAUTH_ISSUER_URL to serve RFC9728 metadata');
+    }
     if (config.auth.mode === 'static' && config.auth.staticTokens.length === 0) {
         throw new Error('Static auth requires ACCESS_TOKENS or API_KEY to be configured');
     }
@@ -180,7 +194,7 @@ function resolveMcpProtocolVersion(req) {
 }
 export function ensureMcpProtocolVersion(req, res, options) {
     const version = resolveMcpProtocolVersion(req);
-    const requireHeader = options?.requireHeader ?? false;
+    const requireHeader = options?.requireHeader ?? config.security.allowRemote;
     if (!version) {
         if (!requireHeader) {
             // Permissive backward-compat fallback: clients predating MCP 2025-03-26 do not
@@ -205,6 +219,9 @@ export function ensureMcpProtocolVersion(req, res, options) {
     }
     return true;
 }
+export function isOAuthMetadataEnabled() {
+    return config.auth.mode === 'oauth';
+}
 // ---------------------------------------------------------------------------
 // Auth fingerprint
 // ---------------------------------------------------------------------------
@@ -282,6 +299,48 @@ class AuthService {
         clean.hash = '';
         return clean.href;
     }
+    canonicalizeResourceUri(value) {
+        if (!URL.canParse(value))
+            return null;
+        const url = new URL(value);
+        url.hash = '';
+        url.protocol = url.protocol.toLowerCase();
+        url.hostname = url.hostname.toLowerCase();
+        const { href } = url;
+        if (url.pathname === '/' && !url.search && href.endsWith('/')) {
+            return href.slice(0, -1);
+        }
+        return href;
+    }
+    readAudienceValues(payload) {
+        const values = [];
+        for (const key of ['aud', 'resource']) {
+            const raw = payload[key];
+            if (typeof raw === 'string') {
+                values.push(raw);
+                continue;
+            }
+            if (!Array.isArray(raw))
+                continue;
+            values.push(...raw.filter((value) => typeof value === 'string'));
+        }
+        return values;
+    }
+    assertTokenAudience(payload) {
+        const expected = this.canonicalizeResourceUri(this.stripHash(config.auth.resourceUrl));
+        if (!expected) {
+            throw new ServerError('Configured resource URL is invalid');
+        }
+        const audiences = this.readAudienceValues(payload)
+            .map((value) => this.canonicalizeResourceUri(value))
+            .filter((value) => value !== null);
+        if (audiences.length === 0) {
+            throw new InvalidTokenError('Token missing audience binding');
+        }
+        if (!audiences.includes(expected)) {
+            throw new InvalidTokenError('Token audience does not match this MCP server');
+        }
+    }
     buildBasicAuthHeader(clientId, clientSecret) {
         // Base64 is only an encoding for header transport; it is NOT encryption.
         const credentials = `${clientId}:${clientSecret ?? ''}`;
@@ -341,7 +400,7 @@ class AuthService {
         const tokenScopeSet = new Set(tokenScopes);
         const missing = requiredScopes.filter((s) => !tokenScopeSet.has(s));
         if (missing.length > 0) {
-            throw new InvalidTokenError('Insufficient scope');
+            throw new InsufficientScopeError(missing);
         }
     }
     async verifyWithIntrospection(token, signal) {
@@ -353,6 +412,7 @@ class AuthService {
         if (!isObject(payload) || payload['active'] !== true) {
             throw new InvalidTokenError('Token is inactive');
         }
+        this.assertTokenAudience(payload);
         const info = this.buildIntrospectionAuthInfo(token, payload);
         this.assertRequiredScopes(info.scopes);
         return info;
@@ -380,17 +440,36 @@ function buildResourceMetadataUrl(req) {
     return buildRequestScopedProtectedResourceUrls(req).resourceMetadata;
 }
 export function applyUnauthorizedAuthHeaders(req, res) {
+    if (!isOAuthMetadataEnabled())
+        return;
     const resourceMetadata = buildResourceMetadataUrl(req);
-    res.setHeader('WWW-Authenticate', `Bearer resource_metadata="${resourceMetadata}"`);
+    const challengeParts = [`resource_metadata="${resourceMetadata}"`];
+    if (config.auth.requiredScopes.length > 0) {
+        challengeParts.push(`scope="${config.auth.requiredScopes.join(' ')}"`);
+    }
+    res.setHeader('WWW-Authenticate', `Bearer ${challengeParts.join(', ')}`);
+}
+export function applyInsufficientScopeAuthHeaders(req, res, requiredScopes, message = 'Additional authorization scope is required') {
+    if (!isOAuthMetadataEnabled())
+        return;
+    const resourceMetadata = buildResourceMetadataUrl(req);
+    const challengeParts = [
+        'error="insufficient_scope"',
+        `scope="${requiredScopes.join(' ')}"`,
+        `resource_metadata="${resourceMetadata}"`,
+        `error_description="${message.replaceAll('"', "'")}"`,
+    ];
+    res.setHeader('WWW-Authenticate', `Bearer ${challengeParts.join(', ')}`);
 }
 export function buildProtectedResourceMetadataDocument(req) {
     const urls = buildRequestScopedProtectedResourceUrls(req);
+    if (!config.auth.issuerUrl) {
+        throw new ServerError('OAuth issuer URL is required for protected resource metadata');
+    }
     return {
         resource: urls.resource,
         resource_metadata: urls.resourceMetadata,
-        authorization_servers: config.auth.issuerUrl
-            ? [config.auth.issuerUrl.href]
-            : [],
+        authorization_servers: [config.auth.issuerUrl.href],
         bearer_methods_supported: ['header'],
         scopes_supported: config.auth.requiredScopes,
     };

package/dist/http/health.d.ts

@@ -4,3 +4,4 @@ export declare function resetEventLoopMonitoring(): void;
 export declare function disableEventLoopMonitoring(): void;
 export declare function shouldHandleHealthRoute(ctx: RequestContext): boolean;
 export declare function sendHealthRouteResponse(store: SessionStore, ctx: RequestContext, authPresent: boolean): boolean;
+//# sourceMappingURL=health.d.ts.map

package/dist/http/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/http/health.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAGnD,OAAO,EAAE,KAAK,cAAc,EAAY,MAAM,cAAc,CAAC;AAY7D,wBAAgB,wBAAwB,IAAI,IAAI,CAI/C;AAED,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD;AAiMD,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAEpE;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,YAAY,EACnB,GAAG,EAAE,cAAc,EACnB,WAAW,EAAE,OAAO,GACnB,OAAO,CAOT"}

package/dist/http/helpers.d.ts

@@ -48,3 +48,4 @@ declare class JsonBodyReader {
 }
 export declare const jsonBodyReader: JsonBodyReader;
 export {};
+//# sourceMappingURL=helpers.d.ts.map

package/dist/http/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/http/helpers.ts"],"names":[],"mappings":"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"}

package/dist/http/native.d.ts

@@ -3,3 +3,4 @@ export declare function startHttpServer(): Promise<{
     port: number;
     host: string;
 }>;
+//# sourceMappingURL=native.d.ts.map

package/dist/http/native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native.d.ts","sourceRoot":"","sources":["../../src/http/native.ts"],"names":[],"mappings":"AA64BA,wBAAsB,eAAe,IAAI,OAAO,CAAC;IAC/C,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,CAAC,CA8DD"}

package/dist/http/native.js

@@ -10,15 +10,15 @@ import { config, enableHttpMode } from '../lib/core.js';
 import { logError, logInfo, registerMcpSessionServer, resolveMcpSessionIdByServer, runWithRequestContext, unregisterMcpSessionServer, unregisterMcpSessionServerByServer, } from '../lib/core.js';
 import { composeCloseHandlers, createSessionStore, createSlotTracker, ensureSessionCapacity, reserveSessionSlot, startSessionCleanupLoop, } from '../lib/core.js';
 import { handleDownload } from '../lib/http.js';
-import { acceptsEventStream, acceptsJsonAndEventStream, isJsonRpcBatchRequest, isMcpRequestBody, } from '../lib/mcp-tools.js';
+import { acceptsEventStream, acceptsJsonAndEventStream, isJsonRpcBatchRequest, isMcpMessageBody, isMcpRequestBody, } from '../lib/mcp-tools.js';
 import { cancelTasksForOwner } from '../lib/mcp-tools.js';
 import { toError } from '../lib/utils.js';
 import { applyHttpServerTuning, drainConnectionsOnShutdown, } from '../lib/utils.js';
 import { isObject } from '../lib/utils.js';
 import { createMcpServerForHttpSession } from '../server.js';
-import { applyUnauthorizedAuthHeaders, assertHttpModeConfiguration, authService, buildAuthFingerprint, buildProtectedResourceMetadataDocument, corsPolicy, ensureMcpProtocolVersion, hostOriginPolicy, isProtectedResourceMetadataPath, SUPPORTED_MCP_PROTOCOL_VERSIONS, } from './auth.js';
+import { applyInsufficientScopeAuthHeaders, applyUnauthorizedAuthHeaders, assertHttpModeConfiguration, authService, buildAuthFingerprint, buildProtectedResourceMetadataDocument, corsPolicy, ensureMcpProtocolVersion, hostOriginPolicy, isInsufficientScopeError, isOAuthMetadataEnabled, isProtectedResourceMetadataPath, SUPPORTED_MCP_PROTOCOL_VERSIONS, } from './auth.js';
 import { disableEventLoopMonitoring, resetEventLoopMonitoring, sendHealthRouteResponse, shouldHandleHealthRoute, } from './health.js';
-import { buildRequestContext, closeMcpServerBestEffort, closeTransportBestEffort, createRequestAbortSignal, createTransportAdapter, DEFAULT_BODY_LIMIT_BYTES, drainRequest, findDuplicateSingleValueHeader, getHeaderValue, getMcpSessionId, jsonBodyReader, registerInboundBlockList, sendError, sendJson, sendText, } from './helpers.js';
+import { buildRequestContext, closeMcpServerBestEffort, closeTransportBestEffort, createRequestAbortSignal, createTransportAdapter, DEFAULT_BODY_LIMIT_BYTES, drainRequest, findDuplicateSingleValueHeader, getHeaderValue, getMcpSessionId, jsonBodyReader, registerInboundBlockList, sendEmpty, sendError, sendJson, } from './helpers.js';
 import { createRateLimitManagerImpl, } from './rate-limit.js';
 // ---------------------------------------------------------------------------
 // MCP session gateway
@@ -41,6 +41,13 @@ function resolveRequestedProtocolVersion(body) {
     }
     return normalized;
 }
+function resolveProtocolVersionHeader(req) {
+    const header = getHeaderValue(req, 'mcp-protocol-version');
+    if (!header)
+        return undefined;
+    const normalized = header.trim();
+    return normalized.length > 0 ? normalized : undefined;
+}
 function isInitializedNotification(method) {
     return method === 'notifications/initialized';
 }
@@ -66,36 +73,33 @@ class McpSessionGateway {
             sendError(ctx.res, -32600, 'Batch requests not supported');
             return;
         }
-        if (!isMcpRequestBody(body)) {
+        if (!isMcpMessageBody(body)) {
             sendError(ctx.res, -32600, 'Invalid request body');
             return;
         }
         const requestId = body.id ?? null;
-        const isInitializedMethod = isInitializedNotification(body.method);
+        const method = isMcpRequestBody(body) ? body.method : null;
+        const isInitializedMethod = method !== null && isInitializedNotification(method);
         const isInitNotification = isInitializedMethod && body.id === undefined;
         const sessionId = getMcpSessionId(ctx.req);
         if (isInitializedMethod && !isInitNotification) {
             sendError(ctx.res, -32600, 'notifications/initialized must be sent as a notification', 400, requestId);
             return;
         }
-        const session = sessionId ? this.store.get(sessionId) : undefined;
-        if (sessionId && !session) {
-            sendError(ctx.res, -32600, 'Session not found', 404, requestId);
+        const session = sessionId
+            ? this.getAuthenticatedSessionById(sessionId, ctx.auth, ctx.res, requestId)
+            : undefined;
+        if (sessionId && !session)
             return;
-        }
         if (!session && isInitNotification) {
             sendError(ctx.res, -32600, 'Missing session ID', 400, requestId);
             return;
         }
         if (session) {
-            if (!ensureMcpProtocolVersion(ctx.req, ctx.res, {
-                requireHeader: true,
-                expectedVersion: session.negotiatedProtocolVersion,
-            })) {
+            if (!this.ensureSessionProtocolVersion(ctx, session))
                 return;
-            }
             if (!session.protocolInitialized) {
-                const isPing = isPingRequest(body.method);
+                const isPing = method !== null && isPingRequest(method);
                 if (!isInitNotification && !isPing) {
                     sendError(ctx.res, -32600, 'Session not initialized', 400, requestId);
                     return;
@@ -110,16 +114,12 @@ class McpSessionGateway {
             }
         }
         if (session && isInitNotification) {
-            if (!session.protocolInitialized) {
-                session.protocolInitialized = true;
-            }
-            if (sessionId)
-                this.store.touch(sessionId);
-            sendText(ctx.res, 200, '');
+            this.markSessionInitialized(sessionId, session);
+            sendEmpty(ctx.res, 202);
             return;
         }
         logInfo('[MCP POST]', {
-            method: body.method,
+            method: method ?? 'response',
             id: body.id,
             sessionId,
         });
@@ -129,27 +129,14 @@ class McpSessionGateway {
         await transport.handleRequest(ctx.req, ctx.res, body);
     }
     async handleGet(ctx) {
-        const sessionId = getMcpSessionId(ctx.req);
-        if (!sessionId) {
-            sendError(ctx.res, -32600, 'Missing session ID');
-            return;
-        }
-        const session = this.store.get(sessionId);
-        if (!session) {
-            sendError(ctx.res, -32600, 'Session not found', 404);
+        const sessionId = this.getRequiredSessionId(ctx.req, ctx.res);
+        if (!sessionId)
             return;
-        }
-        const fingerprint = buildAuthFingerprint(ctx.auth);
-        if (!fingerprint || session.authFingerprint !== fingerprint) {
-            sendError(ctx.res, -32600, 'Session not found', 404);
+        const session = this.getAuthenticatedSessionById(sessionId, ctx.auth, ctx.res);
+        if (!session)
             return;
-        }
-        if (!ensureMcpProtocolVersion(ctx.req, ctx.res, {
-            requireHeader: true,
-            expectedVersion: session.negotiatedProtocolVersion,
-        })) {
+        if (!this.ensureSessionProtocolVersion(ctx, session))
             return;
-        }
         const acceptHeader = getHeaderValue(ctx.req, 'accept');
         if (!acceptsEventStream(acceptHeader)) {
             sendJson(ctx.res, 406, {
@@ -161,27 +148,14 @@ class McpSessionGateway {
         await session.transport.handleRequest(ctx.req, ctx.res);
     }
     async handleDelete(ctx) {
-        const sessionId = getMcpSessionId(ctx.req);
-        if (!sessionId) {
-            sendError(ctx.res, -32600, 'Missing session ID');
+        const sessionId = this.getRequiredSessionId(ctx.req, ctx.res);
+        if (!sessionId)
             return;
-        }
-        const session = this.store.get(sessionId);
-        if (!session) {
-            sendError(ctx.res, -32600, 'Session not found', 404);
-            return;
-        }
-        const fingerprint = buildAuthFingerprint(ctx.auth);
-        if (!fingerprint || session.authFingerprint !== fingerprint) {
-            sendError(ctx.res, -32600, 'Session not found', 404);
+        const session = this.getAuthenticatedSessionById(sessionId, ctx.auth, ctx.res);
+        if (!session)
             return;
-        }
-        if (!ensureMcpProtocolVersion(ctx.req, ctx.res, {
-            requireHeader: true,
-            expectedVersion: session.negotiatedProtocolVersion,
-        })) {
+        if (!this.ensureSessionProtocolVersion(ctx, session))
             return;
-        }
         await session.transport.close();
         this.cleanupSessionRecord(sessionId, 'session-delete');
         sendJson(ctx.res, 200, { status: 'closed' });
@@ -192,7 +166,7 @@ class McpSessionGateway {
             const fingerprint = buildAuthFingerprint(ctx.auth);
             return this.getExistingTransport(sessionId, fingerprint, ctx.res, requestId);
         }
-        if (!isInitializeRequest(ctx.body)) {
+        if (!isMcpRequestBody(ctx.body) || !isInitializeRequest(ctx.body)) {
             sendError(ctx.res, -32600, 'Missing session ID', 400, requestId);
             return null;
         }
@@ -201,20 +175,55 @@ class McpSessionGateway {
             sendError(ctx.res, -32602, `Unsupported protocolVersion; supported versions: ${[...SUPPORTED_MCP_PROTOCOL_VERSIONS].join(', ')}`, 400, requestId);
             return null;
         }
+        const headerProtocolVersion = resolveProtocolVersionHeader(ctx.req);
+        if (headerProtocolVersion &&
+            headerProtocolVersion !== negotiatedProtocolVersion) {
+            sendError(ctx.res, -32600, `initialize protocolVersion mismatch: header=${headerProtocolVersion}, body=${negotiatedProtocolVersion}`, 400, requestId);
+            return null;
+        }
         return this.createNewSession(ctx, requestId, negotiatedProtocolVersion);
     }
     getExistingTransport(sessionId, authFingerprint, res, requestId) {
+        const session = this.getAuthenticatedSessionById(sessionId, authFingerprint, res, requestId);
+        if (!session)
+            return null;
+        this.store.touch(sessionId);
+        return session.transport;
+    }
+    getRequiredSessionId(req, res, requestId = null) {
+        const sessionId = getMcpSessionId(req);
+        if (sessionId)
+            return sessionId;
+        sendError(res, -32600, 'Missing session ID', 400, requestId);
+        return null;
+    }
+    getAuthenticatedSessionById(sessionId, auth, res, requestId = null) {
         const session = this.store.get(sessionId);
         if (!session) {
             sendError(res, -32600, 'Session not found', 404, requestId);
             return null;
         }
-        if (!authFingerprint || session.authFingerprint !== authFingerprint) {
+        const fingerprint = typeof auth === 'string' || auth === null
+            ? auth
+            : buildAuthFingerprint(auth);
+        if (!fingerprint || session.authFingerprint !== fingerprint) {
             sendError(res, -32600, 'Session not found', 404, requestId);
             return null;
         }
-        this.store.touch(sessionId);
-        return session.transport;
+        return session;
+    }
+    ensureSessionProtocolVersion(ctx, session) {
+        return ensureMcpProtocolVersion(ctx.req, ctx.res, {
+            requireHeader: true,
+            expectedVersion: session.negotiatedProtocolVersion,
+        });
+    }
+    markSessionInitialized(sessionId, session) {
+        if (!session.protocolInitialized) {
+            session.protocolInitialized = true;
+        }
+        if (sessionId)
+            this.store.touch(sessionId);
     }
     async createNewSession(ctx, requestId, negotiatedProtocolVersion) {
         const authFingerprint = buildAuthFingerprint(ctx.auth);
@@ -367,6 +376,8 @@ class HttpDispatcher {
     tryHandleProtectedResourceMetadataRoute(ctx) {
         if (ctx.method !== 'GET')
             return false;
+        if (!isOAuthMetadataEnabled())
+            return false;
         if (!isProtectedResourceMetadataPath(ctx.url.pathname))
             return false;
         const document = buildProtectedResourceMetadataDocument(ctx.req);
@@ -420,8 +431,14 @@ class HttpDispatcher {
             return await authService.authenticate(ctx.req, ctx.signal);
         }
         catch (err) {
+            const message = err instanceof Error ? err.message : 'Unauthorized';
+            if (isInsufficientScopeError(err)) {
+                applyInsufficientScopeAuthHeaders(ctx.req, ctx.res, err.requiredScopes, message);
+                sendError(ctx.res, -32000, message, 403);
+                return null;
+            }
             applyUnauthorizedAuthHeaders(ctx.req, ctx.res);
-            sendError(ctx.res, -32000, err instanceof Error ? err.message : 'Unauthorized', 401);
+            sendError(ctx.res, -32000, message, 401);
             return null;
         }
     }

package/dist/http/rate-limit.d.ts

@@ -11,3 +11,4 @@ export interface RateLimitManagerImpl {
 }
 export declare function createRateLimitManagerImpl(options: RateLimitConfig): RateLimitManagerImpl;
 export {};
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/http/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../src/http/rate-limit.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,cAAc,EAAY,MAAM,cAAc,CAAC;AAY7D,UAAU,eAAe;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC;IACpC,IAAI,IAAI,IAAI,CAAC;CACd;AA0FD,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,eAAe,GACvB,oBAAoB,CAEtB"}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 #!/usr/bin/env node
 export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/lib/content.d.ts

@@ -1,4 +1,6 @@
 import { type MetadataBlock } from '../transform/types.js';
+export declare function serializeDocumentForMarkdown(document: Document, fallback: string): string;
+export declare function prepareDocumentForMarkdown(document: Document, baseUrl?: string, signal?: AbortSignal): void;
 export declare function removeNoiseFromHtml(html: string, document?: Document, baseUrl?: string, signal?: AbortSignal): string;
 export declare function resolveLanguageFromAttributes(className: string, dataLang: string): string | undefined;
 export declare function detectLanguageFromCode(code: string): string | undefined;
@@ -12,3 +14,4 @@ export declare function addSourceToMarkdown(content: string, url: string): strin
 export declare function isRawTextContent(content: string): boolean;
 export declare function buildMetadataFooter(metadata?: MetadataBlock, fallbackUrl?: string): string;
 export {};
+//# sourceMappingURL=content.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../../src/lib/content.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAghB3D,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,MAAM,GACf,MAAM,CAQR;AAWD,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,WAAW,GACnB,IAAI,CAYN;AACD,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,QAAQ,EACnB,OAAO,CAAC,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,WAAW,GACnB,MAAM,CAcR;AAkVD,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,MAAM,GAAG,SAAS,CAKpB;AACD,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CA6BvE;AA+CD,UAAU,cAAc;IACtB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AA4QD,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,cAAc,GACvB,MAAM,CA6DR;AA2GD,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,GACd,MAAM,GAAG,SAAS,CAOpB;AACD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAmCxE;AAcD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAczD;AAaD,wBAAgB,mBAAmB,CACjC,QAAQ,CAAC,EAAE,aAAa,EACxB,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,CAmBR"}

package/dist/lib/content.js

@@ -445,7 +445,7 @@ function resolveUrls(document, baseUrlStr) {
             processUrlElement(el, 'srcset', base, true);
     }
 }
-function serialize(document, fallback) {
+export function serializeDocumentForMarkdown(document, fallback) {
     const bodyHtml = document.body.innerHTML;
     if (bodyHtml.trim().length > MIN_BODY_CONTENT_LENGTH)
         return bodyHtml;
@@ -463,6 +463,17 @@ function mayContainNoise(html) {
         : `${html.substring(0, NOISE_SCAN_LIMIT)}\n${html.substring(html.length - NOISE_SCAN_LIMIT)}`;
     return NOISE_PATTERNS.some((re) => re.test(sample));
 }
+export function prepareDocumentForMarkdown(document, baseUrl, signal) {
+    const context = getContext();
+    if (config.noiseRemoval.debug) {
+        logDebug('Noise removal audit enabled', {
+            categories: [...(context.flags.navFooter ? ['nav-footer'] : [])],
+        });
+    }
+    stripNoise(document, context, signal);
+    if (baseUrl)
+        resolveUrls(document, baseUrl);
+}
 export function removeNoiseFromHtml(html, document, baseUrl, signal) {
     const shouldParse = isFullDocumentHtml(html) ||
         mayContainNoise(html) ||
@@ -470,17 +481,9 @@ export function removeNoiseFromHtml(html, document, baseUrl, signal) {
     if (!shouldParse)
         return html;
     try {
-        const context = getContext();
-        if (config.noiseRemoval.debug) {
-            logDebug('Noise removal audit enabled', {
-                categories: [...(context.flags.navFooter ? ['nav-footer'] : [])],
-            });
-        }
         const doc = document ?? parseHTML(html).document;
-        stripNoise(doc, context, signal);
-        if (baseUrl)
-            resolveUrls(doc, baseUrl);
-        return serialize(doc, html);
+        prepareDocumentForMarkdown(doc, baseUrl, signal);
+        return serializeDocumentForMarkdown(doc, html);
     }
     catch {
         return html;
@@ -861,6 +864,7 @@ const REGEX = {
     SPACING_CODE_DASH: /(`[^`]+`)\s*\\-\s*/g,
     SPACING_ESCAPES: /\\([[\].])/g,
     SPACING_LIST_NUM_COMBINED: /^((?![-*+] |\d+\. |[ \t]).+)\n((?:[-*+]|\d+\.) )/gm,
+    PUNCT_ONLY_LIST_ARTIFACT: /^(?:[-*+]|\d+\.)\s*(?:\\[-*+|/]|[-*+|/])(?:\s+(?:\\[-*+|/]|[-*+|/]))*\s*$/gm,
     NESTED_LIST_INDENT: /^( +)((?:[-*+])|\d+\.)\s/gm,
     TYPEDOC_COMMENT: /(`+)(?:(?!\1)[\s\S])*?\1|\s?\/\\?\*[\s\S]*?\\?\*\//g,
 };
@@ -1093,6 +1097,7 @@ function applyGlobalRegexes(text, options) {
         .replace(REGEX.SPACING_CODE_DASH, '$1 - ')
         .replace(REGEX.SPACING_ESCAPES, '$1')
         .replace(REGEX.SPACING_LIST_NUM_COMBINED, '$1\n\n$2')
+        .replace(REGEX.PUNCT_ONLY_LIST_ARTIFACT, '')
         .replace(REGEX.DOUBLE_NEWLINE_REDUCER, '\n\n');
     result = normalizeNestedListIndentation(result);
     checkAbort('markdown:cleanup:properties');

package/dist/lib/core.d.ts

@@ -1,6 +1,6 @@
 import { type McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { z } from 'zod';
+import { type CachedPayload } from '../schemas/cache.js';
 export declare const serverVersion: string;
 type LogLevel = 'debug' | 'info' | 'warn' | 'error';
 type TransformWorkerMode = 'threads' | 'process';
@@ -81,6 +81,7 @@ export declare const config: {
         maxTotal: number;
         maxPerOwner: number;
         emitStatusNotifications: boolean;
+        requireInterception: boolean;
     };
     cache: {
         enabled: boolean;
@@ -143,12 +144,6 @@ export declare const config: {
     runtime: RuntimeState;
 };
 export declare function enableHttpMode(): void;
-declare const CachedPayloadSchema: z.ZodObject<{
-    content: z.ZodOptional<z.ZodString>;
-    markdown: z.ZodOptional<z.ZodString>;
-    title: z.ZodOptional<z.ZodString>;
-}, z.core.$strict>;
-type CachedPayload = z.infer<typeof CachedPayloadSchema>;
 interface CacheEntry {
     url: string;
     title?: string;
@@ -204,12 +199,14 @@ export declare function unregisterMcpSessionServerByServer(server: McpServer): v
 export declare function resolveMcpSessionIdByServer(server: McpServer): string | undefined;
 export declare function runWithRequestContext<T>(context: RequestContext, fn: () => T): T;
 export declare function getRequestId(): string | undefined;
+export declare function getSessionId(): string | undefined;
 export declare function getOperationId(): string | undefined;
 export declare function logInfo(message: string, meta?: LogMetadata): void;
 export declare function logDebug(message: string, meta?: LogMetadata): void;
 export declare function logWarn(message: string, meta?: LogMetadata): void;
 export declare function logError(message: string, error?: Error | LogMetadata): void;
-export declare function setLogLevel(level: string): void;
+export declare function getMcpLogLevel(sessionId?: string): LogLevel;
+export declare function setLogLevel(level: string, sessionId?: string): void;
 export declare function redactUrl(rawUrl: string): string;
 export interface SessionEntry {
     readonly server: McpServer;
@@ -253,3 +250,4 @@ export declare function ensureSessionCapacity({ store, maxSessions, evictOldest,
     evictOldest: (store: SessionStore) => boolean;
 }): boolean;
 export {};
+//# sourceMappingURL=core.d.ts.map