[v2] Мonorepo, sdk-client, sdk-server, sdk-core package split

[KKonstantinov]

Proof of Concept: v2 monorepo, package split

Motivation and Context

v1 of the sdk shipped both client and server in the same package, introducing extra dependencies to users who have a single concern (client or server only). Client and server packages are now split, depending on a shared core package.

Additionally, v1 exported all files as the public API of the SDK, limiting the SDK ability to iterate internally while keeping backwards compatibility. Barrel files are now introduced as the single entrypoint to the SDK and defining the public API of the SDK.

• Dropped Node v18
• Dropped CommonJS (ESM only)
• Updated tsgo to one of the latest versions
• Bumped the ts version
• Added eslint import rules to tidy up imports
• cleaned-up package.json files - client-sdk and server-sdk ship with the minimum required dependencies (as opposed to v1, which shipped server deps if you were only interested in the client and vice versa
• introduce catalogs for reusing dep versions
• bundling tool change - tsdown
• updated docs

How Has This Been Tested?

Unit, integration tests

Breaking Changes

v2

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

Additional context

[pkg-pr-new]

Open in StackBlitz

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

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

commit: c3b1a40

[felixweinberger]

Is there a way we can break this PR up somehow so that this is more reviewable? E.g. with using git mv to preserve history and provenance of files? As it is it'll be quite hard to verify correctness of the split.

[KKonstantinov]

EDITs:

• Provenance / history retained (except 3-4 files, will review them and bring it to them as well)
• Dropped Node v18
• Dropped CommonJS (ESM only)
• Updated tsgo to one of the latest versions
• Bumped the ts version
• Added eslint import rules to tidy up imports
• cleaned-up package.json files - client-sdk and server-sdk ship with the minimum required dependencies (as opposed to v1, which shipped server deps if you were only interested in the client and vice versa
• introduce catalogs for reusing dep versions
• bundling tool change - tsdown as per @mattzcarey
• updated docs

TODOs still:

• test(18) check - no code change, repository config -> needs to be removed as required check from branch rulesets, and replaced with test(20)

[changeset-bot]

🦋 Changeset detected

Latest commit: c3b1a40

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

This PR includes changesets to release 2 packages

Name	Type
@modelcontextprotocol/client	Patch
@modelcontextprotocol/server	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

[felixweinberger]

Awesome refactor, looking great. THANK YOU for taking the time to ensure git history is preserved - that made it MUCH easier to review 95% of this PR as the vast majority of this PR is just shuffling around imports for the new structure.

I peppered with comments, but most of them are questions I had as I was working through so I don't forget - not asks for modifications. Please ignore comments except this one for the next hour or so while I investigate and try to answer my own questions.

Some things I wanted to discuss for sure though:

1. We use ! type checker overrides a lot in this PR. Is this an indication of behavior change or we've somehow tightened tsconfig so we have to do this to satisfy the linter and these are pre-existing problems?
   Addressed, we tightened our type checks and this has no runtime effect. If anything it's good to make it explicit so we can periodically fix it.

2. I think we missed one test file test/experimental/tasks/stores/in-memory.test.ts - there are 59 tests less in this version than in the current main, and this file contains exactly 59 tests.
   Addressed, brought it back. Test count now matches exactly what it was before.

3. We're creating a lot of packages and package.json files - my expectation was that we'd have 3 max: client, server, core. Is this typical? Are we adding complexity for either users or ourselves by doing this?
   Addressed, welcome to Typescript 2025. Minimize dependencies we force people to import.

4. Why change to pnpm? What's the advantage of this? Are we making it more difficult for people to install the SDK? Is this a DevX improvement? I have no intuition of what this change means, is this a drop in replacement for npm?
   Addressed, this provides us a lot of utilities for monorepo dev with multiple packages that npm doesn't support. It's also included with corepack via Node anyway, so minimal Dev friction for contributors, zero change for consumers of the SDK.

5. Did you (or some agent 😄) potentially verify that the examples all still work as written here? Or is that something we still need to do?
   Added to follow-ups for myself

[felixweinberger]

Noting down some follow-ups to this PR we'll want to do as a note to self:

• Highlight change to pnpm in CONTRIBUTING.md - i.e. enable corepack if haven't already, probably need it in README too.
• Call out v1.x and main specifically.
• Update CONTRIBUTING.md with guidance around what to use as base branch
• Update README with a note right up top that we're working on v2, use the README and docs from v1.x by default.
• Update release.yaml on the v1.x branch. Will note it in my follow-ups comment.
• Remove inMemoryEventStory.ts back to examples rather than in main exports.
• Tweak language in README about roadmap / path to v2 + big NOTE right at the top to call it out.
• Test every example, audit all .md files for correctness.
• Circular dependency (I think) between client & test-helpers potentially?

[KKonstantinov]

Managed to bring back tsgo. Had to update @typescript/native-preview to resolve prior challenges I had with it.

cc @mattzcarey

[felixweinberger]

I think we'll need a more visible pointer at the very top of the docs rather than at the bottom. And I think it's actually premature to call this "legacy" -> v1 will remain the primary version for the next few months at least. "legacy" language here implies we're dropping support basically straight away and people should use whatever is on main which isn't actually the case yet.

I think we should only call it legacy once we actually have a stable 2.0.0 release.

Can be a fast follow, noting it down.

[felixweinberger]

Awesome stuff!