modelcontextprotocol/typescript-sdk
Watch
1
0
Fork
You've already forked typescript-sdk
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

docs: add ROADMAP, VERSIONING and DEPENDENCY_POLICY for the v2 line (#2680)

Browse source
This commit is contained in:
Felix Weinberger 2026-08-18 13:34:31 +01:00 • committed by GitHub
commit e3f39c1a81
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 119 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

49
VERSIONING.md Normal file
View file

@ -0,0 +1,49 @@
# Versioning Policy
The MCP TypeScript SDK follows [Semantic Versioning 2.0.0](https://semver.org/) for every published package.
## Packages and Version Groups
The v2 SDK is a monorepo. Versions are managed with [Changesets](https://github.com/changesets/changesets) (`.changeset/`):
- `@modelcontextprotocol/core`, `client`, `server`, `server-legacy` and `codemod` form a **fixed group** and always release together with the same version.
- The framework integrations `@modelcontextprotocol/node`, `express`, `hono` and `fastify` are versioned through Changesets alongside the fixed group: they bump whenever their `@modelcontextprotocol/server` peer range has to move, and independently for their own changes.
- `@modelcontextprotocol/core-internal` is private and carries no compatibility promise; the `@modelcontextprotocol/core/internal` entry point is likewise not covered by this policy and may change in any release.
- The `v1.x` branch continues to publish `@modelcontextprotocol/sdk` 1.x under the same rules (patch releases on `release-X.Y` npm tags; see `CONTRIBUTING.md`).
## Version Format
`MAJOR.MINOR.PATCH`
- **MAJOR**: Incremented for breaking changes (see below).
- **MINOR**: Incremented for new features that are backward-compatible.
- **PATCH**: Incremented for backward-compatible bug fixes.
## What Constitutes a Breaking Change
The following changes are considered breaking and require a major version bump:
- Removing or renaming a public API export (class, function, type, or constant).
- Changing the signature of a public function or method in a way that breaks existing callers (removing parameters, changing required/optional status, changing types).
- Removing or renaming a public type or interface field.
- Changing the behavior of an existing API in a way that breaks documented contracts.
- Dropping support for a Node.js LTS version.
- Removing support for a transport type.
- Dropping support for an MCP protocol revision the SDK previously negotiated (see `docs/protocol-versions.md`).
The following are **not** considered breaking:
- Adding new optional parameters to existing functions.
- Adding new exports, types, or interfaces.
- Adding new optional fields to existing types.
- Bug fixes that correct behavior to match documented intent.
- Internal refactoring that does not affect the public API.
- Adding support for new MCP spec revisions or features.
- Changes to dev dependencies or build tooling.
## How Breaking Changes Are Communicated
1. **Changelog**: Every consumer-facing change ships with a changeset; the per-package `CHANGELOG.md` and the GitHub release for each package tag document breaking changes with migration instructions.
2. **Deprecation**: When feasible, APIs are deprecated for at least one minor release before removal using `@deprecated` JSDoc annotations, which surface warnings through TypeScript tooling and editors. Protocol features the specification deprecates stay available for as long as the specification keeps them.
3. **Migration guide**: Major version releases include a migration guide (see `docs/migration/`) and, where practical, a codemod (`@modelcontextprotocol/codemod`).
4. **PR labels**: Pull requests containing breaking changes are labeled with `breaking change`.