Add mcp-stateless module: migrate an MCP server from the 2025 stateful protocol to 2026-07-28 on Spring AI 2.1.0
Co-Authored-By: Claude Sonnet 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017ic4b4tJPXfq5UyiLSFr49
This commit is contained in:
co-authored by
Claude Sonnet 5.5
parent
3aa20a1dce
commit
26e0a3875a
@@ -0,0 +1,63 @@
|
||||
# mcp-stateless
|
||||
|
||||
Companion module for the ankurm.com post **MCP 2026-07-28 for Java Developers: Migrating an MCP Server to the Stateless Spec**.
|
||||
|
||||
One order-lookup MCP server that runs as a 2025-era stateful server (`legacy` profile) or as a 2026-07-28 stateless server
|
||||
(`modern` profile). The tools are the same `@McpTool` beans in both. The tests start real instances, put a plain
|
||||
round-robin proxy in front of them and write what happened to `output/`.
|
||||
|
||||
## Versions (verified on Maven Central, 2026-11-22)
|
||||
|
||||
| Component | Version | Note |
|
||||
|---|---|---|
|
||||
| Spring Boot | 4.2.0 | GA 2026-11-19 |
|
||||
| Spring AI `spring-ai-starter-mcp-server-webmvc` | 2.1.0 | GA 2026-11-19. `protocol: MODERN` first exists in 2.1.0-RC2; it is absent from 2.0.x and 2.1.0-RC1 |
|
||||
| MCP Java SDK `io.modelcontextprotocol.sdk:mcp` | 2.2.0 | brought in by Spring AI. The `io.modelcontextprotocol.modern` package first appears in 2.2.0-M1; 2.1.0 has none |
|
||||
| JDK | 25 LTS | Temurin 25.0.5 |
|
||||
|
||||
## Run
|
||||
|
||||
```bash
|
||||
scripts/run-all.sh # all tests, regenerates output/
|
||||
scripts/run.sh modern 8082 M1 # one 2026-07-28 server
|
||||
scripts/run.sh legacy 8081 L1 # one 2025-era server
|
||||
scripts/curl-modern.sh 8082 A-101 # a single stateless request
|
||||
```
|
||||
|
||||
## Profiles
|
||||
|
||||
| Profile | Property | Wire behaviour |
|
||||
|---|---|---|
|
||||
| `legacy` | `spring.ai.mcp.server.protocol=STREAMABLE` | `initialize`, `Mcp-Session-Id`, session held in server memory |
|
||||
| `modern` | `spring.ai.mcp.server.protocol=MODERN` | `server/discover`, `_meta` on every request, `Mcp-Method` / `Mcp-Name` headers, no session |
|
||||
|
||||
## Tools
|
||||
|
||||
| Tool | Profiles | Purpose |
|
||||
|---|---|---|
|
||||
| `order_status` | both | read-only lookup; reports which instance answered |
|
||||
| `cancel_order` | `modern` | asks for confirmation by returning `input_required` (multi-round-trip request) |
|
||||
|
||||
## Captured output (`output/`)
|
||||
|
||||
| File | Shows |
|
||||
|---|---|
|
||||
| `01-legacy-handshake.txt` | initialize, session id, a call without a session, an unknown session |
|
||||
| `02-legacy-behind-lb.txt` | two 2025 instances behind round-robin: 3 of 6 calls fail; affinity; instance stopped |
|
||||
| `03-modern-wire.txt` | `server/discover`, `tools/list`, `tools/call` with no session |
|
||||
| `04-modern-errors.txt` | header and body mismatches, wrong version, a 2025 `initialize`, a stray session header |
|
||||
| `05-modern-behind-lb.txt` | two 2026-07-28 instances behind round-robin, one stopped mid-run |
|
||||
| `06-modern-mrtr.txt` | `input_required`, `requestState`, a retry on another instance with and without a shared secret |
|
||||
| `07-both-versions.txt` | one URL, two generations, routed on `MCP-Protocol-Version` |
|
||||
| `08-sdk-modern-client.txt` | the 2.2.0 modern SDK client through round-robin |
|
||||
| `09-sdk-version-mismatch.txt` | what each SDK client says against the other generation's server |
|
||||
| `10-sdk-clients-through-router.txt` | both SDK clients through the version router |
|
||||
|
||||
## Layout
|
||||
|
||||
```
|
||||
src/main/java/com/ankurm/mcpstateless/ StatelessApp, OrderTools, CancelOrderTool
|
||||
src/main/resources/ application.yml, application-legacy.yml, application-modern.yml
|
||||
src/test/java/com/ankurm/mcpstateless/ one test class per transcript group
|
||||
src/test/java/.../support/ Wire (raw HTTP), Transcript, Instance, Proxy (the stand-in balancer)
|
||||
```
|
||||
Reference in New Issue
Block a user