test(core): enforce transport exact optional compatibility

Author: rechedev9

.changeset/fix-transport-exact-optional-property-types.md

@@ -4,6 +4,6 @@
 
 Add explicit `| undefined` to optional properties on the `Transport` interface and `TransportSendOptions` (`onclose`, `onerror`, `onmessage`, `sessionId`, `setProtocolVersion`, `setSupportedProtocolVersions`, `onresumptiontoken`).
 
-This fixes TS2420 errors for consumers using `exactOptionalPropertyTypes: true` without `skipLibCheck`, where the emitted `.d.ts` for implementing classes included `| undefined` but the interface did not.
+This fixes TS2420 errors for consumers using `exactOptionalPropertyTypes: true` without `skipLibCheck`, where the emitted `.d.ts` for implementing classes included `| undefined` but the interface did not. The package typecheck now also compiles a dedicated Transport compatibility test with `exactOptionalPropertyTypes: true`, so this stays enforced.
 
 Workaround for older SDK versions: enable `skipLibCheck: true` in your tsconfig.

packages/core/package.json

@@ -35,7 +35,7 @@
         }
     },
     "scripts": {
-        "typecheck": "tsgo -p tsconfig.json --noEmit",
+        "typecheck": "tsgo -p tsconfig.json --noEmit && tsgo -p tsconfig.exact-optional.json --noEmit",
         "lint": "eslint src/ && prettier --ignore-path ../../.prettierignore --check .",
         "lint:fix": "eslint src/ --fix && prettier --ignore-path ../../.prettierignore --write .",
         "check": "pnpm run typecheck && pnpm run lint",

packages/core/src/shared/transport.ts

@@ -37,10 +37,14 @@ export function createFetchWithInit(baseFetch: FetchLike = fetch, baseInit?: Req
     return async (url: string | URL, init?: RequestInit): Promise<Response> => {
         const mergedInit: RequestInit = {
             ...baseInit,
-            ...init,
-            // Headers need special handling - merge instead of replace
-            headers: init?.headers ? { ...normalizeHeaders(baseInit.headers), ...normalizeHeaders(init.headers) } : baseInit.headers
+            ...init
         };
+
+        // Headers need special handling - merge instead of replace
+        if (init?.headers) {
+            mergedInit.headers = { ...normalizeHeaders(baseInit.headers), ...normalizeHeaders(init.headers) };
+        }
+
         return baseFetch(url, mergedInit);
     };
 }

packages/core/test/shared/transport.types.test.ts

@@ -0,0 +1,37 @@
+/**
+ * Compile-time type checks for the Transport interface.
+ *
+ * Verifies that a class declaring optional Transport properties as `T | undefined`
+ * (the pattern required by `exactOptionalPropertyTypes: true`) is assignable to
+ * Transport without TS2420 errors when compiled with the dedicated
+ * exact-optional typecheck config.
+ *
+ * See: https://github.com/modelcontextprotocol/typescript-sdk/issues/1314
+ */
+import { test } from 'vitest';
+
+import type { Transport } from '../../src/shared/transport.js';
+import type { JSONRPCMessage, MessageExtraInfo } from '../../src/types/index.js';
+
+// A concrete class that uses the explicit `| undefined` union form for optional Transport members.
+// With the old Transport interface (no `| undefined` on these members), this class would produce
+// TS2420 under `exactOptionalPropertyTypes: true` when compiled by tsconfig.exact-optional.json.
+class ExplicitUndefinedTransport implements Transport {
+    sessionId?: string | undefined;
+    onclose?: (() => void) | undefined;
+    onerror?: ((error: Error) => void) | undefined;
+    onmessage?: (<T extends JSONRPCMessage>(message: T, extra?: MessageExtraInfo) => void) | undefined;
+    setProtocolVersion?: ((version: string) => void) | undefined;
+    setSupportedProtocolVersions?: ((versions: string[]) => void) | undefined;
+
+    async start(): Promise<void> {}
+    async close(): Promise<void> {}
+    async send(_message: JSONRPCMessage): Promise<void> {}
+}
+
+test('Transport allows explicit | undefined on optional members', () => {
+    const transport: Transport = new ExplicitUndefinedTransport();
+    // The mere fact this file compiles is the assertion.
+    // We also verify runtime assignability here.
+    expect(transport).toBeDefined();
+});

packages/core/tsconfig.exact-optional.json

@@ -0,0 +1,7 @@
+{
+    "extends": "./tsconfig.json",
+    "include": ["src/shared/transport.ts", "src/types/index.ts", "test/shared/transport.types.test.ts"],
+    "compilerOptions": {
+        "exactOptionalPropertyTypes": true
+    }
+}