Skip to content

Commit 4ff0569

Browse files
authored
Merge branch 'main' into dgarnier/streamable-double-complete
2 parents 42978c0 + 2de7fa9 commit 4ff0569

11 files changed

Lines changed: 1127 additions & 15 deletions

File tree

‎.github/pull_request_template.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
<!--
2+
Pull requests from outside the maintainer team need to link an open issue that
3+
a maintainer has assigned to you (or one labeled `help wanted`); others are
4+
closed automatically until that's in place. See CONTRIBUTING.md for details.
5+
-->
6+
7+
- Link the issue with `Fixes #N`, or `Updates #N` for a partial fix. You must be
8+
assigned to that issue (or it must be labeled `help wanted`).
9+
- Describe the change at a high level: why it is needed, and anything that is
10+
not obvious from the diff.

‎.github/scripts/pr_intake_gate.js‎

Lines changed: 310 additions & 0 deletions
Large diffs are not rendered by default.
Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# PR intake gate — see CONTRIBUTING.md ("How pull requests get in") for the
2+
# policy and .github/scripts/pr_intake_gate.js for the rules as applied.
3+
#
4+
# In short: a PR from someone without triage rights stays open only if it links
5+
# an open issue here that is assigned to them (or labeled `help wanted`);
6+
# otherwise it is labeled `missing-issue-link`, gets one comment, and is closed,
7+
# and it reopens automatically once the author is assigned. Drafts are gated
8+
# too; bots are skipped. A triage+ user reopening the PR, removing the label,
9+
# or adding `bypass-issue-check` overrides.
10+
#
11+
# Operating it:
12+
# - Live by default. To pause it without a revert, set the repository
13+
# variable PR_GATE_ENFORCE to "false": runs then only log their verdicts.
14+
# - PRs below the number in the job `if:` predate the gate and are ignored
15+
# unless evaluated by hand: `gh workflow run require-linked-issue.yml -f pr_number=N`.
16+
#
17+
# Security: pull_request_target runs with a write token in the base repo's
18+
# context, and GitHub takes both this file and the checkout from the default
19+
# branch whatever the PR targets. The job checks out only that, for the script,
20+
# and never fetches, builds, or runs anything from the pull request.
21+
#
22+
# Adapted from modelcontextprotocol/go-sdk's require-linked-issue.yml, itself
23+
# adapted from modelcontextprotocol/python-sdk's.
24+
25+
name: Require Linked Issue
26+
27+
on:
28+
pull_request_target: # checks out the default branch only and never runs PR code — see header
29+
types: [opened, edited, reopened, ready_for_review, labeled, unlabeled]
30+
issues:
31+
types: [assigned]
32+
workflow_dispatch:
33+
inputs:
34+
pr_number:
35+
description: PR number to evaluate
36+
required: true
37+
type: number
38+
39+
permissions: {}
40+
41+
jobs:
42+
gate:
43+
name: Evaluate
44+
# Routing only; the rules are in the script. PR events run at or above the
45+
# grandfathering floor, or for PRs the gate has already labeled; label
46+
# events only for the two labels the gate cares about.
47+
if: >-
48+
github.event_name == 'workflow_dispatch' ||
49+
(github.event_name == 'issues' && !github.event.issue.pull_request && github.event.issue.state == 'open') ||
50+
(
51+
github.event_name == 'pull_request_target' &&
52+
(
53+
github.event.pull_request.number >= 1289 ||
54+
contains(github.event.pull_request.labels.*.name, 'missing-issue-link') ||
55+
github.event.action == 'unlabeled'
56+
) &&
57+
(github.event.action != 'unlabeled' || github.event.label.name == 'missing-issue-link') &&
58+
(github.event.action != 'labeled' || github.event.label.name == 'bypass-issue-check')
59+
)
60+
runs-on: ubuntu-latest
61+
timeout-minutes: 10
62+
concurrency:
63+
group: require-linked-issue-${{ github.event.pull_request.number || inputs.pr_number || format('issue-{0}-{1}', github.event.issue.number, github.event.assignee.login) }}
64+
cancel-in-progress: false
65+
permissions:
66+
contents: read # check out the gate script from the default branch
67+
issues: write # read linked issues; label and comment on the PR
68+
pull-requests: write # close and reopen the PR
69+
env:
70+
ENFORCE: ${{ vars.PR_GATE_ENFORCE != 'false' && 'true' || 'false' }} # kill switch: set the variable to "false" to go log-only
71+
PR_NUMBER_INPUT: ${{ inputs.pr_number }}
72+
steps:
73+
- name: Check out the gate script (default branch)
74+
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
75+
with:
76+
persist-credentials: false
77+
sparse-checkout: .github/scripts
78+
79+
- name: Evaluate
80+
uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
81+
with:
82+
script: |
83+
const run = require('./.github/scripts/pr_intake_gate.js');
84+
await run({ github, context, core });

