@j0hanz/fetch-url-mcp 1.12.0 → 1.12.2

package/dist/http/native.js

@@ -7,10 +7,11 @@ import { hostname } from 'node:os';
 import process from 'node:process';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
-import { composeCloseHandlers, config, createSessionStore, createSlotTracker, enableHttpMode, ensureSessionCapacity, logError, logInfo, registerMcpSessionServer, reserveSessionSlot, runWithRequestContext, startSessionCleanupLoop, } from '../lib/core.js';
+import { composeCloseHandlers, config, createSessionStore, createSlotTracker, enableHttpMode, ensureSessionCapacity, logDebug, logError, logInfo, logWarn, registerMcpSessionOwnerKey, registerMcpSessionServer, reserveSessionSlot, runWithRequestContext, startSessionCleanupLoop, } from '../lib/core.js';
 import { acceptsEventStream, acceptsJsonAndEventStream, isJsonRpcBatchRequest, isMcpMessageBody, isMcpRequestBody, } from '../lib/mcp-interop.js';
 import { applyHttpServerTuning, drainConnectionsOnShutdown, isObject, toError, } from '../lib/utils.js';
 import { createMcpServerForHttpSession } from '../server.js';
+import { buildAuthenticatedOwnerKey } from '../tasks/owner.js';
 import { applyInsufficientScopeAuthHeaders, applyUnauthorizedAuthHeaders, assertHttpModeConfiguration, authService, buildAuthFingerprint, buildProtectedResourceMetadataDocument, corsPolicy, DEFAULT_MCP_PROTOCOL_VERSION, ensureMcpProtocolVersion, hostOriginPolicy, isInsufficientScopeError, isOAuthMetadataEnabled, isProtectedResourceMetadataPath, SUPPORTED_MCP_PROTOCOL_VERSIONS, } from './auth.js';
 import { disableEventLoopMonitoring, isVerboseHealthRequest, resetEventLoopMonitoring, sendHealthRouteResponse, shouldHandleHealthRoute, } from './health.js';
 import { buildRequestContext, createRequestAbortSignal, createTransportAdapter, DEFAULT_BODY_LIMIT_BYTES, drainRequest, findDuplicateSingleValueHeader, getHeaderValue, getMcpSessionId, isJsonBodyError, jsonBodyReader, registerInboundBlockList, sendEmpty, sendError, sendJson, } from './helpers.js';
