feat(node): restore SSEServerTransport under /node/sse, @deprecated

[felixweinberger]

Part of the v2 backwards-compatibility series — see reviewer guide.

v2 removed SSEServerTransport. Proxy/bridge use-cases (stdio→SSE→browser) still need it; the spec still documents SSE. Restored as @deprecated v1 copy.

Motivation and Context

v2 removed SSEServerTransport. Proxy/bridge use-cases (stdio→SSE→browser) still need it; the spec still documents SSE. Restored as @deprecated v1 copy.

v1 vs v2 pattern & evidence

v1 pattern:

`import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'`

v2-native:

`import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node'` (StreamableHTTP supersedes SSE)

Evidence: Hit in real-repo testing (proxy/bridge pattern).

How Has This Been Tested?

• packages/middleware/node/test/sse.compat.test.ts
• Integration: validated bump-only against 5 OSS repos via the v2-bc-integration validation branch
• pnpm typecheck:all && pnpm lint:all && pnpm test:all green

Breaking Changes

None — additive @deprecated shim. Removed in v3.

Types of changes

• New feature (non-breaking change which adds functionality)

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added or updated documentation as needed

Additional context

Stacks on: none

[changeset-bot]

🦋 Changeset detected

Latest commit: 32bd98d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@modelcontextprotocol/node	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/@modelcontextprotocol/client@1909

@modelcontextprotocol/server

npm i https://pkg.pr.new/@modelcontextprotocol/server@1909

@modelcontextprotocol/express

npm i https://pkg.pr.new/@modelcontextprotocol/express@1909

@modelcontextprotocol/fastify

npm i https://pkg.pr.new/@modelcontextprotocol/fastify@1909

@modelcontextprotocol/hono

npm i https://pkg.pr.new/@modelcontextprotocol/hono@1909

@modelcontextprotocol/node

npm i https://pkg.pr.new/@modelcontextprotocol/node@1909

commit: 32bd98d

[felixweinberger]

@claude review

[felixweinberger]

@claude review

[felixweinberger]

@claude review

[claude]

All prior feedback addressed (docs, changeset wording, section heading, test-only export removed) — no further issues from me. Deferring to a human for the final sign-off since this adds a new public entry point (./sse), two runtime deps, and a ~260-line transport, which is a BC-series design call worth a maintainer ack.

Extended reasoning...

Overview

Restores the v1 SSEServerTransport as a deprecated compat shim under @modelcontextprotocol/node/sse. Touches: new packages/middleware/node/src/sse.ts (~260 LoC, frozen v1 port + a small toWebRequest adapter), new ./sse subpath export in package.json + tsdown.config.ts, two new runtime deps (content-type, raw-body), a vitest integration test, a changeset, and doc updates across docs/migration.md, docs/migration-SKILL.md, and docs/faq.md.

Review history

Four prior rounds. All actionable items are now resolved: migration/FAQ prose updated to reflect the shim; the leaked _resetSSEDeprecationWarning export was removed (runtime warning dropped entirely); the changeset wording was corrected (no more "without code changes" / non-existent meta-package); and the §8 heading was renamed in 2a95520. The two declined items (close() double-onclose, unguarded new URL on raw Host header) were declined on the explicit "frozen v1 port — not hardening beyond v1" basis, which is consistent with the PR's stated scope and the linked BC-series reviewer guide.

Security risks

The toWebRequest Host-header parse can throw on malformed-but-valid header values, potentially yielding an unhandled rejection — flagged previously, author confirmed v1 has identical behavior at the same position, so this is not a regression. DNS-rebinding protection is opt-in (matches v1). No new auth/crypto surface.

Level of scrutiny

Moderate-to-high: this is new public API surface and new dependencies, and it reverses a prior v2 removal decision. The implementation itself is low-risk (battle-tested v1 code), but the decision to ship it belongs to a maintainer per REVIEW.md's "burden of proof is on addition" principle.

Other factors

Part of the documented v2-bc series with a reviewer guide; integration-tested against 5 OSS repos per the description; vitest coverage for the happy path. Bug-hunting system found nothing this round. I'm not approving solely because the scope (new entry point + deps + design reversal) exceeds the "simple/mechanical" bar, not because of any outstanding concern.

[claude]

Thanks — 32bd98d's heading rename was the last open item from my side and the bug hunter found nothing new this round. Leaving final sign-off to a maintainer since this adds a new public subpath export plus content-type/raw-body runtime deps to @modelcontextprotocol/node.

Extended reasoning...

Overview

This PR restores SSEServerTransport as a deprecated v1-compat shim under @modelcontextprotocol/node/sse. It adds a new ~260-line transport source file (packages/middleware/node/src/sse.ts, a frozen port of v1's src/server/sse.ts plus a small toWebRequest adapter), a new ./sse subpath export in package.json, two new runtime dependencies (content-type, raw-body), a vitest integration test, a changeset, and doc updates across docs/migration.md, docs/migration-SKILL.md, and docs/faq.md.

Prior feedback status

Across four review rounds, every item is now either fixed or explicitly declined as out-of-scope for a frozen v1 port:

• Docs claiming SSE was removed → fixed (2d16182).
• _resetSSEDeprecationWarning leaking as public API → fixed by removing the runtime warning entirely.
• Changeset "without code changes" / non-existent meta-package wording → fixed (1188b1a, 9287528); current changeset text is accurate.
• §8 heading "Removed Server Features" → renamed to "Deprecated/Removed Server Features" (32bd98d).
• onclose double-fire and unguarded new URL(host) in toWebRequest → declined as byte-identical to origin/v1.x:src/server/sse.ts; reasonable given the bit-for-bit-compat goal.

Security risks

The transport handles raw HTTP input: DNS-rebinding host/origin checks, content-type parsing, raw-body consumption (capped at 4 MB), and JSON parsing. These code paths are inherited verbatim from the v1 implementation that has been in production use, and the module is @deprecated/quarantined under its own subpath so it doesn't affect users of NodeStreamableHTTPServerTransport. I don't see new injection/auth-bypass surface beyond what v1 already shipped, but this is still HTTP-request-handling code in a published package.

Level of scrutiny

Medium-high. While the implementation is a near-verbatim v1 port (low novelty risk), the PR makes design-level decisions a maintainer should ratify: (1) restoring a previously-removed transport as public API, (2) adding content-type and raw-body as runtime dependencies of @modelcontextprotocol/node for all consumers (not just SSE users), and (3) committing to carry this until v3. Those are exactly the "burden of proof is on addition" calls REVIEW.md reserves for humans.

Other factors

Test coverage exists (sse.compat.test.ts exercises endpoint event, POST routing, and send()); typecheck/lint/test reportedly green; integration-validated against 5 OSS repos per the PR description. No special CODEOWNERS apply. Given the new public surface and dependency additions, I'm deferring rather than auto-approving.