SPEC COMPLIANCE: Remove loose/passthrough types not allowed/defined by MCP spec + Task types #1242

KKonstantinov · 2025-12-07T12:37:52Z

Typescript SDK has for a long time contained types which are allowing more than the actual specification. This has been masked by the spec test (spec.types.ts) having a RemovePassthrough helper to make types pass typechecks. This has unfortunately lead to actual implementation in the SDK to have wrong types, as well as SDK users to have the ability to use out-of-spec attributes in various JSONRPC methods - knowingly or unknowingly. Further, in many occasions it has broken types for SDK end users.

TL; DR:

This PR is a final iteration on bringing the SDK to be fully aligned with the MCP spec and to only allow flexibility where that flexibility is explicitly defined by the specification.
EDIT: This PR also pulls in 18 new types from the official spec (https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2025-11-25/schema.ts) which were missing in the SDK.

Motivation and Context

Passthrough and loose objects not allowed by the spec were largely removed in another PR, but a few still remain.

How Has This Been Tested?

Unit tests, type checking.

Breaking Changes

None. Bringing SDK back to full spec compliance.

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

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

pkg-pr-new · 2025-12-07T12:38:34Z

Open in StackBlitz

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/sdk@1242

commit: 36536f9

felixweinberger

Looking at this change to Request and Notification, I'm not convinced 0 passthrough is actually the right objective for all types. I don't think the spec's types are all that strict.

Some types are intended to be flexible per the spec, these ones being specific examples. See the spec's schema.ts which literally has a comment "Allow unofficial extensions of Request.params without impacting `RequestParams")

In practice we're introducing new Generic types just to be able to keep the flexibility which seems odd? Runtime behavior hasn't really changed, we just introduced a new type to hide the flexibility elsewhere?

src/shared/protocol.ts

src/types.ts

… types from 2025-11-25 spec

…ub.com:KKonstantinov/typescript-sdk into feature/passthrough-looseobject-removal-part-2

felixweinberger

Thanks @KKonstantinov for reworking this AND syncing our schema.ts to the latest version! Some small follow-ups but I think we can do that in a fast-follow PR if easier.

Let's use the npm run fetch:spec-types to update the spec as that will be what the nightly build does anyway. To align with the 2025-11-25 spec this makes sense, let's make sure we stay synced with the protocol.
The timeout increase - was that necessary for this PR or just bypassing some flakiness?
Let's remove the console.log from the test.

felixweinberger · 2025-12-09T11:26:41Z

src/spec.types.ts

- * Last updated from commit: 7dcdd69262bd488ddec071bf4eefedabf1742023
- *
- * DO NOT EDIT THIS FILE MANUALLY. Changes will be overwritten by automated updates.
- * To update this file, run: npm run fetch:spec-types


did you run this? not sure we should be removing this docstring

In the interim it's fine to do this I think, but we'll want to restore the nightly logic as a fast follow. Ran it locally and there are some small diffs in comments and the 2026-DRAFT version which I think should be the one this points to longer term

Yeah I didn't run it, but got the stable spec from 2025-25-11 version to test against. Now it's restored via #1274

src/types.ts

felixweinberger · 2025-12-09T11:39:13Z

test/spec.types.test.ts

 /* eslint-disable @typescript-eslint/no-unsafe-function-type */

-// Removes index signatures added by ZodObject.passthrough().
-type RemovePassthrough<T> = T extends object


felixweinberger · 2025-12-09T11:40:05Z

test/spec.types.test.ts

            }
        }

+        console.log(missingTests);


nit: I'm guessing this was accidentally included during debugging?

felixweinberger · 2025-12-09T11:41:16Z

test/server/streamableHttp.test.ts

            // Verify we received the notification that was sent while disconnected
            expect(allText).toContain('Missed while disconnected');
-        }, 10000);
+        }, 15000);


nit: This increase in timeouts seems unrelated to this change right? Just to reduce flakiness?

Yes for some reason 10s was still not enough to remove flakiness, I've not looked into why in this PR.

