From 6c53f18be682c754f6e71ad49a94a8ef85f6ca60 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dariusz=20J=C4=99drzejczyk?= Date: Fri, 20 Feb 2026 17:53:21 +0100 Subject: [PATCH] Add governance documentation for SEP-1730 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add governance documentation required for SEP-1730 tier compliance: - DEPENDENCY_POLICY.md: Conservative update policy for Maven dependencies - VERSIONING.md: SemVer policy with breaking/non-breaking definitions - ROADMAP.md: 2025-11-25 spec implementation focus and v1.x development - .github/dependabot.yml: Monthly updates with frozen production dependencies This mirrors the TypeScript SDK PR structure while being adapted for the Java context. Signed-off-by: Dariusz Jędrzejczyk --- .github/dependabot.yml | 22 ++++++++++++++++++++ DEPENDENCY_POLICY.md | 26 ++++++++++++++++++++++++ ROADMAP.md | 45 +++++++++++++++++++++++++++++++++++++++++ VERSIONING.md | 46 ++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 139 insertions(+) create mode 100644 .github/dependabot.yml create mode 100644 DEPENDENCY_POLICY.md create mode 100644 ROADMAP.md create mode 100644 VERSIONING.md diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 000000000..c25de745b --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,22 @@ +version: 2 +updates: + - package-ecosystem: 'github-actions' + directory: '/' + schedule: + interval: monthly + - package-ecosystem: 'maven' + directory: '/' + schedule: + interval: monthly + open-pull-requests-limit: 10 + ignore: + # Freeze production dependencies of mcp-core + - dependency-name: 'org.slf4j:slf4j-api' + - dependency-name: 'com.fasterxml.jackson.core:jackson-annotations' + - dependency-name: 'tools.jackson.core:jackson-databind' + - dependency-name: 'io.projectreactor:reactor-bom' + - dependency-name: 'io.projectreactor:reactor-core' + - dependency-name: 'jakarta.servlet:jakarta.servlet-api' + # mcp-json-jackson2 and mcp-json-jackson3 dependencies + - dependency-name: 'com.fasterxml.jackson.core:jackson-databind' + - dependency-name: 'com.networknt:json-schema-validator' \ No newline at end of file diff --git a/DEPENDENCY_POLICY.md b/DEPENDENCY_POLICY.md new file mode 100644 index 000000000..5714a6b57 --- /dev/null +++ b/DEPENDENCY_POLICY.md @@ -0,0 +1,26 @@ +# Dependency Policy + +As a library consumed by downstream projects, the MCP Java 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). +- A bug in a dependency directly affects the SDK. +- A new dependency feature is needed for SDK development. +- A dependency drops support for a Java 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 scheduled version bumps for production Maven 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 Maven 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`). +- **Maven dependencies** are monitored via Dependabot on a monthly schedule for non-production updates only (see `.github/dependabot.yml`). diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 000000000..b5b7dc4d7 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,45 @@ +# 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/views/1). + +## Current Focus Areas + +### 2025-11-25 Spec Implementation + +The Java SDK is actively implementing the [2025-11-25 MCP specification revision](https://github.com/orgs/modelcontextprotocol/projects/26/views/1). + +Key features in this revision include: + +- **Tasks**: Experimental support for tracking durable requests with polling and deferred result retrieval +- **Tool calling in sampling**: Support for `tools` and `toolChoice` parameters +- **URL mode elicitation**: Client-side URL elicitation requests +- **Icons metadata**: Servers can expose icons for tools, resources, resource templates, and prompts +- **Enhanced schemas**: JSON Schema 2020-12 as default, improved enum support, default values for elicitation +- **Security improvements**: Updated security best practices, enhanced authorization flows, enabling OAuth integrations + +See the full [changelog](https://modelcontextprotocol.io/specification/2025-11-25/changelog) for details. + +### Tier 1 SDK Support + +Once we catch up on the most recent MCP specification revision we aim to fully support all the upcoming specification features on the day of its release. + +### v1.x Development + +The Java SDK is currently in active development as v1.x, following a recent stable 1.0.0 release. The SDK provides: + +- MCP protocol implementation +- Synchronous and asynchronous programming models +- Multiple transport options (STDIO, HTTP/SSE, Servlet) +- Pluggable JSON serialization (Jackson 2 and Jackson 3) + +Development is tracked via [GitHub Issues](https://github.com/modelcontextprotocol/java-sdk/issues) and [GitHub Projects](https://github.com/orgs/modelcontextprotocol/projects). + +### Future Versions + +Major version updates will align with MCP specification changes and breaking API changes as needed. The SDK is designed to evolve with the Java ecosystem, including: + +- Virtual Threads and Structured Concurrency support +- Additional transport implementations +- Performance optimizations diff --git a/VERSIONING.md b/VERSIONING.md new file mode 100644 index 000000000..331c6d05e --- /dev/null +++ b/VERSIONING.md @@ -0,0 +1,46 @@ +# Versioning Policy + +The MCP Java SDK (`io.modelcontextprotocol.sdk`) 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 (class, interface, method, or constant). +- Changing the signature of a public method in a way that breaks existing callers (removing parameters, changing required/optional status, changing types). +- Removing or renaming a public interface method or field. +- Changing the behavior of an existing API in a way that breaks documented contracts. +- Dropping support for a Java LTS version. +- Removing support for a transport type. +- Changes to the MCP protocol version that require client/server code changes. +- Removing a module from the SDK. + +The following are **not** considered breaking: + +- Adding new methods with default implementations to interfaces. +- Adding new public APIs, classes, interfaces, or methods. +- Adding new optional parameters to existing methods (through method overloading). +- 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 test dependencies or build tooling. +- Adding new modules to the SDK. + +## 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 `@Deprecated` annotations, which surface warnings through Java tooling and IDEs. +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`. + +## Maven Coordinates + +All SDK modules share the same version number and are released together. The BOM (`mcp-bom`) provides dependency management for all SDK modules to ensure version consistency.