Repository navigation
Publish versioning, roadmap, and dependency policies for v2 #3215
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
+109
−4
Merged
Changes from 6 commits
Commits
Show all changes
11 commits
Select commit
Hold shift + click to select a range
e90d907
Publish versioning, roadmap, and dependency policies for v2
maxisbey e8bee4d
Address review: pre-release opt-in, era-scoped deprecations, lock recipe
maxisbey fbefbf6
Address review: state policy, stop restating mechanics owned elsewhere
maxisbey dfee3cb
Address review: SEP link, extras wording, taxonomy scope
maxisbey 8f6eded
Trim the versioning policy to its commitments
maxisbey 07eb1a4
Trim the roadmap and dependency policy to their commitments
maxisbey 429e98c
Move the versioning policy and roadmap to the repository root
maxisbey bc5bfe8
Drop the docs index pointer to the root policy files
maxisbey 2be1b57
Address review: roadmap open item, baseline scope, deferral and place…
maxisbey 4102871
Address review: retired-feature wording, lock description, roadmap tr…
maxisbey 9ab5bca
Bullet the support and announcements section
maxisbey File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Some comments aren't visible on the classic Files Changed page.
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,15 @@ | ||
| # Dependency Policy | ||
|
|
||
| `mcp` is a library that lives inside other people's environments, so its requirements are chosen to constrain your resolver as little as possible while still describing what the SDK needs. | ||
|
|
||
| ## How requirements are declared | ||
|
|
||
| Every runtime dependency is a `>=` floor set to the oldest version that provides what the SDK uses, with no upper bound unless a dependency's next major is known to break the SDK. The one exception is `mcp-types`, the wire-types package released in lockstep with `mcp`: each `mcp` release requires exactly its own version of it, so it is the other half of the SDK rather than an independent constraint. | ||
|
|
||
| ## When a floor moves | ||
|
|
||
| A floor is raised only when the SDK starts relying on something that first appeared in that version — not because the dependency published a security advisory. The `>=` bound already lets, and expects, you to run the newest release your other constraints allow, so a higher floor would only shrink the environments the SDK installs into; nor does the SDK add code to work around a dependency's vulnerability, since the fix belongs upstream and in your lockfile ([background](https://github.com/Kludex/uvicorn/discussions/2643), [python-sdk#1552](https://github.com/modelcontextprotocol/python-sdk/issues/1552)). Adding a new runtime dependency, or moving one to its next major version, is decided in an issue before the pull request. Which of these may ship in a minor release is set by the [versioning policy](https://py.sdk.modelcontextprotocol.io/versioning/); floor raises are called out in the release notes. | ||
|
|
||
| ## Automated updates | ||
|
|
||
| [Dependabot](https://github.com/modelcontextprotocol/python-sdk/blob/main/.github/dependabot.yml) opens monthly, grouped pull requests for the `uv` lockfile and for GitHub Actions. These refresh the versions the SDK is developed and tested against; the requirements published to PyPI move only under the rules above. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,21 @@ | ||
| # Roadmap | ||
|
|
||
| The SDK's work is organized by MCP specification revision, with one GitHub project board per revision; each item is an issue or pull request you can follow. | ||
|
|
||
| ## The 2026-07-28 revision | ||
|
|
||
| v2 implements the [2026-07-28 specification](https://modelcontextprotocol.io/specification/2026-07-28) and negotiates back to every earlier revision. Board: **[python-sdk · 2026-07-28 spec](https://github.com/orgs/modelcontextprotocol/projects/42)** (tracking issue [#2891](https://github.com/modelcontextprotocol/python-sdk/issues/2891)); the cross-SDK view is [2026-07-28 Spec Implementation](https://github.com/orgs/modelcontextprotocol/projects/41). Still open there: the capabilities API and `server/discover` handler ([#2896](https://github.com/modelcontextprotocol/python-sdk/issues/2896)). | ||
|
|
||
| ## Not yet implemented | ||
|
|
||
| The extensions and optional client-auth mechanisms this SDK does not implement yet are tracked as the entries in the conformance suite's expected-failures baseline, [`.github/actions/conformance/expected-failures.yml`](https://github.com/modelcontextprotocol/python-sdk/blob/main/.github/actions/conformance/expected-failures.yml), which burns down as each lands: | ||
|
Check warning on line 11 in docs/roadmap.md
|
||
|
maxisbey marked this conversation as resolved.
Resolved
|
||
|
|
||
| * **Tasks extension** (`io.modelcontextprotocol/tasks`, [SEP-2663](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/seps/2663-tasks-extension.md)) — deferred at 2.0 because the 2026-07-28 design is wire-incompatible with the earlier in-core Tasks; tracked in [#2806](https://github.com/modelcontextprotocol/python-sdk/issues/2806). | ||
| * **DPoP-bound access tokens** ([SEP-1932](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1932)) in the OAuth client. | ||
| * **The workload-identity `jwt-bearer` grant** in the OAuth client. | ||
|
|
||
| Everything else — bugs and smaller features — lives in the [issue tracker](https://github.com/modelcontextprotocol/python-sdk/issues), prioritized `P0`–`P3`. The SDK aims to release support for each new specification revision alongside that revision. | ||
|
|
||
| ## The previous major | ||
|
|
||
| `v1.x` is a maintenance line: critical bug fixes and security fixes only. Support terms are in [Versioning and support policy](versioning.md#support-and-announcements); the path off it is the **[Migration Guide](migration.md)**. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,35 @@ | ||
| # Versioning and support policy | ||
|
|
||
| What a version number of `mcp` promises: which changes can arrive in a minor release, which wait for a major, how deprecations are announced, and which release lines are supported. | ||
|
|
||
| ## The version number | ||
|
|
||
| [Semantic Versioning](https://semver.org/) semantics in [PEP 440](https://peps.python.org/pep-0440/) syntax, taken from the git tag: in `2.X.Y`, **X** (minor) carries new functionality and every non-breaking change, **Y** (patch) carries bug fixes only, and a breaking change to the public API lands only in a new **major**. Pre-releases are cut from `main` as `aN`/`bN`/`rcN`; installers prefer final releases by default, so an unpinned `pip install mcp` stays on a stable release whenever one satisfies your requirement. `mcp` and its wire-types package `mcp-types` release in lockstep, each `mcp` requiring exactly the matching `mcp-types`. | ||
|
|
||
| ## The public API | ||
|
|
||
| The promise covers every name exported by `mcp` and `mcp_types` (their `__all__`), the import paths, signatures, and behavior documented on this site and in the [API Reference](api/mcp/index.md). It does not cover underscore-prefixed names, undocumented modules, or the wording of log lines, warnings, and exception messages (their types and documented raise conditions are covered). APIs labelled **provisional** (for example the middleware chain) may still change in a minor release; **experimental** APIs are opt-in previews. | ||
|
|
||
| ## Breaking and non-breaking changes | ||
|
|
||
| Held for the next major: | ||
|
|
||
| * removing or renaming a public name, | ||
| * changing a signature, return type, raised exception type, or documented behavior so that working code stops working, | ||
| * removing a documented import path, extra, or CLI command. | ||
|
|
||
| Allowed in a minor: | ||
|
|
||
| * additions — functions, defaulted parameters, classes, fields, enum members, | ||
| * changes to provisional or experimental APIs, | ||
| * new deprecation warnings, and the eventual removal of protocol features the specification has retired, | ||
| * raising a dependency floor the SDK needs (see the [dependency policy](https://github.com/modelcontextprotocol/python-sdk/blob/main/DEPENDENCY_POLICY.md)) when the dependency's changes don't reach you through the SDK's API, or dropping a Python version after its upstream end-of-life — both called out in the release notes, | ||
| * bug fixes, including ones that make the SDK match its documented or specified behavior. | ||
|
|
||
| ## Deprecations | ||
|
|
||
| **SDK APIs** are deprecated before removal: they keep working for at least one minor release, marked with [`typing_extensions.deprecated`](https://typing-extensions.readthedocs.io/en/latest/#typing_extensions.deprecated) wherever Python can carry the marker (docstring and migration guide otherwise), and are removed only in a major. **Protocol features** the specification retires keep their implementation through the spec's deprecation window and warn with `MCPDeprecationWarning`, a `UserWarning` subclass that shows by default; what still functions depends on the revision a connection negotiated — see [Deprecated features](deprecated.md). | ||
|
|
||
| ## Support and announcements | ||
|
|
||
| Two lines are maintained and only the newest release of each receives fixes: **2.x** (`main`) gets bug fixes, security fixes, and features; **1.x** ([`v1.x`](https://github.com/modelcontextprotocol/python-sdk/tree/v1.x)) gets critical bug fixes and security fixes. [SECURITY.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/SECURITY.md) has the reporting process. Every release publishes notes on [GitHub Releases](https://github.com/modelcontextprotocol/python-sdk/releases); every breaking change between majors is documented in the [Migration Guide](migration.md) before it merges; and pull requests that make one carry the `breaking change` label. | ||
|
maxisbey marked this conversation as resolved.
Resolved
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.