Files

64 lines
3.2 KiB
Markdown

# 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)
```