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

Add governance documentation for SEP-1730 (#808)

Browse source 
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 <dariusz.jedrzejczyk@broadcom.com>
This commit is contained in:
Dariusz Jędrzejczyk 2026-02-20 18:11:26 +01:00 • committed by GitHub
commit 72f9da91a2
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 139 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

22
.github/dependabot.yml vendored Normal file
View file

@ -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'

26
DEPENDENCY_POLICY.md Normal file
View file

@ -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`).

45
ROADMAP.md Normal file
View file

@ -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

46
VERSIONING.md Normal file
View file

@ -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.