From 301cfdf47a76fb3d79a53dbe25caa8cc880d1840 Mon Sep 17 00:00:00 2001 From: Felix Weinberger Date: Mon, 9 Feb 2026 14:35:58 +0000 Subject: [PATCH 1/3] ci: backport weekly lockfile update and dependabot from main --- .github/dependabot.yml | 10 +++++ .github/workflows/weekly-lockfile-update.yml | 40 ++++++++++++++++++++ 2 files changed, 50 insertions(+) create mode 100644 .github/dependabot.yml create mode 100644 .github/workflows/weekly-lockfile-update.yml diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 000000000..00dc69828 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,10 @@ +version: 2 +updates: + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: monthly + groups: + github-actions: + patterns: + - "*" diff --git a/.github/workflows/weekly-lockfile-update.yml b/.github/workflows/weekly-lockfile-update.yml new file mode 100644 index 000000000..10be50302 --- /dev/null +++ b/.github/workflows/weekly-lockfile-update.yml @@ -0,0 +1,40 @@ +name: Weekly Lockfile Update + +on: + workflow_dispatch: + schedule: + # Every Thursday at 8:00 UTC + - cron: "0 8 * * 4" + +permissions: + contents: write + pull-requests: write + +jobs: + update-lockfile: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v6 + + - uses: astral-sh/setup-uv@v7.2.1 + with: + version: 0.9.5 + + - name: Update lockfile + run: | + echo '## Updated Dependencies' > pr_body.md + echo '' >> pr_body.md + echo '```' >> pr_body.md + uv lock --upgrade 2>&1 | tee -a pr_body.md + echo '```' >> pr_body.md + + - name: Create pull request + uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0 # v7 + with: + commit-message: "chore: update uv.lock with latest dependencies" + title: "chore: weekly dependency update" + body-path: pr_body.md + branch: weekly-lockfile-update-v1x + delete-branch: true + add-paths: uv.lock + labels: dependencies From 2dfd474aba0b1da0c0406020e6bb437ca5f77dde Mon Sep 17 00:00:00 2001 From: Felix Weinberger Date: Mon, 9 Feb 2026 14:36:18 +0000 Subject: [PATCH 2/3] docs: add dependency update and triage policies to CONTRIBUTING.md --- CONTRIBUTING.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c18937f5b..0d45d01f1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -64,6 +64,28 @@ pre-commit run --all-files 9. Submit a pull request to the same branch you branched from +## Dependency Update Policy + +The lockfile is updated automatically every Thursday at 08:00 UTC by the [`weekly-lockfile-update.yml`](.github/workflows/weekly-lockfile-update.yml) workflow, which runs `uv lock --upgrade` and opens a PR. GitHub Actions versions are updated monthly via [Dependabot](.github/dependabot.yml). + +When bumping a dependency version manually, update the constraint in `pyproject.toml` then run `uv lock --resolution lowest-direct` (see [RELEASE.md](RELEASE.md)). + +Security-relevant dependency updates (P0) are applied within 7 days of public disclosure and backported to active release branches. + +The SDK currently supports Python 3.10 through 3.13. New CPython releases are supported within one minor SDK release of their stable release date. + +## Triage Process + +New issues are triaged by a maintainer within 2 business days. Triage means adding an appropriate label and determining whether the issue is valid. + +Issues are labeled per the [SDK Tiering System](https://modelcontextprotocol.io/community/sdk-tiers): + +- **Type** (pick one): `bug`, `enhancement`, `question` +- **Status** (pick one): `needs confirmation`, `needs repro`, `ready for work`, `good first issue`, `help wanted` +- **Priority** (if actionable): `P0`, `P1`, `P2`, `P3` + +P0 issues are security vulnerabilities (CVSS ≥ 7.0) or core functionality failures that prevent basic MCP operations (connection establishment, message exchange, or use of core primitives). P0 issues must be resolved within 7 days. + ## Code Style - We use `ruff` for linting and formatting From 6ba15b9993f3691117af43e36176eb3fbf281f42 Mon Sep 17 00:00:00 2001 From: Felix Weinberger Date: Wed, 18 Feb 2026 15:47:32 +0000 Subject: [PATCH 3/3] Add VERSIONING.md, ROADMAP.md, and DEPENDENCY_POLICY.md Add standalone policy/governance files to match the TypeScript SDK's structure (PR #1547). These files are checked by the tier-check CLI. - VERSIONING.md: semver policy adapted for Python (compatible-release specifiers, DeprecationWarning, Python version support) - ROADMAP.md: spec tracking and v2 milestones (shared across SDKs) - DEPENDENCY_POLICY.md: extracted from CONTRIBUTING.md and expanded with policy rationale (update triggers, automated tooling, pinning) - CONTRIBUTING.md: updated to reference standalone DEPENDENCY_POLICY.md --- .github/workflows/weekly-lockfile-update.yml | 4 +- CONTRIBUTING.md | 2 +- DEPENDENCY_POLICY.md | 30 +++++++++++++++ ROADMAP.md | 22 +++++++++++ VERSIONING.md | 40 ++++++++++++++++++++ 5 files changed, 95 insertions(+), 3 deletions(-) create mode 100644 DEPENDENCY_POLICY.md create mode 100644 ROADMAP.md create mode 100644 VERSIONING.md diff --git a/.github/workflows/weekly-lockfile-update.yml b/.github/workflows/weekly-lockfile-update.yml index 10be50302..c44eaf5ac 100644 --- a/.github/workflows/weekly-lockfile-update.yml +++ b/.github/workflows/weekly-lockfile-update.yml @@ -14,9 +14,9 @@ jobs: update-lockfile: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v6 + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6 - - uses: astral-sh/setup-uv@v7.2.1 + - uses: astral-sh/setup-uv@803947b9bd8e9f986429fa0c5a41c367cd732b41 # v7.2.1 with: version: 0.9.5 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0d45d01f1..379c47c12 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -66,7 +66,7 @@ pre-commit run --all-files ## Dependency Update Policy -The lockfile is updated automatically every Thursday at 08:00 UTC by the [`weekly-lockfile-update.yml`](.github/workflows/weekly-lockfile-update.yml) workflow, which runs `uv lock --upgrade` and opens a PR. GitHub Actions versions are updated monthly via [Dependabot](.github/dependabot.yml). +See [DEPENDENCY_POLICY.md](DEPENDENCY_POLICY.md) for the full dependency update policy. When bumping a dependency version manually, update the constraint in `pyproject.toml` then run `uv lock --resolution lowest-direct` (see [RELEASE.md](RELEASE.md)). diff --git a/DEPENDENCY_POLICY.md b/DEPENDENCY_POLICY.md new file mode 100644 index 000000000..7db632e7f --- /dev/null +++ b/DEPENDENCY_POLICY.md @@ -0,0 +1,30 @@ +# Dependency Policy + +As a library consumed by downstream projects, the MCP Python 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. + +## Update Triggers + +Dependencies are updated when: + +- A **security vulnerability** is disclosed (via GitHub security alerts or PyPI advisories) in a dependency that directly affects the SDK's functionality or its consumers. +- A bug in a dependency directly affects the SDK. +- A new dependency feature is needed for SDK development. +- A dependency drops support for a Python version the SDK still targets. + +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 ad-hoc version bumps for PyPI 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 + +- **Lockfile refresh**: The lockfile is updated automatically every Thursday at 08:00 UTC by the [`weekly-lockfile-update.yml`](.github/workflows/weekly-lockfile-update.yml) workflow, which runs `uv lock --upgrade` and opens a PR. This does not alter the minimum or maximum versions for dependencies of the `mcp` package itself. +- **GitHub security updates** are enabled at the repository level and automatically open pull requests for 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 monthly schedule (see `.github/dependabot.yml`). + +## Pinning and Ranges + +Production dependencies use compatible-release specifiers (`~=`) or lower-bound constraints (`>=`) to allow compatible updates. Exact versions are pinned only when necessary to work around a specific issue. The lockfile (`uv.lock`) records exact resolved versions for reproducible installs. diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 000000000..9f9bb31e0 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,22 @@ +# Roadmap + +## Spec Implementation Tracking + +The SDK tracks implementation of MCP spec components via GitHub Projects, with a dedicated project board for each spec revision. For example, see the [2025-11-25 spec revision board](https://github.com/orgs/modelcontextprotocol/projects/26). + +## Current Focus Areas + +### Next Spec Revision + +The next MCP specification revision is being developed in the [protocol repository](https://github.com/modelcontextprotocol/modelcontextprotocol). Key areas expected in the next revision include extensions and stateless transports. + +The SDK has historically implemented spec changes promptly as they are finalized, with dedicated project boards tracking component-level progress for each revision. + +### v2 + +A major version of the SDK is in active development, tracked via [GitHub Project](https://github.com/orgs/modelcontextprotocol/projects/31). Target milestones: + +- **Alpha**: ~mid-March 2026 +- **Beta**: ~May 2026 + +The v2 release is planned to align with the next spec release, expected around mid-2026. diff --git a/VERSIONING.md b/VERSIONING.md new file mode 100644 index 000000000..a89d4c3b8 --- /dev/null +++ b/VERSIONING.md @@ -0,0 +1,40 @@ +# Versioning Policy + +The MCP Python SDK (`mcp`) follows [Semantic Versioning 2.0.0](https://semver.org/). + +## 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 dataclass/TypedDict field. +- Changing the behavior of an existing API in a way that breaks documented contracts. +- Dropping support for a Python version that is still receiving security updates. +- Removing support for a transport type. +- Changes to the MCP protocol version that require client/server code changes. + +The following are **not** considered breaking: + +- Adding new optional parameters to existing functions. +- Adding new exports, types, or classes. +- 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 features. +- Changes to dev dependencies or build tooling. + +## How Breaking Changes Are Communicated + +1. **Changelog**: All breaking changes are documented in the GitHub release notes with migration instructions. +2. **Deprecation**: When feasible, APIs are deprecated for at least one minor release before removal using `warnings.warn()` with `DeprecationWarning`, which surfaces warnings at runtime and through static analysis tooling. +3. **Migration guide**: Major version releases include a migration guide describing what changed and how to update. +4. **PR labels**: Pull requests containing breaking changes are labeled with `breaking change`.