Repository navigation
normalizeHeaders references the bare global HeadersInit, breaking Node-only consumers with skipLibCheck: false #2568
Description
Summary
shared/transport.d.ts references the bare global HeadersInit, which is a DOM lib type. Node-only consumers compiling with "skipLibCheck": false and no "DOM" in lib fail to build.
File/line: dist/esm/shared/transport.d.ts:7
export declare function normalizeHeaders(headers: HeadersInit | undefined): Record<string, string>;Reproduction
@modelcontextprotocol/sdk@1.30.0 + @types/node@22.20.1, with "lib": ["ES2023"], "types": ["node"], "skipLibCheck": false:
node_modules/@modelcontextprotocol/sdk/dist/esm/shared/transport.d.ts(7,51):
error TS2304: Cannot find name 'HeadersInit'.
Affects every published 1.x from 1.23.0-beta.0 through 1.30.0 (current latest).
Why @types/node cannot fix this
@types/node@22's fetch-globals shim (node_modules/@types/node/web-globals/fetch.d.ts) binds Headers, Request, RequestInit, Response and ResponseInit globally from undici-types — but deliberately not HeadersInit.
Per the review thread on DefinitelyTyped PR #74414 (@Renegade334): HeadersInit is a web-IDL typedef, which maps to a TypeScript type alias, and type aliases cannot be declaration-merged — unlike the dictionary/interface-shaped Headers/Request/RequestInit/Response, which can. So @types/node structurally cannot bind this global the way it binds the others.
That leaves the fix on the SDK side: don't reference the bare global.
Suggested fix
Change the signature to avoid the DOM-only global:
export declare function normalizeHeaders(headers: RequestInit['headers'] | undefined): Record<string, string>;This is same-behaviour and depends only on a global @types/node does bind. It's also exactly what the v2 rewrite already does (#1279).
Blast radius is small: src/shared/transport.ts and its compiled output — 2 files.
Why a 1.x backport matters
The v2 rewrite already fixes this, but v2 is outside the peer range that @anthropic-ai/claude-agent-sdk pins (^1.29.0), so consumers coming through the Agent SDK can't upgrade to it today. Without a 1.x backport, the only options are a local ambient shim, adding "DOM" to lib (which drags every browser global into a Node service), or skipLibCheck: true (which stops type-checking all declaration files).
Happy to open a PR for the one-line change if that's useful.
Activity
DiadkoShmek commentedon Jul 31, 2026
Confirmed on current
v1.xat2d889f2using a packed SDK artifact and a clean Node-only consumer (lib: ["ES2023"],types: ["node"],skipLibCheck: false).The baseline fails with the reported
TS2304: Cannot find name 'HeadersInit'. Changing the source signature toRequestInit['headers'] | undefinedmakes the same packed-artifact consumer compile successfully.I also ran:
npm run buildnpm run checkThe diff is one source line and does not change runtime behavior. I have the independently reviewed local commit ready and can open a focused PR against
v1.xif maintainers want this backport.fix(shared): stop referencing the DOM-only global HeadersInit in norm…
ziadantar90 commentedon Oct 22, 2026
Hi, I'd like to take this one. The fix looks like changing the
normalizeHeadersparameter toRequestInit['headers'] | undefinedinsrc/shared/transport.ts, plus a changeset and a small test for the three input shapes (Headers, tuple array, plain object). I'll targetv1.x. @felixweinberger could you assign it to me? I'll have a PR up within a week.theOguz16 commentedon Oct 29, 2026
Reproduced on
@modelcontextprotocol/sdk@1.30.0with"lib": ["ES2023"],"types": ["node"],"skipLibCheck": false:HeadersInitcomes from the DOM lib only, whileRequestInitis also declared globally by@types/nodeviaundici-types, soRequestInit['headers']resolves without DOM. That is the signature already used onmain(packages/core-internal/src/shared/transport.ts).I have a one-line change on
v1.xplus a changeset:Verified by packing the branch and type-checking a consumer with
lib: ["ES2023"]— it goes fromTS2304to a clean compile. TheHeadersInitoccurrences insrc/client/sse.tsandsrc/client/streamableHttp.tsare local variables, so they never reach the emitted.d.tsand are left alone.CONTRIBUTING says to comment before starting. Is this still open for a community PR, or is it queued for a maintainer under
ready for work? Happy to open it either way.