From 0ea76e5658e378ed0aa98f7521c1bb7e699ffd9e Mon Sep 17 00:00:00 2001 From: Felix Weinberger Date: Mon, 17 Aug 2026 17:31:01 +0000 Subject: [PATCH 1/3] docs: add ROADMAP, VERSIONING and DEPENDENCY_POLICY for the v2 line Port the SEP-1730 governance documents from v1.x (#1547) to main, adjusted for the v2 monorepo: changesets version groups, per-package changelogs, the 2026-07-28 spec board, weekly Dependabot for Actions, pnpm catalogs and the 7-day minimumReleaseAge, and the v1.x maintenance window. No-Verification-Needed: documentation-only change --- DEPENDENCY_POLICY.md | 35 +++++++++++++++++++++++++++++++ ROADMAP.md | 35 +++++++++++++++++++++++++++++++ VERSIONING.md | 49 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 119 insertions(+) create mode 100644 DEPENDENCY_POLICY.md create mode 100644 ROADMAP.md create mode 100644 VERSIONING.md diff --git a/DEPENDENCY_POLICY.md b/DEPENDENCY_POLICY.md new file mode 100644 index 0000000000..0469d654e8 --- /dev/null +++ b/DEPENDENCY_POLICY.md @@ -0,0 +1,35 @@ +# Dependency Policy + +As a library consumed by downstream projects, the MCP TypeScript SDK takes a conservative approach to dependency updates. Dependencies are kept stable unless there is a specific reason to update, such as a security vulnerability, a bug fix, or a need for new functionality. + +This policy applies to every published package in this monorepo (`@modelcontextprotocol/core`, `client`, `server`, `server-legacy`, `codemod`, `node`, `express`, `hono`, `fastify`) and to the `v1.x` maintenance line (`@modelcontextprotocol/sdk`). + +## Update Triggers + +Dependencies are updated when: + +- A **security vulnerability** is disclosed (via GitHub security alerts). +- A bug in a dependency directly affects the SDK. +- A new dependency feature is needed for SDK development. +- A dependency drops support for a Node.js version the SDK still targets. +- A new MCP specification revision requires it. + +Routine version bumps without a clear motivation are avoided to minimize churn for downstream consumers. + +## What We Don't Do + +The SDK does not run scheduled version bumps for npm dependencies. Updating a dependency can force downstream consumers to adopt that update transitively, which can be disruptive for projects with strict dependency policies. + +Dependencies are only updated when there is a concrete reason, not simply because a newer version is available. + +## Automated Tooling + +- **GitHub security updates** are enabled at the repository level and automatically open pull requests for npm packages with known vulnerabilities. This is a GitHub repo setting, separate from the `dependabot.yml` configuration. +- **GitHub Actions versions** are kept up to date via Dependabot on a weekly schedule (see `.github/dependabot.yml`). +- **Supply-chain cooldown**: pnpm's `minimumReleaseAge` (see `pnpm-workspace.yaml`) keeps newly published versions out of the lockfile for 7 days, and only an allow-listed set of dependencies may run install scripts (`onlyBuiltDependencies`). + +## Pinning and Ranges + +Dependency ranges live in the pnpm workspace catalogs (`pnpm-workspace.yaml`), so a version is declared once and shared by every package. Runtime dependencies use caret ranges (`^`) to allow compatible updates within a major version. Exact versions are pinned only when necessary to work around a specific issue. Framework integrations (`express`, `hono`, `fastify`) declare the framework as a peer dependency rather than bundling a copy. + +Runtime dependencies of published packages are kept to a minimum; adding one is a design decision discussed in an issue first (see `CONTRIBUTING.md`). diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000000..7809904bfa --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,35 @@ +# Roadmap + +## Spec Implementation Tracking + +The SDK tracks implementation of MCP spec components via GitHub Projects, with a dedicated project board for each spec revision: + +- [2026-07-28 spec revision board](https://github.com/orgs/modelcontextprotocol/projects/41) — implemented in v2.0.0 (released 2026-07-27, alongside the spec). +- [2025-11-25 spec revision board](https://github.com/orgs/modelcontextprotocol/projects/26) — implemented in v1.23.0 (2025-11-25) and carried into v2. + +Conformance against every supported revision runs on each push to `main` and `v1.x` via the [conformance workflow](https://github.com/modelcontextprotocol/typescript-sdk/actions/workflows/conformance.yml) using the [MCP conformance suite](https://github.com/modelcontextprotocol/conformance). + +## Current Focus Areas + +### v2 hardening + +v2.0.0 is the stable release line (`main`). Post-release work is tracked as issues on this repository and released as 2.0.x patches: + +- Migration tooling and guides (`@modelcontextprotocol/codemod`, `docs/migration/`). +- Runtime coverage beyond Node.js (Bun, Deno, Cloudflare Workers, Vercel) and the framework integrations (`node`, `express`, `hono`, `fastify`). +- Documentation completeness for every non-experimental spec feature at https://ts.sdk.modelcontextprotocol.io. + +### Next Spec Revision + +The next MCP specification revision is being developed in the [protocol repository](https://github.com/modelcontextprotocol/modelcontextprotocol). The SDK implements accepted SEPs as they are finalized so that support ships with the spec release, with a dedicated project board tracking component-level progress for that revision. + +### Extensions + +Protocol extensions are implemented as they stabilize and are not part of the core tier requirements: + +- Tasks (`io.modelcontextprotocol/tasks`) — [#2189](https://github.com/modelcontextprotocol/typescript-sdk/issues/2189). +- Client authentication extensions: Workload Identity Federation (SEP-1933) — [#2576](https://github.com/modelcontextprotocol/typescript-sdk/issues/2576); DPoP (SEP-1932). + +### v1.x Maintenance + +The `v1.x` branch (`@modelcontextprotocol/sdk`) continues to receive bug fixes and security updates for at least six months after the v2 release (2026-07-27). It targets the 2025-11-25 spec revision; new spec revisions are implemented on `main` only. diff --git a/VERSIONING.md b/VERSIONING.md new file mode 100644 index 0000000000..c708358374 --- /dev/null +++ b/VERSIONING.md @@ -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 independently through Changesets (a change to `core` does not by itself imply a new integration release). +- `@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`. From d017562cbbc74b6386ba9345d432ec87aa2e0cfa Mon Sep 17 00:00:00 2001 From: Felix Weinberger Date: Mon, 17 Aug 2026 18:20:09 +0000 Subject: [PATCH 2/3] docs: tighten wording in ROADMAP and DEPENDENCY_POLICY No-Verification-Needed: documentation-only change --- DEPENDENCY_POLICY.md | 4 ++-- ROADMAP.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/DEPENDENCY_POLICY.md b/DEPENDENCY_POLICY.md index 0469d654e8..d09832a116 100644 --- a/DEPENDENCY_POLICY.md +++ b/DEPENDENCY_POLICY.md @@ -30,6 +30,6 @@ Dependencies are only updated when there is a concrete reason, not simply becaus ## Pinning and Ranges -Dependency ranges live in the pnpm workspace catalogs (`pnpm-workspace.yaml`), so a version is declared once and shared by every package. Runtime dependencies use caret ranges (`^`) to allow compatible updates within a major version. Exact versions are pinned only when necessary to work around a specific issue. Framework integrations (`express`, `hono`, `fastify`) declare the framework as a peer dependency rather than bundling a copy. +Ranges shared by more than one package live in the pnpm workspace catalogs (`pnpm-workspace.yaml`), so a version is declared once. Runtime dependencies use caret ranges (`^`) to allow compatible updates within a major version; exact versions of runtime dependencies are pinned only when necessary to work around a specific issue. Framework integrations (`express`, `hono`, `fastify`) declare the framework as a peer dependency rather than bundling a copy. -Runtime dependencies of published packages are kept to a minimum; adding one is a design decision discussed in an issue first (see `CONTRIBUTING.md`). +Runtime dependencies of published packages are kept to a minimum; adding one is a significant change under the discuss-before-you-code rule in `CONTRIBUTING.md`. diff --git a/ROADMAP.md b/ROADMAP.md index 7809904bfa..5cbe9af36e 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -7,7 +7,7 @@ The SDK tracks implementation of MCP spec components via GitHub Projects, with a - [2026-07-28 spec revision board](https://github.com/orgs/modelcontextprotocol/projects/41) — implemented in v2.0.0 (released 2026-07-27, alongside the spec). - [2025-11-25 spec revision board](https://github.com/orgs/modelcontextprotocol/projects/26) — implemented in v1.23.0 (2025-11-25) and carried into v2. -Conformance against every supported revision runs on each push to `main` and `v1.x` via the [conformance workflow](https://github.com/modelcontextprotocol/typescript-sdk/actions/workflows/conformance.yml) using the [MCP conformance suite](https://github.com/modelcontextprotocol/conformance). +Conformance against the 2025-11-25 and 2026-07-28 revisions runs on each push to `main` (and against 2025-11-25 on `v1.x`) via the [conformance workflow](https://github.com/modelcontextprotocol/typescript-sdk/actions/workflows/conformance.yml) using the [MCP conformance suite](https://github.com/modelcontextprotocol/conformance). ## Current Focus Areas @@ -17,7 +17,7 @@ v2.0.0 is the stable release line (`main`). Post-release work is tracked as issu - Migration tooling and guides (`@modelcontextprotocol/codemod`, `docs/migration/`). - Runtime coverage beyond Node.js (Bun, Deno, Cloudflare Workers, Vercel) and the framework integrations (`node`, `express`, `hono`, `fastify`). -- Documentation completeness for every non-experimental spec feature at https://ts.sdk.modelcontextprotocol.io. +- Documentation completeness for every non-experimental spec feature at https://ts.sdk.modelcontextprotocol.io/v2/. ### Next Spec Revision From fe4d2a6c0848e67d88735c16a77ca6bc6217299c Mon Sep 17 00:00:00 2001 From: Felix Weinberger Date: Tue, 18 Aug 2026 10:17:15 +0000 Subject: [PATCH 3/3] docs: correct middleware versioning, pinning, cooldown exclusions and roadmap wording No-Verification-Needed: documentation-only change --- DEPENDENCY_POLICY.md | 4 ++-- ROADMAP.md | 4 ++-- VERSIONING.md | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/DEPENDENCY_POLICY.md b/DEPENDENCY_POLICY.md index d09832a116..6be03850f3 100644 --- a/DEPENDENCY_POLICY.md +++ b/DEPENDENCY_POLICY.md @@ -26,10 +26,10 @@ Dependencies are only updated when there is a concrete reason, not simply becaus - **GitHub security updates** are enabled at the repository level and automatically open pull requests for npm packages with known vulnerabilities. This is a GitHub repo setting, separate from the `dependabot.yml` configuration. - **GitHub Actions versions** are kept up to date via Dependabot on a weekly schedule (see `.github/dependabot.yml`). -- **Supply-chain cooldown**: pnpm's `minimumReleaseAge` (see `pnpm-workspace.yaml`) keeps newly published versions out of the lockfile for 7 days, and only an allow-listed set of dependencies may run install scripts (`onlyBuiltDependencies`). +- **Supply-chain cooldown**: pnpm's `minimumReleaseAge` (see `pnpm-workspace.yaml`) keeps newly published versions out of the lockfile for 7 days (`minimumReleaseAgeExclude` lists the exceptions, currently the MCP conformance suite), and only an allow-listed set of dependencies may run install scripts (`onlyBuiltDependencies`). ## Pinning and Ranges -Ranges shared by more than one package live in the pnpm workspace catalogs (`pnpm-workspace.yaml`), so a version is declared once. Runtime dependencies use caret ranges (`^`) to allow compatible updates within a major version; exact versions of runtime dependencies are pinned only when necessary to work around a specific issue. Framework integrations (`express`, `hono`, `fastify`) declare the framework as a peer dependency rather than bundling a copy. +Ranges shared by more than one package live in the pnpm workspace catalogs (`pnpm-workspace.yaml`), so a version is declared once. Runtime dependencies use caret ranges (`^`) to allow compatible updates within a major version; exact versions of third-party runtime dependencies are pinned only when necessary to work around a specific issue. Dependencies between the SDK's own packages (`workspace:*`) publish as exact pins by design, so a released `client` or `server` always resolves the `core` it was built against. Framework integrations (`express`, `hono`, `fastify`) declare the framework as a peer dependency rather than bundling a copy. Runtime dependencies of published packages are kept to a minimum; adding one is a significant change under the discuss-before-you-code rule in `CONTRIBUTING.md`. diff --git a/ROADMAP.md b/ROADMAP.md index 5cbe9af36e..377fc86a97 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -5,7 +5,7 @@ The SDK tracks implementation of MCP spec components via GitHub Projects, with a dedicated project board for each spec revision: - [2026-07-28 spec revision board](https://github.com/orgs/modelcontextprotocol/projects/41) — implemented in v2.0.0 (released 2026-07-27, alongside the spec). -- [2025-11-25 spec revision board](https://github.com/orgs/modelcontextprotocol/projects/26) — implemented in v1.23.0 (2025-11-25) and carried into v2. +- [2025-11-25 spec revision board](https://github.com/orgs/modelcontextprotocol/projects/26) — implemented in v1.23.0 (2025-11-25) and carried into v2, minus the experimental tasks component (SEP-1686), which v2 does not serve. Conformance against the 2025-11-25 and 2026-07-28 revisions runs on each push to `main` (and against 2025-11-25 on `v1.x`) via the [conformance workflow](https://github.com/modelcontextprotocol/typescript-sdk/actions/workflows/conformance.yml) using the [MCP conformance suite](https://github.com/modelcontextprotocol/conformance). @@ -13,7 +13,7 @@ Conformance against the 2025-11-25 and 2026-07-28 revisions runs on each push to ### v2 hardening -v2.0.0 is the stable release line (`main`). Post-release work is tracked as issues on this repository and released as 2.0.x patches: +v2.0.0 is the stable release line (`main`). Post-release work is tracked as issues on this repository and released as 2.x patch and minor releases (see `VERSIONING.md`): - Migration tooling and guides (`@modelcontextprotocol/codemod`, `docs/migration/`). - Runtime coverage beyond Node.js (Bun, Deno, Cloudflare Workers, Vercel) and the framework integrations (`node`, `express`, `hono`, `fastify`). diff --git a/VERSIONING.md b/VERSIONING.md index c708358374..787da06f3a 100644 --- a/VERSIONING.md +++ b/VERSIONING.md @@ -7,7 +7,7 @@ The MCP TypeScript SDK follows [Semantic Versioning 2.0.0](https://semver.org/) 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 independently through Changesets (a change to `core` does not by itself imply a new integration release). +- 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`).