@@ -28,10 +29,9 @@ function resolveRequestedProtocolVersion(body) {
     const normalized = value.trim();
     if (normalized.length === 0)
         return DEFAULT_MCP_PROTOCOL_VERSION;
-    if (!SUPPORTED_MCP_PROTOCOL_VERSIONS.has(normalized)) {
-        return null;
-    }
-    return normalized;
+    return SUPPORTED_MCP_PROTOCOL_VERSIONS.has(normalized)
+        ? normalized
+        : DEFAULT_MCP_PROTOCOL_VERSION;
 }
 function resolveProtocolVersionHeader(req) {
     const header = getHeaderValue(req, 'mcp-protocol-version');
@@ -49,6 +49,36 @@ function isPingRequest(method) {
 function isMcpRoute(pathname) {
     return pathname === '/mcp' || pathname === '/mcp/';
 }
+function logGatewayRejection(params) {
+    const { message, details, rpcId, ...rest } = params;
+    logWarn(message, {
+        ...rest,
+        ...(rpcId === null || rpcId === undefined ? {} : { rpcId }),
+        ...(details ?? {}),
+    }, 'http');
+}
+function resolveRequestPath(req) {
+    return URL.parse(req.url ?? '', 'http://localhost')?.pathname ?? '/';
+}
+function logRequestCompletion(params) {
+    const meta = {
+        method: params.method,
+        path: params.path,
+        statusCode: params.statusCode,
+        durationMs: Math.round(params.durationMs),
+        requestId: params.requestId,
+        ...(params.sessionId ? { sessionId: params.sessionId } : {}),
+    };
+    if (params.statusCode >= 500) {
+        logError('HTTP request completed with server error', meta, 'http');
+        return;
+    }
+    if (params.statusCode >= 400) {
+        logWarn('HTTP request completed with client error', meta, 'http');
+        return;
+    }
+    logDebug('HTTP request completed', meta, 'http');
+}
 function createSessionTeardownOptions(mode, context) {
     switch (mode) {
         case 'ended':
@@ -71,6 +101,14 @@ function createSessionTeardownOptions(mode, context) {
                 unregisterByServer: true,
                 awaitClose: true,
             };
+        case 'init-timeout':
+            return {
+                cancelMessage: 'The task was cancelled because the MCP session did not finish initialization.',
+                closeTransportReason: 'session-init-timeout',
+                closeServerReason: 'session-init-timeout',
+                unregisterByServer: true,
+                awaitClose: true,
+            };
     }
 }
 class McpSessionGateway {
@@ -94,11 +132,11 @@ class McpSessionGateway {
             sendEmpty(ctx.res, 202);
             return;
         }
-        logInfo('[MCP POST]', {
+        logDebug('MCP POST received', {
             method: method ?? 'response',
-            id: body.id,
+            rpcId: body.id,
             sessionId,
-        });
+        }, 'http');
         const transport = await this.getOrCreateTransport(ctx, requestId);
         if (!transport)
             return;
@@ -113,11 +151,20 @@ class McpSessionGateway {
         const { sessionId, session } = sessionState;
         const acceptHeader = getHeaderValue(ctx.req, 'accept');
         if (!acceptsEventStream(acceptHeader)) {
+            logGatewayRejection({
+                message: 'Rejected MCP GET request',
+                method: ctx.method,
+                path: ctx.url.pathname,
+                reason: 'accept_missing_event_stream',
+                status: 406,
+                sessionId,
+            });
             sendJson(ctx.res, 406, {
-                error: 'Not Acceptable: expected text/event-stream',
+                error: 'We need you to use "text/event-stream" for this connection.',
             });
             return;
         }
+        logDebug('MCP GET received', { sessionId }, 'http');
         this.store.touch(sessionId);
         await session.transport.handleRequest(ctx.req, ctx.res);
     }
@@ -129,23 +176,47 @@ class McpSessionGateway {
             return;
         const { sessionId, session } = sessionState;
         await session.transport.close();
-        this.cleanupSessionRecord(sessionId, 'session-delete');
+        logDebug('MCP DELETE received', { sessionId }, 'http');
+        this.cleanupSessionRecord(sessionId, createSessionTeardownOptions('ended', 'session-delete'));
         sendJson(ctx.res, 200, { status: 'closed' });
     }
     validatePostRequest(ctx) {
         if (!acceptsJsonAndEventStream(getHeaderValue(ctx.req, 'accept'))) {
+            logGatewayRejection({
+                message: 'Rejected MCP POST request',
+                method: ctx.method,
+                path: ctx.url.pathname,
+                reason: 'accept_missing_json_or_event_stream',
+                status: 406,
+            });
             sendJson(ctx.res, 406, {
-                error: 'Not Acceptable: expected application/json and text/event-stream',
+                error: 'We need the request to accept both "application/json" and "text/event-stream".',
             });
             return null;
         }
         const { body } = ctx;
         if (isJsonRpcBatchRequest(body)) {
-            sendError(ctx.res, -32600, 'Batch requests not supported');
+            logGatewayRejection({
+                message: 'Rejected MCP POST request',
+                method: ctx.method,
+                path: ctx.url.pathname,
+                reason: 'batch_request_not_supported',
+                status: 400,
+                mcpCode: -32600,
+            });
+            sendError(ctx.res, -32600, "We don't support batch requests yet. Please send one request at a time.");
             return null;
         }
         if (!isMcpMessageBody(body)) {
-            sendError(ctx.res, -32600, 'Invalid request body');
+            logGatewayRejection({
+                message: 'Rejected MCP POST request',
+                method: ctx.method,
+                path: ctx.url.pathname,
+                reason: 'invalid_request_body',
+                status: 400,
+                mcpCode: -32600,
+            });
+            sendError(ctx.res, -32600, "The request body isn't quite right. Please check the format and try again.");
             return null;
         }
         return body;
@@ -156,7 +227,16 @@ class McpSessionGateway {
         const isInitializedMethod = method !== null && isInitializedNotification(method);
         const isInitNotification = isInitializedMethod && body.id === undefined;
         if (isInitializedMethod && !isInitNotification) {
-            sendError(ctx.res, -32600, 'notifications/initialized must be sent as a notification', 400, requestId);
+            logGatewayRejection({
+                message: 'Rejected MCP POST request',
+                method: ctx.method,
+                path: ctx.url.pathname,
+                reason: 'initialized_request_must_be_notification',
+                status: 400,
+                mcpCode: -32600,
+                rpcId: requestId,
+            });
+            sendError(ctx.res, -32600, "The 'notifications/initialized' message must be sent as a notification, without an ID.", 400, requestId);
             return null;
         }
         const sessionState = this.getOptionalAuthenticatedSession(ctx, requestId);
@@ -187,10 +267,19 @@ class McpSessionGateway {
             return false;
         if (!session) {
             if (isInitNotification) {
-                sendError(ctx.res, -32600, 'Missing session ID', 400, requestId);
+                logGatewayRejection({
+                    message: 'Rejected MCP POST request',
+                    method: ctx.method,
+                    path: ctx.url.pathname,
+                    reason: 'missing_session_id_for_initialized_notification',
+                    status: 400,
+                    mcpCode: -32600,
+                    rpcId: requestId,
+                });
+                sendError(ctx.res, -32600, "We couldn't find a session ID for your request. Please ensure you have an active session.", 400, requestId);
                 return false;
             }
-            return ensureMcpProtocolVersion(ctx.req, ctx.res);
+            return true;
         }
         if (!this.ensureSessionProtocolVersion(ctx, session))
             return false;
@@ -200,7 +289,17 @@ class McpSessionGateway {
             return true;
         if (method !== null && isPingRequest(method))
             return true;
-        sendError(ctx.res, -32600, 'Session not initialized', 400, requestId);
+        logGatewayRejection({
+            message: 'Rejected MCP request',
+            method: ctx.method,
+            path: ctx.url.pathname,
+            reason: 'session_not_initialized',
+            status: 400,
+            mcpCode: -32600,
+            sessionId,
+            rpcId: requestId,
+        });
+        sendError(ctx.res, -32600, "Your session hasn't been initialized yet. Please wait a moment and try again.", 400, requestId);
         return false;
     }
     async getOrCreateTransport(ctx, requestId) {
@@ -216,24 +315,54 @@ class McpSessionGateway {
     }
     getInitializeProtocolVersion(ctx, requestId) {
         if (!isMcpRequestBody(ctx.body)) {
-            sendError(ctx.res, -32600, 'Missing session ID', 400, requestId);
+            logGatewayRejection({
+                message: 'Rejected MCP initialize request',
+                method: ctx.method,
+                path: ctx.url.pathname,
+                reason: 'missing_session_id',
+                status: 400,
+                mcpCode: -32600,
+                rpcId: requestId,
+            });
+            sendError(ctx.res, -32600, "We couldn't find a session ID for your request. Please ensure you have an active session.", 400, requestId);
             return null;
         }
         if (!isInitializeRequest(ctx.body)) {
-            sendError(ctx.res, ctx.body.method === 'initialize' ? -32602 : -32600, ctx.body.method === 'initialize'
-                ? 'Invalid initialize request'
-                : 'Missing session ID', 400, requestId);
+            const invalidInitialize = ctx.body.method === 'initialize';
+            logGatewayRejection({
+                message: 'Rejected MCP initialize request',
+                method: ctx.method,
+                path: ctx.url.pathname,
+                reason: invalidInitialize
+                    ? 'invalid_initialize_request'
+                    : 'missing_session_id',
+                status: 400,
+                mcpCode: invalidInitialize ? -32602 : -32600,
+                rpcId: requestId,
+            });
+            sendError(ctx.res, invalidInitialize ? -32602 : -32600, invalidInitialize
+                ? 'The initialize request format is invalid. Please double-check your parameters.'
+                : "We couldn't find a session ID for your request. Please ensure you have an active session.", 400, requestId);
             return null;
         }
         const negotiatedProtocolVersion = resolveRequestedProtocolVersion(ctx.body);
-        if (!negotiatedProtocolVersion) {
-            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);
+            logGatewayRejection({
+                message: 'Rejected MCP initialize request',
+                method: ctx.method,
+                path: ctx.url.pathname,
+                reason: 'protocol_version_mismatch',
+                status: 400,
+                mcpCode: -32600,
+                rpcId: requestId,
+                details: {
+                    headerProtocolVersion,
+                    negotiatedProtocolVersion,
+                },
+            });
+            sendError(ctx.res, -32600, `There's a mismatch in the protocol version. The header says '${headerProtocolVersion}' but the body says '${negotiatedProtocolVersion}'.`, 400, requestId);
             return null;
         }
         return negotiatedProtocolVersion;
@@ -261,13 +390,13 @@ class McpSessionGateway {
             return null;
         const { sessionId, session } = state;
         if (!sessionId || !session) {
-            sendError(ctx.res, -32600, 'Missing session ID', 400, requestId);
+            sendError(ctx.res, -32600, "We couldn't find a session ID for your request. Please ensure you have an active session.", 400, requestId);
             return null;
         }
         if (!this.ensureSessionProtocolVersion(ctx, session))
             return null;
         if (options?.requireInitialized && !session.protocolInitialized) {
-            sendError(ctx.res, -32600, 'Session not initialized', 400, requestId);
+            sendError(ctx.res, -32600, "Your session hasn't been initialized yet. Please wait a moment and try again.", 400, requestId);
             return null;
         }
         return { sessionId, session };
@@ -275,11 +404,29 @@ class McpSessionGateway {
     getAuthenticatedSessionById(sessionId, authFingerprint, res, requestId = null) {
         const session = this.store.get(sessionId);
         if (!session) {
-            sendError(res, -32600, 'Session not found', 404, requestId);
+            logGatewayRejection({
+                message: 'Rejected MCP session request',
+                path: '/mcp',
+                reason: 'session_not_found',
+                status: 404,
+                mcpCode: -32600,
+                sessionId,
+                rpcId: requestId,
+            });
+            sendError(res, -32600, "We couldn't find your session. It might have expired or been closed.", 404, requestId);
             return null;
         }
         if (!authFingerprint || session.authFingerprint !== authFingerprint) {
-            sendError(res, -32600, 'Session not found', 404, requestId);
+            logGatewayRejection({
+                message: 'Rejected MCP session request',
+                path: '/mcp',
+                reason: 'session_auth_mismatch',
+                status: 404,
+                mcpCode: -32600,
+                sessionId,
+                rpcId: requestId,
+            });
+            sendError(res, -32600, "We couldn't find your session. It might have expired or been closed.", 404, requestId);
             return null;
         }
         return session;
@@ -296,6 +443,7 @@ class McpSessionGateway {
         this.clearSessionInitTimeout(sessionId);
         if (sessionId)
             this.store.touch(sessionId);
+        logDebug('Session initialized', { sessionId }, 'session');
     }
     createSessionInitTimeout(sessionId, tracker, unpublishedSession) {
         const initTimeout = setTimeout(() => {
@@ -305,9 +453,11 @@ class McpSessionGateway {
                     this.clearSessionInitTimeout(sessionId);
                     return;
                 }
-                this.cleanupSessionRecord(sessionId, 'session-init-timeout');
+                logWarn('Session init timeout', { sessionId }, 'session');
+                this.cleanupSessionRecord(sessionId, createSessionTeardownOptions('init-timeout'));
                 return;
             }
+            logWarn('Session init timeout before registration completed', { sessionId }, 'session');
             tracker.releaseSlot();
             void teardownUnregisteredSessionResources(unpublishedSession, 'session-init-timeout');
         }, config.server.sessionInitTimeoutMs);
@@ -327,6 +477,10 @@ class McpSessionGateway {
             await sessionServer.connect(transport);
         }
         catch (err) {
+            logWarn('Session transport connect failed', {
+                sessionId,
+                error: toError(err).message,
+            }, 'session');
             clearTimeout(initTimeout);
             tracker.releaseSlot();
             void teardownUnregisteredSessionResources(unpublishedSession, 'session-connect-failed');
@@ -337,7 +491,20 @@ class McpSessionGateway {
     async createNewSession(ctx, requestId, negotiatedProtocolVersion) {
         const authFingerprint = buildAuthFingerprint(ctx.auth);
         if (!authFingerprint) {
-            sendError(ctx.res, -32603, 'Missing auth context', 500, requestId);
+            logError('Session creation failed: missing auth context', {
+                path: ctx.url.pathname,
+                method: ctx.method,
+            }, 'session');
+            sendError(ctx.res, -32603, "We're missing some authorization details to process this request.", 500, requestId);
+            return null;
+        }
+        const ownerKey = buildAuthenticatedOwnerKey(ctx.auth);
+        if (!ownerKey) {
+            logError('Session creation failed: missing task owner context', {
+                path: ctx.url.pathname,
+                method: ctx.method,
+            }, 'session');
+            sendError(ctx.res, -32603, "We're missing the owner information needed to authorize this request.", 500, requestId);
             return null;
         }
         if (!this.reserveCapacity(ctx.res, requestId))
@@ -349,6 +516,7 @@ class McpSessionGateway {
             sessionServer = await this.createSessionServer();
         }
         catch (error) {
+            logError('Session server creation failed', { sessionId: newSessionId, error: toError(error).message }, 'session');
             tracker.releaseSlot();
             throw error;
         }
@@ -363,6 +531,7 @@ class McpSessionGateway {
         const isConnected = await this.connectTransport(sessionServer, transportImpl, initTimeout, tracker, unpublishedSession, newSessionId);
         tracker.releaseSlot();
         if (!isConnected) {
+            logWarn('Session closed before registration completed', { sessionId: newSessionId }, 'session');
             void teardownUnregisteredSessionResources(unpublishedSession, 'session-closed-during-connect');
             return null;
         }
@@ -376,18 +545,24 @@ class McpSessionGateway {
             authFingerprint,
         });
         this.sessionInitTimeouts.set(newSessionId, initTimeout);
+        registerMcpSessionOwnerKey(newSessionId, ownerKey);
         registerMcpSessionServer(newSessionId, sessionServer);
+        logInfo('Session created', { sessionId: newSessionId, negotiatedProtocolVersion }, 'session');
         transportImpl.onclose = composeCloseHandlers(transportImpl.onclose, () => {
-            this.cleanupSessionRecord(newSessionId, 'session-close');
+            this.cleanupSessionRecord(newSessionId, createSessionTeardownOptions('ended', 'session-close'));
         });
         return transportImpl;
     }
-    cleanupSessionRecord(sessionId, context) {
+    cleanupSessionRecord(sessionId, teardownOptions) {
+        const context = teardownOptions.closeTransportReason ??
+            teardownOptions.closeServerReason ??
+            'session';
+        logDebug('Session cleanup', { sessionId, context }, 'session');
         this.clearSessionInitTimeout(sessionId);
         const session = this.store.remove(sessionId);
         if (!session)
             return;
-        void teardownSessionResources(session, createSessionTeardownOptions('ended', context));
+        void teardownSessionResources(session, teardownOptions);
     }
     clearSessionInitTimeout(sessionId) {
         if (!sessionId)
@@ -412,12 +587,14 @@ class McpSessionGateway {
             },
         });
         if (!allowed) {
-            sendError(res, -32000, 'Server busy', 503, requestId);
+            logWarn('Session capacity exhausted', { maxSessions: config.server.maxSessions }, 'session');
+            sendError(res, -32000, 'The server is currently too busy to handle your request. Please try again in a little while.', 503, requestId);
             return false;
         }
         // Double-check: capacity may have changed during the async eviction window above.
         if (!reserveSessionSlot(this.store, config.server.maxSessions)) {
-            sendError(res, -32000, 'Server busy', 503, requestId);
+            logWarn('Session capacity exhausted (post-eviction)', { maxSessions: config.server.maxSessions }, 'session');
+            sendError(res, -32000, 'The server is currently too busy to handle your request. Please try again in a little while.', 503, requestId);
             return false;
         }
         return true;
@@ -472,14 +649,23 @@ class HttpDispatcher {
                 const handled = await this.handleMcpRoutes(authCtx);
                 if (handled)
                     return;
+                ctx.res.setHeader('Allow', 'DELETE, GET, OPTIONS, POST');
+                sendJson(ctx.res, 405, {
+                    error: "Looks like you tried to use a method that isn't allowed here.",
+                });
+                return;
             }
-            sendJson(ctx.res, 404, { error: 'Not Found' });
+            sendJson(ctx.res, 404, {
+                error: "We couldn't find what you were looking for.",
+            });
         }
         catch (err) {
             const error = toError(err);
-            logError('Request failed', error);
+            logError('Request failed', error, 'http');
             if (!ctx.res.writableEnded) {
-                sendJson(ctx.res, 500, { error: 'Internal Server Error' });
+                sendJson(ctx.res, 500, {
+                    error: "Something went wrong on our end. We're looking into it!",
+                });
             }
         }
     }
@@ -504,6 +690,7 @@ class HttpDispatcher {
         }
         catch (err) {
             const message = err instanceof Error ? err.message : 'Unauthorized';
+            logWarn('Authentication failed', { message, method: ctx.method, path: ctx.url.pathname }, 'auth');
             if (isInsufficientScopeError(err)) {
                 applyInsufficientScopeAuthHeaders(ctx.req, ctx.res, err.requiredScopes, message);
                 sendError(ctx.res, -32000, message, 403);
@@ -521,21 +708,21 @@ class HttpDispatcher {
 const DEFAULT_BODY_ERROR = {
     statusCode: 400,
     mcpCode: -32700,
-    mcpMsg: 'Parse error',
-    restMsg: 'Invalid JSON',
+    mcpMsg: "We couldn't parse the request body. Please ensure it's valid JSON.",
+    restMsg: "The request body doesn't seem to be valid JSON. Please check and try again.",
 };
 const BODY_PARSE_ERRORS = {
     'payload-too-large': {
         statusCode: 413,
         mcpCode: -32600,
-        mcpMsg: 'Request body too large',
-        restMsg: 'Payload too large',
+        mcpMsg: 'The request body is too large. Please send a smaller payload.',
+        restMsg: 'That request is a bit too big for us to handle right now.',
     },
     'read-failed': {
         statusCode: 400,
         mcpCode: -32600,
-        mcpMsg: 'Request body read failed',
-        restMsg: 'Invalid JSON',
+        mcpMsg: 'We ran into an issue reading the request. Please try sending it again.',
+        restMsg: "The request body doesn't seem to be valid JSON. Please check and try again.",
     },
     default: DEFAULT_BODY_ERROR,
 };
@@ -562,6 +749,18 @@ class HttpRequestPipeline {
         const requestId = getHeaderValue(rawReq, 'x-request-id') ?? randomUUID();
         const sessionId = getMcpSessionId(rawReq) ?? undefined;
         const { signal, cleanup } = createRequestAbortSignal(rawReq);
+        const path = resolveRequestPath(rawReq);
+        const startTime = performance.now();
+        rawRes.once('finish', () => {
+            logRequestCompletion({
+                path,
+                statusCode: rawRes.statusCode,
+                durationMs: performance.now() - startTime,
+                requestId,
+                ...(rawReq.method ? { method: rawReq.method } : {}),
+                ...(sessionId ? { sessionId } : {}),
+            });
+        });
         try {
             await runWithRequestContext({
                 requestId,
@@ -588,8 +787,16 @@ class HttpRequestPipeline {
         const duplicateHeader = findDuplicateSingleValueHeader(rawReq);
         if (!duplicateHeader)
             return false;
+        logGatewayRejection({
+            message: 'Rejected HTTP request',
+            method: rawReq.method,
+            path: resolveRequestPath(rawReq),
+            reason: 'duplicate_single_value_header',
+            status: 400,
+            details: { header: duplicateHeader },
+        });
         sendJson(rawRes, 400, {
-            error: `Duplicate ${duplicateHeader} header is not allowed`,
+            error: `It seems the '${duplicateHeader}' header was sent multiple times when it should only be sent once.`,
         });
         drainRequest(rawReq);
         return true;
@@ -611,7 +818,9 @@ class HttpRequestPipeline {
             return false;
         }
         if (!this.rateLimiter.check(ctx)) {
-            sendJson(ctx.res, 429, { error: 'Too Many Requests' });
+            sendJson(ctx.res, 429, {
+                error: "You're sending requests a bit too quickly. Please slow down and try again.",
+            });
             drainRequest(rawReq);
             return false;
         }
@@ -628,6 +837,12 @@ class HttpRequestPipeline {
         }
         catch (error) {
             const bodyErrorKind = isJsonBodyError(error) ? error.kind : null;
+            if (bodyErrorKind === 'payload-too-large') {
+                logWarn('The request body is too large. Please send a smaller payload.', { method: ctx.method, path: ctx.url.pathname }, 'http');
+            }
+            else if (bodyErrorKind === 'read-failed' || bodyErrorKind === null) {
+                logError('Request body parsing failed', toError(error), 'http');
+            }
             sendBodyParseError(ctx, bodyErrorKind, rawReq);
             return false;
         }
@@ -648,11 +863,13 @@ class HttpRequestPipeline {
 // Server bootstrap
 // ---------------------------------------------------------------------------
 function handlePipelineError(error, res) {
-    logError('Request pipeline failed', toError(error));
+    logError('Request pipeline failed', toError(error), 'http');
     if (res.writableEnded)
         return;
     if (!res.headersSent) {
-        sendJson(res, 500, { error: 'Internal Server Error' });
+        sendJson(res, 500, {
+            error: "Something went wrong on our end. We're looking into it!",
+        });
         return;
     }
     res.end();
@@ -694,7 +911,7 @@ function resolveListeningPort(server, fallback) {
 function createShutdownHandler(options) {
     const closeBatchSize = 10;
     return async (signal) => {
-        logInfo(`Stopping HTTP server (${signal})...`);
+        logInfo(`Stopping HTTP server (${signal})...`, undefined, 'http');
         options.rateLimiter.stop();
         options.sessionCleanup.abort();
         drainConnectionsOnShutdown(options.server);
@@ -707,7 +924,7 @@ function createShutdownHandler(options) {
             }));
             for (const r of results) {
                 if (r.status === 'rejected') {
-                    logError('Session teardown failed during shutdown', r.reason instanceof Error ? r.reason : undefined);
+                    logError('Session teardown failed during shutdown', r.reason instanceof Error ? r.reason : undefined, 'http');
                 }
             }
         }
@@ -722,7 +939,7 @@ export async function startHttpServer() {
     const sessionStore = createSessionStore(config.server.sessionTtlMs);
     const sessionCleanup = startSessionCleanupLoop(sessionStore, config.server.sessionTtlMs, {
         onEvictSession: (session) => {
-            teardownSessionRegistration(session.server, 'The task was cancelled because the MCP session expired.');
+            teardownSessionRegistration(session.server);
         },
     });
     const mcpGateway = new McpSessionGateway(sessionStore, createMcpServerForHttpSession);
@@ -743,7 +960,7 @@ export async function startHttpServer() {
         arch: process.arch,
         hostname: hostname(),
         nodeVersion: process.version,
-    });
+    }, 'http');
     return {
         port,
         host: config.server.host,

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

@@ -1 +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"}
+{"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;AA2FD,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,eAAe,GACvB,oBAAoB,CAEtB"}

package/dist/http/rate-limit.js

@@ -21,7 +21,7 @@ class RateLimiter {
             },
             onError: (err) => {
                 if (!isAbortError(err)) {
-                    logWarn('Rate limit cleanup failed', { error: err });
+                    logWarn('Rate limit cleanup failed', { error: err }, 'rate-limit');
                 }
             },
         });
@@ -71,6 +71,7 @@ class RateLimiter {
             this.store.set(key, entry);
         }
         if (entry.count > this.options.maxRequests) {
+            logWarn('Rate limit exceeded', { ip: key }, 'rate-limit');
             const retryAfter = Math.max(1, Math.ceil((entry.resetTime - now) / 1000));
             ctx.res.setHeader('Retry-After', String(retryAfter));
             sendJson(ctx.res, 429, { error: 'Rate limit exceeded', retryAfter });