refactor(server): carry the typed message on InboundModernRoute and drop the JSONRPCRequest casts

felixweinberger · felixweinberger · commit 02e5d3bc5991 · 2026-06-18T17:02:03.000Z
InboundModernRoute is now a discriminated union over messageKind that carries
the guard-proved JSONRPCRequest / JSONRPCNotification body. The classifier
already establishes the shape via isJSONRPCRequest / isJSONRPCNotification, so
the body is threaded through on the route instead of being re-cast at every
read site in serveModern. Removes the five 'as JSONRPCRequest' casts and the
'as JSONRPCRequest | JSONRPCNotification' at the call site; serveModern no
longer takes a separate message argument.
diff --git a/packages/core/src/shared/inboundClassification.ts b/packages/core/src/shared/inboundClassification.ts
@@ -67,7 +67,7 @@ import { PROTOCOL_VERSION_META_KEY } from '../types/constants.js';
 import { ProtocolErrorCode } from '../types/enums.js';
 import { ProtocolError, UnsupportedProtocolVersionError } from '../types/errors.js';
 import { isJSONRPCErrorResponse, isJSONRPCNotification, isJSONRPCRequest, isJSONRPCResultResponse } from '../types/guards.js';
-import type { MessageClassification } from '../types/types.js';
+import type { JSONRPCNotification, JSONRPCRequest, MessageClassification } from '../types/types.js';
 import { envelopeClaimVersion, hasEnvelopeClaim, requestMetaOf, validateEnvelopeMeta } from './envelope.js';
 import { isModernProtocolVersion } from './protocolEras.js';
 
@@ -126,17 +126,32 @@ export interface InboundLegacyRoute {
     requestedVersion?: string;
 }
 
-/** The request claims the per-request envelope mechanism and is served on the modern path. */
-export interface InboundModernRoute {
-    kind: 'modern';
-    /** Whether the classified message is a request or a notification. */
-    messageKind: 'request' | 'notification';
-    /**
-     * The classification handed to the per-request transport and validated by
-     * the protocol layer against the serving instance's negotiated era.
-     */
-    classification: MessageClassification;
-}
+/**
+ * The request claims the per-request envelope mechanism and is served on the
+ * modern path. Discriminated by `messageKind` so the typed `message` narrows
+ * with it — the classifier has already proved the JSON-RPC shape via the
+ * `isJSONRPCRequest` / `isJSONRPCNotification` guards, so consumers never
+ * cast the body again.
+ */
+export type InboundModernRoute =
+    | {
+          kind: 'modern';
+          messageKind: 'request';
+          /** The classified body — guard-proved {@linkcode JSONRPCRequest} shape. */
+          message: JSONRPCRequest;
+          /**
+           * The classification handed to the per-request transport and validated by
+           * the protocol layer against the serving instance's negotiated era.
+           */
+          classification: MessageClassification;
+      }
+    | {
+          kind: 'modern';
+          messageKind: 'notification';
+          /** The classified body — guard-proved {@linkcode JSONRPCNotification} shape. */
+          message: JSONRPCNotification;
+          classification: MessageClassification;
+      };
 
 /** The named steps of the inbound validation ladder, in evaluation order. */
 export type InboundValidationRung =
@@ -461,9 +476,9 @@ function classifyBatch(body: readonly unknown[]): InboundClassificationOutcome {
     return { kind: 'legacy', reason: 'batch' };
 }
 
-function classifyRequestBody(request: InboundHttpRequest, body: Record<string, unknown>): InboundClassificationOutcome {
-    const params = body['params'];
-    const method = body['method'] as string;
+function classifyRequestBody(request: InboundHttpRequest, body: JSONRPCRequest): InboundClassificationOutcome {
+    const params = body.params;
+    const method = body.method;
     const headerVersion = request.protocolVersionHeader;
     const headerNamesModern = headerVersion !== undefined && isModernProtocolVersion(headerVersion);
 
@@ -523,7 +538,7 @@ function classifyRequestBody(request: InboundHttpRequest, body: Record<string, u
                 `the body names method ${method} but the Mcp-Method header names ${request.mcpMethodHeader}`
             );
         }
-        return { kind: 'modern', messageKind: 'request', classification: classificationForClaim(claimedVersion) };
+        return { kind: 'modern', messageKind: 'request', message: body, classification: classificationForClaim(claimedVersion) };
     }
 
     // No claim: legacy-era traffic — unless the protocol-version header names a
@@ -554,9 +569,9 @@ function classifyRequestBody(request: InboundHttpRequest, body: Record<string, u
     return { kind: 'legacy', reason: 'no-claim', ...(headerVersion !== undefined && { requestedVersion: headerVersion }) };
 }
 
-function classifyNotificationBody(request: InboundHttpRequest, body: Record<string, unknown>): InboundClassificationOutcome {
-    const params = body['params'];
-    const method = body['method'] as string;
+function classifyNotificationBody(request: InboundHttpRequest, body: JSONRPCNotification): InboundClassificationOutcome {
+    const params = body.params;
+    const method = body.method;
     const headerVersion = request.protocolVersionHeader;
     const headerNamesModern = headerVersion !== undefined && isModernProtocolVersion(headerVersion);
 
@@ -603,7 +618,7 @@ function classifyNotificationBody(request: InboundHttpRequest, body: Record<stri
                 `the notification body names method ${method} but the Mcp-Method header names ${request.mcpMethodHeader}`
             );
         }
-        return { kind: 'modern', messageKind: 'notification', classification };
+        return { kind: 'modern', messageKind: 'notification', message: body, classification };
     }
 
     // Notifications carry no body claim under the current spec, so the
