OpenWikimodelcontextprotocol/typescript-sdk

Upgrade to v2

Purpose and Scope

Use this page when you have code on the v1 monolithic package and need to move it to the v2 package split. The migration documentation treats the v2 upgrade as a package and public API migration first: replace the old single dependency, let the codemod perform mechanical rewrites, then finish the remaining type, runtime, and behavior changes by hand. The repository’s migration index explicitly points v1 users to this guide and separates it from the later protocol revision work, so do not combine the two projects into one unreviewable change.

Sources: docs/migration/upgrade-to-v2.md, docs/migration/index.md

The upgrade guide is written for both humans and shell-capable agents. That matters because the recommended path starts with a repeatable command, then uses build output and codemod diagnostics as the work queue. Treat the command output, inline migration markers, and TypeScript errors as structured signals rather than as unrelated cleanup. This keeps a large migration boring: first update imports and package metadata broadly, then inspect only the code the tool could not safely transform, then format and test the resulting tree.

Sources: docs/migration/upgrade-to-v2.md

Relevant Source Files

  • docs/migration/upgrade-to-v2.md — Primary v1 to v2 migration guide, including the quick path, codemod invocation, manual follow-up sections, and the distinction between v2 package migration and later protocol adoption.
  • docs/migration/index.md — Migration landing page that tells v1 users to start with the v2 upgrade guide, run the codemod at the package root, and use the 2026 guide only after the package migration is complete.
  • docs/migration/support-2026-07-28.md — Follow-up guide for projects already on v2 that want to opt into the 2026-07-28 protocol revision, version negotiation, modern serving APIs, and per-era behavior.
  • docs/.vitepress/theme/index.ts — v2 documentation site theme wiring; it extends the default VitePress theme and inserts the shared banner at the top of the layout.
  • docs/v1/.vitepress/theme/index.ts — v1 documentation site theme wiring; it keeps the legacy docs site available while sharing the v2 custom CSS instead of duplicating it.
  • docs/_meta/CONVENTIONS.md — Authoring conventions for the official docs, including code-first migration style, imperative language, short main-flow paragraphs, and recap expectations.

Migration Flow

Run the migration from the package root, not from a source subdirectory. The migration index calls this out because real projects import the SDK from tests, scripts, fixtures, and other nonproduction folders, while the codemod also needs to rewrite package metadata. If you target only a source directory, you create a partial migration: application files may compile, but tests or helper tools keep importing the old package. The root-level command gives the codemod a complete view of the package and makes the later grep step meaningful.

Sources: docs/migration/upgrade-to-v2.md, docs/migration/index.md

Use this command as the first mechanical step:

npx @modelcontextprotocol/codemod@beta v1-to-v2 .

After the codemod runs, search for explicit failure markers before you start editing based on intuition. The upgrade guide says recognized but unsafe rewrites are marked in place, which means the migration leaves a to-do list directly where human judgment is needed. Review those markers before broad refactors, because each marker preserves local context about the old v1 usage. Then run your normal type check. Remaining compiler errors should map to the manual sections in the guide, while formatter noise should wait until after semantic fixes are complete.

Sources: docs/migration/upgrade-to-v2.md

Use this search to find the codemod markers:

grep -rn '@mcp-codemod-error' .

Package and API Changes

The key package change is that v2 replaces the monolithic v1 package with side-specific packages. Server code moves toward the server package, client code moves toward the client package, and raw schema consumers use the core package. The official package guidance also explains subpath exports: root imports expose broadly portable APIs, while Node-only stdio transports live behind a stdio subpath. During migration, keep that boundary visible. If a browser-capable client module starts importing a child-process transport, you have moved a Node-only concern into the wrong layer.

Sources: docs/migration/upgrade-to-v2.md

Library authors should be especially careful with dependency declarations. Application packages can install the concrete client or server package they execute, but reusable libraries that peer-depend on the SDK need to model the new split intentionally. A helper that only registers server-side tools should not force client dependencies on downstream users. A host integration that supports both sides may need both packages. The migration is a good time to narrow public surfaces, because v2 makes the protocol role visible in the import path instead of hiding everything behind one package name.

Sources: docs/migration/upgrade-to-v2.md

Protocol Revision Boundary

Do not treat the v2 package upgrade as the same task as adopting the 2026-07-28 protocol revision. The migration landing page states that the codemod covers the v1 to v2 SDK surface only, while the 2026 revision involves architecture-level choices such as modern handler creation, multi-round-trip requests, version negotiation, and per-era wire codecs. The 2026 guide also says hand-constructed v2 clients and servers continue using the 2025-era behavior unless you explicitly opt in. Finish the package migration first, then make protocol-era changes as a second reviewable step.

Sources: docs/migration/index.md, docs/migration/support-2026-07-28.md

This separation gives you safer compatibility testing. A v1 to v2 migration should prove that your existing behavior still works on the new package layout. Only after that baseline passes should you decide whether a client should negotiate automatically, pin a modern revision, or remain legacy-compatible. On the server side, the later revision work may change request state handling, auth expectations, subscription listening behavior, cache fields, and other wire-era details. Keeping those changes out of the initial package upgrade makes regressions easier to attribute.

Sources: docs/migration/support-2026-07-28.md

Documentation and Review Signals

The repository keeps both v2 and v1 documentation sites wired through VitePress theme entry points, with the v1 site sharing the v2 custom CSS. That source layout reflects the migration story: v1 remains documented while v2 is being adopted, and readers need clear navigation between the two eras. The migration pages themselves use frontmatter and direct links so a human reader or an agent can choose the correct guide. When you update internal migration notes, preserve that distinction instead of replacing v1 references with vague historical comments.

Sources: docs/.vitepress/theme/index.ts, docs/v1/.vitepress/theme/index.ts, docs/migration/index.md

The documentation conventions file reinforces the intended style for these guides: start with concrete action, use imperative language, keep asides out of the main path, and define terms close to where they are used. Apply the same pattern in project-specific upgrade pull requests. Put the codemod command, grep command, type-check command, and test command in the migration description. Then list any manual edits by area, such as imports, transports, package metadata, or protocol-era choices. Reviewers can compare that checklist to the official migration flow.

Sources: docs/_meta/CONVENTIONS.md, docs/migration/upgrade-to-v2.md

Verification Checklist

A complete upgrade has four visible checkpoints. First, package metadata no longer depends on the old monolithic package for migrated code. Second, the codemod marker search returns no unresolved migration errors. Third, the project type-checks with the v2 imports and package boundaries in place. Fourth, the test suite exercises the same client, server, transport, and helper paths that existed before the migration. Run formatting after semantic edits because the guide notes that the codemod rewrites the syntax tree without doing final formatting.

Sources: docs/migration/upgrade-to-v2.md

Use the protocol revision guide only after those checks pass. At that point, read the sections on client version negotiation, serving the modern revision, state replacement, auth, wire codecs, and multi-round-trip requests as a separate adoption plan. If you maintain examples or developer docs, update them in the same order: package imports first, runtime behavior second, modern protocol features last. That sequence matches the repository’s migration index and gives users a clear path from v1 production code to v2 beta packages without hiding architectural changes inside mechanical rewrites.

Sources: docs/migration/index.md, docs/migration/support-2026-07-28.md

Ask a question...