‎CHANGELOG.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,11 @@ Versioning follows [Semantic Versioning](https://semver.org/); see
1919

2020
## Unreleased (2.2.0)
2121

22+
- Preview of a stateless server for the **2026-07-28** MCP specification revision, in
23+
`io.modelcontextprotocol.modern`, with Servlet (Streamable HTTP) and STDIO transports. It supports
24+
`server/discover`, multi round-trip requests with sealed `requestState`, `subscriptions/listen`, caching
25+
hints, required client capabilities and SEP-2243 `Mcp-Param` header validation. The API may change in minor
26+
releases until 3.0. See [MCP Server (2026-07-28)](docs/server-modern.md).
2227
- Add `McpTransportContext.putAll(Map)`, returning a context that combines an
2328
existing context with additional entries, which take precedence.
2429
- `McpTransportContext` no longer compares contexts by their contents in

‎CONTRIBUTING.md‎

Lines changed: 64 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,57 @@
33
Thank you for your interest in contributing to the Model Context Protocol Java SDK!
44
This document outlines how to contribute to this project.
55

6+
## Before you start
7+
8+
> [!IMPORTANT]
9+
> **The most useful contribution is a good issue.** Pull requests from outside
10+
> the maintainer team are closed automatically unless they link an issue
11+
> assigned to their author.
12+
13+
### Why issues rather than pull requests
14+
15+
Coding agents can now turn any open issue into a plausible-looking pull request within
16+
hours, and generate speculative bug reports from a scan of the code, so we
17+
receive far more issues and PRs than we can read carefully. Reviewing a PR
18+
properly still takes as long as it always did. When an issue is well described,
19+
it is usually quicker for a maintainer to write a fix that fits the codebase
20+
than to review and reshape someone else's.
21+
22+
What we can't produce ourselves is your context: what you were doing, what you
23+
expected, a minimal reproduction, and the system where it broke.
24+
That is what a good issue carries, so that is what we ask for first.
25+
26+
### How pull requests get in
27+
28+
A PR from someone outside the maintainer team stays open when both of these
29+
hold:
30+
31+
1. Its description links an open issue in this repository with `Fixes #123`
32+
(or `Closes`, `Resolves`), or with `Updates #123` for a partial fix.
33+
2. A maintainer has assigned that issue to you, or the issue carries the [`help
34+
wanted`](https://github.com/modelcontextprotocol/java-sdk/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22help%20wanted%22)
35+
label, which means we'd welcome a PR for it from anyone.
36+
37+
Otherwise a bot labels the PR `missing-issue-link`, leaves a comment explaining
38+
this, and closes it. Drafts are treated the same way. If that happens to yours,
39+
there's no need to open a new one: it reopens automatically as soon as a
40+
maintainer assigns you the issue, or when you edit the description to link one
41+
that qualifies. While it's closed, push updates as new commits rather than
42+
force-pushing, since GitHub can't reopen a PR whose branch has been rewritten.
43+
This applies to small fixes like typos too; for those, an issue pointing at the
44+
problem is all we need.
45+
46+
Whether to assign an issue, and to whom, is a maintainer call, and it depends
47+
on our capacity at the time as much as on the change itself. Comments that only
48+
ask to be assigned don't factor into it, so please skip those (and don't have
49+
an agent post them). What does help is engaging with the issue itself:
50+
confirming the reproduction, asking about the intended behavior, or briefly
51+
describing the approach you'd take. If you reported the issue and would like to
52+
fix it yourself, say so in the issue.
53+
54+
Maintainers can override the check by reopening the PR, by removing its
55+
`missing-issue-link` label, or by adding `bypass-issue-check`.
56+
657
## Prerequisites
758

859
The following software is required to work on the codebase:
@@ -69,25 +120,23 @@ git checkout -b feature/your-feature-name
69120

70121
## Submitting Changes
71122

72-
Please don't submit pull requests:
123+
**Before submitting a PR, please first open an issue and wait until it is assigned to you.**
73124

74-
- With GitHub accounts managed by autonomous AI bots
75-
- For already assigned issues (as the assignee is or plans to work on it)
125+
Please don't submit issues or pull requests with GitHub accounts managed by autonomous AI bots.
76126

77127
When submitting changes:
78128

79-
1. For non-trivial changes, please clarify with the maintainers in an issue whether
80-
you can contribute the change and the desired scope of the change.
81-
2. For trivial changes (for example a couple of lines or documentation changes) there
82-
is no need to open an issue first.
83-
3. Maintainers will triage issues and act on them. There is no such guarantee on pull requests.
84-
PRs opened without being discussed in an issue MAY be ignored, and maintainers reserve the right
85-
to close these PRs without justification.
86-
4. Push your changes to your fork.
87-
5. Submit a pull request to the main repository.
88-
6. Follow the pull request template.
89-
7. Wait for review.
90-
8. For any follow-up work, please add new commits instead of force-pushing. This will
129+
1. Every PR from outside the maintainer team must link an issue that a maintainer
130+
has assigned to you, or one labeled `help wanted`, as described in [How pull
131+
requests get in](#how-pull-requests-get-in). For changes that don't relate to an
132+
existing issue, file an issue first, clarify the desired scope of the change with
133+
the maintainers, and wait for it to be assigned before opening a PR.
134+
2. Maintainers will triage issues and act on them. There is no such guarantee on pull requests.
135+
3. Push your changes to your fork.
136+
4. Submit a pull request to the main repository.
137+
5. Follow the pull request template.
138+
6. Wait for review.
139+
7. For any follow-up work, please add new commits instead of force-pushing. This will
91140
allow the reviewer to focus on incremental changes instead of having to restart the
92141
review process.
93142

‎ROADMAP.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@ The earlier **1.x and 0.x release lines receive security patches only** — no f
2525

2626
The next major version, **3.x**, will implement the [2026-07-28 MCP specification revision](https://modelcontextprotocol.io/specification/2026-07-28), including `server/discover` and the SEP-2575 stateless lifecycle. The first 3.0.0 milestone releases are planned for **September 2026**, tracked via a dedicated spec revision project board.
2727

28+
A preview of the 2026-07-28 server ships in **2.2.0** in the `io.modelcontextprotocol.modern` packages, alongside the 2.x server: stateless `McpServer` with Servlet and STDIO transports, `server/discover`, multi round-trip requests and `subscriptions/listen`. Its API may change until 3.0. A modern client and tasks are not yet implemented. See [MCP Server (2026-07-28)](docs/server-modern.md).
29+
2830
### SDK Tiering
2931

3032
The Java SDK is an official [Tier 2 SDK](https://modelcontextprotocol.io/community/sdk-tiers) committed to full protocol support: new spec revisions are implemented within the Tier 2 six-month window, with conformance continuously verified against the [MCP conformance suite](https://github.com/modelcontextprotocol/conformance) in CI. Once caught up on the most recent specification revision, we aim for Tier 1: fully supporting new specification features on the day of their release.

‎docs/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ enables standardized integration between AI models and tools.
3333
- WebMVC SSE server transport for servlet-based HTTP streaming
3434
- WebMVC Streamable HTTP server transport
3535
- WebMVC Stateless server transport
36+
- Preview of a stateless server for the [2026-07-28](https://modelcontextprotocol.io/specification/2026-07-28) specification revision, with `server/discover`, multi round-trip requests and `subscriptions/listen` (see [MCP Server (2026-07-28)](server-modern.md))
3637
- Supports Synchronous and Asynchronous programming paradigms
3738
- Pluggable JSON serialization (Jackson 2.x and Jackson 3.x)
3839
- Pluggable authorization hooks for server security

‎docs/overview.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,11 @@ Key Interactions:
3636
- **Message Flow**: JSON-RPC message handling with validation, type-safe response processing, and error handling.
3737
- **Resource Management**: Resource discovery, URI template-based access, subscription system, and content retrieval.
3838

39+
!!! note "2026-07-28 specification"
40+
The architecture and interactions above describe the classic client and server. The preview server for the stateless
41+
2026-07-28 revision, in `io.modelcontextprotocol.modern`, has no sessions: a single `McpServer` dispatches
42+
each request to features backed by repositories you implement. See [MCP Server (2026-07-28)](server-modern.md).
43+
3944
## Module Structure
4045

4146
The SDK is organized into modules to separate concerns and allow adopters to bring in only what they need:

0 commit comments

Comments
 (0)