@@ -623,6 +638,7 @@ function classifyNotificationBody(request: InboundHttpRequest, body: Record<stri
         return {
             kind: 'modern',
             messageKind: 'notification',
+            message: body,
             classification: { era: 'modern', revision: headerVersion }
         };
     }
diff --git a/packages/server/src/server/createMcpHandler.ts b/packages/server/src/server/createMcpHandler.ts
@@ -34,8 +34,6 @@ import type {
     InboundLadderRejection,
     InboundLegacyRoute,
     InboundModernRoute,
-    JSONRPCNotification,
-    JSONRPCRequest,
     RequestId
 } from '@modelcontextprotocol/core';
 import {
@@ -630,12 +628,7 @@ export function createMcpHandler(factory: McpServerFactory, options: CreateMcpHa
     // to turn legacy serving off (modern-only strict).
     const legacyHandler: LegacyHttpHandler | undefined = legacy === 'reject' ? undefined : legacyStatelessFallback(factory, reportError);
 
-    async function serveModern(
-        route: InboundModernRoute,
-        message: JSONRPCRequest | JSONRPCNotification,
-        request: Request,
-        authInfo: AuthInfo | undefined
-    ): Promise<Response> {
+    async function serveModern(route: InboundModernRoute, request: Request, authInfo: AuthInfo | undefined): Promise<Response> {
         const claimedRevision = route.classification.revision;
         if (claimedRevision === undefined || !SUPPORTED_MODERN_PROTOCOL_VERSIONS.includes(claimedRevision)) {
             // The claim names a revision this endpoint does not serve (an
@@ -646,10 +639,10 @@ export function createMcpHandler(factory: McpServerFactory, options: CreateMcpHa
                 requested: claimedRevision ?? 'unknown'
             });
             reportError(error);
-            return jsonRpcErrorResponse(400, error.code, error.message, error.data, echoableRequestId(message));
+            return jsonRpcErrorResponse(400, error.code, error.message, error.data, echoableRequestId(route.message));
         }
 
-        const meta = route.messageKind === 'request' ? requestMetaOf((message as JSONRPCRequest).params) : undefined;
+        const meta = route.messageKind === 'request' ? requestMetaOf(route.message.params) : undefined;
         const declaredClientCapabilities = meta?.[CLIENT_CAPABILITIES_META_KEY] as ClientCapabilities | undefined;
 
         // Pre-dispatch capability gate: a request to a method whose processing
@@ -659,7 +652,7 @@ export function createMcpHandler(factory: McpServerFactory, options: CreateMcpHa
         // spec-mandated HTTP 400 for this error; a handler-time emission would
         // surface in-band on HTTP 200.
         if (route.messageKind === 'request') {
-            const required = requiredClientCapabilitiesForRequest((message as JSONRPCRequest).method);
+            const required = requiredClientCapabilitiesForRequest(route.message.method);
             if (required !== undefined) {
                 const missing = missingClientCapabilities(required, declaredClientCapabilities);
                 if (missing !== undefined) {
@@ -670,7 +663,7 @@ export function createMcpHandler(factory: McpServerFactory, options: CreateMcpHa
                         error.code,
                         error.message,
                         error.data,
-                        (message as JSONRPCRequest).id
+                        route.message.id
                     );
                 }
             }
@@ -692,8 +685,8 @@ export function createMcpHandler(factory: McpServerFactory, options: CreateMcpHa
         // Authorization the consumer performs inside the factory therefore DOES
         // see listen requests, although token verification still belongs at the
         // middleware layer mounted in front of this entry.
-        if (route.messageKind === 'request' && (message as JSONRPCRequest).method === 'subscriptions/listen') {
-            return listenRouter.serve(message as JSONRPCRequest, request.signal, server.getCapabilities());
+        if (route.messageKind === 'request' && route.message.method === 'subscriptions/listen') {
+            return listenRouter.serve(route.message, request.signal, server.getCapabilities());
         }
 
         // Era-write at instance binding, then modern-only handler installation —
@@ -717,7 +710,7 @@ export function createMcpHandler(factory: McpServerFactory, options: CreateMcpHa
         };
 
         try {
-            const response = await invoke(product, message, {
+            const response = await invoke(product, route.message, {
                 classification: route.classification,
                 request,
                 ...(authInfo !== undefined && { authInfo }),
@@ -742,7 +735,7 @@ export function createMcpHandler(factory: McpServerFactory, options: CreateMcpHa
             await server.close().catch(() => {});
             inflight.delete(server);
             reportError(toError(error));
-            return internalServerErrorResponse(echoableRequestId(message));
+            return internalServerErrorResponse(echoableRequestId(route.message));
         }
     }
 
@@ -794,7 +787,7 @@ export function createMcpHandler(factory: McpServerFactory, options: CreateMcpHa
                     return rejectionResponse(outcome, echoableRequestId(body));
                 }
                 case 'modern': {
-                    return await serveModern(outcome, body as JSONRPCRequest | JSONRPCNotification, request, authInfo);
+                    return await serveModern(outcome, request, authInfo);
                 }
                 case 'legacy': {
                     return await serveLegacyRoute(outcome, forwardRequest, authInfo, parsedBody);