felixweinberger · 2025-12-09T11:47:24Z

src/types.ts

 export const RequestSchema = z.object({
    method: z.string(),
-    params: BaseRequestParamsSchema.optional()
+    params: BaseRequestParamsSchema.loose().optional()


felixweinberger · 2025-12-09T11:47:29Z

src/types.ts

 });

-const NotificationsParamsSchema = z.looseObject({
+const NotificationsParamsSchema = z.object({


- Restore spec.types.ts docstring header via npm run fetch:spec-types - Remove debugging console.log from spec.types.test.ts - Revert unrelated timeout increase in streamableHttp.test.ts

passthrough, looseoebject removal part 2

bf5a7ef

KKonstantinov requested a review from a team as a code owner December 7, 2025 12:37

KKonstantinov and others added 3 commits December 7, 2025 14:43

flaky test fix

a297f9d

Merge branch 'main' into feature/passthrough-looseobject-removal-part-2

9363ec9

Merge branch 'main' into feature/passthrough-looseobject-removal-part-2

ce49412

felixweinberger requested changes Dec 8, 2025

View reviewed changes

src/shared/protocol.ts Outdated Show resolved Hide resolved

src/types.ts Show resolved Hide resolved

felixweinberger reviewed Dec 8, 2025

View reviewed changes

src/types.ts Outdated Show resolved Hide resolved

KKonstantinov added 2 commits December 8, 2025 19:22

remove result generic and notification generic, align types with Task…

b4278c8

… types from 2025-11-25 spec

Merge branch 'feature/passthrough-looseobject-removal-part-2' of gith…

f332ccd

…ub.com:KKonstantinov/typescript-sdk into feature/passthrough-looseobject-removal-part-2

KKonstantinov changed the title ~~Passthrough removal part 2: Achieve 0 passthrough types.~~ Passthrough removal part 2: Remove loose types not allowed by spec. Dec 8, 2025

KKonstantinov and others added 3 commits December 8, 2025 20:15

Merge branch 'main' into feature/passthrough-looseobject-removal-part-2

d62b7f8

GetTaskPayloadResult in examples

bbbf2cf

Merge branch 'feature/passthrough-looseobject-removal-part-2' of gith…

47583d1

…ub.com:KKonstantinov/typescript-sdk into feature/passthrough-looseobject-removal-part-2

KKonstantinov changed the title ~~Passthrough removal part 2: Remove loose types not allowed by spec.~~ SPEC COMPLIANCE: Remove loose/passthrough types not allowed/defined by MCP spec. Dec 8, 2025

KKonstantinov changed the title ~~SPEC COMPLIANCE: Remove loose/passthrough types not allowed/defined by MCP spec.~~ SPEC COMPLIANCE: Remove loose/passthrough types not allowed/defined by MCP spec + Task types Dec 8, 2025

Merge branch 'main' into feature/passthrough-looseobject-removal-part-2

36536f9

felixweinberger approved these changes Dec 9, 2025

View reviewed changes

felixweinberger merged commit a606fb1 into modelcontextprotocol:main Dec 9, 2025
6 checks passed

felixweinberger mentioned this pull request Dec 9, 2025

Follow-up fixes for PR #1242 #1274

Merged

9 tasks

felixweinberger added a commit that referenced this pull request Dec 9, 2025

Follow-up fixes for PR #1242 (#1274)

06a4fd2

Liooo mentioned this pull request Dec 10, 2025

fix: nullable json-rpc id instead of optional #1281

Open

9 tasks

SPEC COMPLIANCE: Remove loose/passthrough types not allowed/defined by MCP spec + Task types #1242

SPEC COMPLIANCE: Remove loose/passthrough types not allowed/defined by MCP spec + Task types #1242

Uh oh!

Conversation

KKonstantinov commented Dec 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Uh oh!

pkg-pr-new bot commented Dec 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

felixweinberger left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

felixweinberger left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

KKonstantinov commented Dec 7, 2025 •

edited

Loading

pkg-pr-new bot commented Dec 7, 2025 •

edited

Loading