diff --git a/README.md b/README.md index e5da0d1..beda750 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,7 @@ facts, so the build fails when a claim stops being true. | `mcp-sdk-plain` | Write an MCP Server with the Plain MCP Java SDK (No Spring): stdio and Streamable HTTP | tools, a resource and a resource template on the framework-free SDK, a fat jar over stdio and Streamable HTTP, wire-level transcripts, and a Spring AI client connecting to it | | `koog` | Koog: JetBrains' Kotlin AI Agent Framework on the JVM, Your First Agent with Tools in Java | a tool-calling agent, a strategy graph with a plain-Java node before the model, and the Spring Boot starter, tested against a scripted OpenAI-compatible endpoint, with tool-error, bad-argument, iteration-cap and Kotlin-BOM failure modes | | `claude-code-spring` | Claude Code for Java and Spring Boot Developers: CLAUDE.md, Skills, Hooks, MCP and IntelliJ | a Spring Boot 4.2 orders service with a complete committed Claude Code setup: `CLAUDE.md`, a path-scoped rule, two skills, four hooks (command guard, protected files, tests after edit, a Stop gate) run against real hook JSON, project-scoped `.mcp.json` generated by the real `claude mcp` CLI, and tests that lint the setup | +| `mcp-stateless` | MCP 2026-07-28 for Java Developers: Migrating an MCP Server to the Stateless Spec | one order server as a 2025-era stateful and a 2026-07-28 stateless Spring AI server, behind a round-robin balancer, with multi-round-trip requests, a version router and real SDK clients | ## Versions (verified on Maven Central, 2026-10-11) @@ -40,6 +41,7 @@ facts, so the build fails when a claim stops being true. | Kotlin `kotlin-stdlib` | 2.3.10 | the Spring Boot 3.5.16 BOM pins 1.9.25 and would win; the `koog` pom imports the Kotlin BOMs first | | Spring Boot (`claude-code-spring`) | 4.2.0 | GA 2026-11-19, verified on Maven Central 2026-11-21; `claude-code-spring` only | | Claude Code CLI | 2.1.330 | `claude mcp` run for `claude-code-spring/output/08`; the model-side behaviour is documented, not executed | +| Spring Boot / Spring AI / MCP Java SDK (`mcp-stateless`) | 4.2.0 / 2.1.0 / 2.2.0 | verified on Maven Central 2026-11-22; this module overrides the Spring versions above | | JDK | 25 LTS | | | JUnit | 6.1.3 | | diff --git a/mcp-stateless/README.md b/mcp-stateless/README.md new file mode 100644 index 0000000..6c2b5dc --- /dev/null +++ b/mcp-stateless/README.md @@ -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) +``` diff --git a/mcp-stateless/output/01-legacy-handshake.txt b/mcp-stateless/output/01-legacy-handshake.txt new file mode 100644 index 0000000..cebe389 --- /dev/null +++ b/mcp-stateless/output/01-legacy-handshake.txt @@ -0,0 +1,44 @@ +# 2025-era server (protocol STREAMABLE): the session lives in the server's memory +# Error bodies are shown without the Java stack trace the SDK serialises into them. + +## 1. tools/call with no session yet +> POST /mcp +> {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"order_status","arguments":{"orderId":"A-101"}}} +< 400 +< Content-Type: application/json +< {"jsonRpcError":{"code":-32601,"message":"Session ID missing"}} + +## 2. initialize +> POST /mcp +> {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"wire-test","version":"1"}}} +< 200 +< Mcp-Session-Id: +< Content-Type: application/json +< {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25","capabilities":{"completions":{},"logging":{},"prompts":{"listChanged":true},"resources":{"subscribe":false,"listChanged":true},"tools":{"listChanged":true}},"serverInfo":{"name":"orders","version":"1.0.0"},"instructions":"Order lookup server used to compare the 2025 and 2026-07-28 MCP protocol generations."}} + +## 3. notifications/initialized +> POST /mcp +> MCP-Protocol-Version: 2025-11-25 +> Mcp-Session-Id: +> {"jsonrpc":"2.0","method":"notifications/initialized"} +< 202 + +## 4. tools/call with the session +> POST /mcp +> MCP-Protocol-Version: 2025-11-25 +> Mcp-Session-Id: +> {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"order_status","arguments":{"orderId":"A-101"}}} +< 200 +< Content-Type: text/event-stream +< id: +< event:message +< data: {"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"order A-101 is SHIPPED (answered by instance L1)"}],"isError":false}} + +## 5. tools/call with a session id this server never issued +> POST /mcp +> MCP-Protocol-Version: 2025-11-25 +> Mcp-Session-Id: +> {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"order_status","arguments":{"orderId":"A-101"}}} +< 404 +< Content-Type: application/json +< {"jsonRpcError":{"code":-32603,"message":"Session not found: "}} diff --git a/mcp-stateless/output/02-legacy-behind-lb.txt b/mcp-stateless/output/02-legacy-behind-lb.txt new file mode 100644 index 0000000..84236b8 --- /dev/null +++ b/mcp-stateless/output/02-legacy-behind-lb.txt @@ -0,0 +1,55 @@ +# Two 2025-era instances behind a balancer: round-robin, then session affinity, then an instance dies +# PART A: plain round-robin. Request n goes to L1 when n is even and to L2 when n is odd. + +## A1. initialize +> POST balancer/mcp +> {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"wire-test","version":"1"}}} +< 200 +< Mcp-Session-Id: +< Content-Type: application/json +< X-Served-By: L1 +< {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25","capabilities":{"completions":{},"logging":{},"prompts":{"listChanged":true},"resources":{"subscribe":false,"listChanged":true},"tools":{"listChanged":true}},"serverInfo":{"name":"orders","version":"1.0.0"},"instructions":"Order lookup server used to compare the 2025 and 2026-07-28 MCP protocol generations."}} + +## A2. notifications/initialized +> POST balancer/mcp +> MCP-Protocol-Version: 2025-11-25 +> Mcp-Session-Id: +> {"jsonrpc":"2.0","method":"notifications/initialized"} +< 404 +< Content-Type: application/json +< X-Served-By: L2 +< {"jsonRpcError":{"code":-32603,"message":"Session not found: "}} + +# Six tools/call with the same session id, through the same balancer: +call 1 -> L1: 200 OK +call 2 -> L2: 404 Session not found: +call 3 -> L1: 200 OK +call 4 -> L2: 404 Session not found: +call 5 -> L1: 200 OK +call 6 -> L2: 404 Session not found: +succeeded: 3 of 6 + +# PART B: the balancer learns Mcp-Session-Id from the initialize response and pins the session. +initialize served by L1, then 6 calls pinned to the same instance +succeeded: 6 of 6 + +# PART C: the pinned instance L1 is stopped, as in a rolling deploy. + +## C1. the same session after L1 is gone +> POST balancer/mcp +> MCP-Protocol-Version: 2025-11-25 +> Mcp-Session-Id: +> {"jsonrpc":"2.0","id":30,"method":"tools/call","params":{"name":"order_status","arguments":{"orderId":"A-101"}}} +< 404 +< Content-Type: application/json +< X-Served-By: L2 +< {"jsonRpcError":{"code":-32603,"message":"Session not found: "}} + +## C2. the client has to start over with initialize +> POST balancer/mcp +> {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"wire-test","version":"1"}}} +< 200 +< Mcp-Session-Id: +< Content-Type: application/json +< X-Served-By: L2 +< {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25","capabilities":{"completions":{},"logging":{},"prompts":{"listChanged":true},"resources":{"subscribe":false,"listChanged":true},"tools":{"listChanged":true}},"serverInfo":{"name":"orders","version":"1.0.0"},"instructions":"Order lookup server used to compare the 2025 and 2026-07-28 MCP protocol generations."}} diff --git a/mcp-stateless/output/03-modern-wire.txt b/mcp-stateless/output/03-modern-wire.txt new file mode 100644 index 0000000..ce68c18 --- /dev/null +++ b/mcp-stateless/output/03-modern-wire.txt @@ -0,0 +1,29 @@ +# 2026-07-28 server (protocol MODERN): no handshake, no session, three self-contained POSTs + +## 1. server/discover replaces initialize +> POST /mcp +> MCP-Protocol-Version: 2026-07-28 +> Mcp-Method: server/discover +> {"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"wire-test","version":"1"},"io.modelcontextprotocol/clientCapabilities":{"elicitation":{"form":{}}}}}} +< 200 +< Content-Type: application/json +< {"jsonrpc":"2.0","id":1,"result":{"supportedVersions":["2026-07-28"],"capabilities":{"completions":{},"prompts":{"listChanged":true},"resources":{"subscribe":false,"listChanged":true},"tools":{"listChanged":true}},"instructions":"Order lookup server used to compare the 2025 and 2026-07-28 MCP protocol generations.","ttlMs":300000,"cacheScope":"public","resultType":"complete","_meta":{"io.modelcontextprotocol/serverInfo":{"name":"orders","version":"1.0.0"}}}} + +## 2. tools/list +> POST /mcp +> MCP-Protocol-Version: 2026-07-28 +> Mcp-Method: tools/list +> {"jsonrpc":"2.0","id":2,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"wire-test","version":"1"},"io.modelcontextprotocol/clientCapabilities":{"elicitation":{"form":{}}}}}} +< 200 +< Content-Type: application/json +< {"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"cancel_order","title":"cancel_order","description":"Cancels an order after the user confirms","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"orderId":{"type":"string","description":"Order id such as A-101"}},"required":["orderId"]},"annotations":{"title":"","readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false}},{"name":"order_status","title":"order_status","description":"Looks up the status of an order by its id","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"orderId":{"type":"string","description":"Order id such as A-101"}},"required":["orderId"]},"annotations":{"title":"","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}}],"ttlMs":300000,"cacheScope":"public","resultType":"complete","_meta":{"io.modelcontextprotocol/serverInfo":{"name":"orders","version":"1.0.0"}}}} + +## 3. tools/call carries the tool name in a header as well as in the body +> POST /mcp +> MCP-Protocol-Version: 2026-07-28 +> Mcp-Method: tools/call +> Mcp-Name: order_status +> {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"order_status","arguments":{"orderId":"A-101"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"wire-test","version":"1"},"io.modelcontextprotocol/clientCapabilities":{"elicitation":{"form":{}}}}}} +< 200 +< Content-Type: application/json +< {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"order A-101 is SHIPPED (answered by instance M1)"}],"isError":false,"resultType":"complete","_meta":{"io.modelcontextprotocol/serverInfo":{"name":"orders","version":"1.0.0"}}}} diff --git a/mcp-stateless/output/04-modern-errors.txt b/mcp-stateless/output/04-modern-errors.txt new file mode 100644 index 0000000..faaeb05 --- /dev/null +++ b/mcp-stateless/output/04-modern-errors.txt @@ -0,0 +1,80 @@ +# 2026-07-28 server: how a malformed request fails + +## 1. tools/call without Mcp-Name +> POST /mcp +> MCP-Protocol-Version: 2026-07-28 +> Mcp-Method: tools/call +> {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"order_status","arguments":{"orderId":"A-101"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"wire-test","version":"1"},"io.modelcontextprotocol/clientCapabilities":{"elicitation":{"form":{}}}}}} +< 400 +< Content-Type: application/json +< {"jsonrpc":"2.0","id":3,"error":{"code":-32020,"message":"Missing required header: Mcp-Name"}} + +## 2. Mcp-Method says tools/list, the body says tools/call +> POST /mcp +> MCP-Protocol-Version: 2026-07-28 +> Mcp-Method: tools/list +> Mcp-Name: order_status +> {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"order_status","arguments":{"orderId":"A-101"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"wire-test","version":"1"},"io.modelcontextprotocol/clientCapabilities":{"elicitation":{"form":{}}}}}} +< 400 +< Content-Type: application/json +< {"jsonrpc":"2.0","id":3,"error":{"code":-32020,"message":"Mcp-Method header does not match request method"}} + +## 3. the version header is present but params._meta is missing +> POST /mcp +> MCP-Protocol-Version: 2026-07-28 +> Mcp-Method: tools/list +> {"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}} +< 400 +< Content-Type: application/json +< {"jsonrpc":"2.0","id":2,"error":{"code":-32602,"message":"params._meta is required"}} + +## 4. a protocol version the server does not support +> POST /mcp +> MCP-Protocol-Version: 2027-01-01 +> Mcp-Method: tools/list +> {"jsonrpc":"2.0","id":2,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2027-01-01"}}} +< 400 +< Content-Type: application/json +< {"jsonrpc":"2.0","id":2,"error":{"code":-32022,"message":"Unsupported protocol version","data":{"supported":["2026-07-28"],"requested":"2027-01-01"}}} + +## 5. a 2025-era client's first request, initialize +> POST /mcp +> {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"wire-test","version":"1"}}} +< 400 +< Content-Type: application/json +< {"jsonrpc":"2.0","id":1,"error":{"code":-32020,"message":"Missing required header: Mcp-Method"}} + +## 6. a stray Mcp-Session-Id on a modern request +> POST /mcp +> MCP-Protocol-Version: 2026-07-28 +> Mcp-Method: tools/call +> Mcp-Name: order_status +> Mcp-Session-Id: left-over-from-a-2025-client +> {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"order_status","arguments":{"orderId":"A-101"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"wire-test","version":"1"},"io.modelcontextprotocol/clientCapabilities":{"elicitation":{"form":{}}}}}} +< 200 +< Content-Type: application/json +< {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"order A-101 is SHIPPED (answered by instance M1)"}],"isError":false,"resultType":"complete","_meta":{"io.modelcontextprotocol/serverInfo":{"name":"orders","version":"1.0.0"}}}} + +## 7. GET /mcp +< 405 +< Allow: POST + +## 8. unknown tool +> POST /mcp +> MCP-Protocol-Version: 2026-07-28 +> Mcp-Method: tools/call +> Mcp-Name: nope +> {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"nope","arguments":{},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"wire-test","version":"1"},"io.modelcontextprotocol/clientCapabilities":{"elicitation":{"form":{}}}}}} +< 400 +< Content-Type: application/json +< {"jsonrpc":"2.0","id":3,"error":{"code":-32602,"message":"Unknown tool: nope"}} + +## 9. a missing argument +> POST /mcp +> MCP-Protocol-Version: 2026-07-28 +> Mcp-Method: tools/call +> Mcp-Name: order_status +> {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"order_status","arguments":{},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"wire-test","version":"1"},"io.modelcontextprotocol/clientCapabilities":{"elicitation":{"form":{}}}}}} +< 200 +< Content-Type: application/json +< {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"Invalid arguments: Validation failed: JSON schema validation errors: [: required property 'orderId' not found]"}],"isError":true,"resultType":"complete","_meta":{"io.modelcontextprotocol/serverInfo":{"name":"orders","version":"1.0.0"}}}} diff --git a/mcp-stateless/output/05-modern-behind-lb.txt b/mcp-stateless/output/05-modern-behind-lb.txt new file mode 100644 index 0000000..5151ba6 --- /dev/null +++ b/mcp-stateless/output/05-modern-behind-lb.txt @@ -0,0 +1,16 @@ +# Two 2026-07-28 instances behind plain round-robin: no affinity, no handshake, no state to lose +# PART A: six tools/call, no initialize, no session id, one URL. +call 1 -> M1: 200 order A-102 is DELIVERED (answered by instance M1) +call 2 -> M2: 200 order A-102 is DELIVERED (answered by instance M2) +call 3 -> M1: 200 order A-102 is DELIVERED (answered by instance M1) +call 4 -> M2: 200 order A-102 is DELIVERED (answered by instance M2) +call 5 -> M1: 200 order A-102 is DELIVERED (answered by instance M1) +call 6 -> M2: 200 order A-102 is DELIVERED (answered by instance M2) +succeeded: 6 of 6 + +# PART B: M1 is stopped, as in a rolling deploy. The client changes nothing. +call 1 -> M2: 200 order A-102 is DELIVERED (answered by instance M2) +call 2 -> M2: 200 order A-102 is DELIVERED (answered by instance M2) +call 3 -> M2: 200 order A-102 is DELIVERED (answered by instance M2) +call 4 -> M2: 200 order A-102 is DELIVERED (answered by instance M2) +succeeded: 4 of 4 diff --git a/mcp-stateless/output/06-modern-mrtr.txt b/mcp-stateless/output/06-modern-mrtr.txt new file mode 100644 index 0000000..d4cef0b --- /dev/null +++ b/mcp-stateless/output/06-modern-mrtr.txt @@ -0,0 +1,77 @@ +# Multi-round-trip request: cancel_order asks for confirmation by returning input_required +# PART A: no spring.ai.mcp.server.modern.request-state-secret, so each instance seals with its own random key. + +## A1. first call, no answer yet +> POST /mcp (M1) +> MCP-Protocol-Version: 2026-07-28 +> Mcp-Method: tools/call +> Mcp-Name: cancel_order +> {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"cancel_order","arguments":{"orderId":"A-101"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"wire-test","version":"1"},"io.modelcontextprotocol/clientCapabilities":{"elicitation":{"form":{}}}}}} +< 200 +< Content-Type: application/json +< {"jsonrpc":"2.0","id":1,"result":{"inputRequests":{"confirm":{"params":{"mode":"form","message":"Cancel order A-101?","requestedSchema":{"type":"object","properties":{"ok":{"type":"boolean"}}}},"method":"elicitation/create"}},"requestState":"","resultType":"input_required","_meta":{"io.modelcontextprotocol/serverInfo":{"name":"orders","version":"1.0.0"}}}} + +# The part of requestState before the dot is base64url JSON, readable by anyone who holds it: + {"v":1,"s":"orderId=A-101","exp":,"m":"tools/call","n":"cancel_order"} + +## A2. retry, answer yes, back on the SAME instance +> POST /mcp (M1) +> MCP-Protocol-Version: 2026-07-28 +> Mcp-Method: tools/call +> Mcp-Name: cancel_order +> {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"cancel_order","arguments":{"orderId":"A-101"},"inputResponses":{"confirm":{"action":"accept","content":{"ok":true}}},"requestState":"","_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"wire-test","version":"1"},"io.modelcontextprotocol/clientCapabilities":{"elicitation":{"form":{}}}}}} +< 200 +< Content-Type: application/json +< {"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"order A-101 cancelled (answered by instance M1)"}],"resultType":"complete","_meta":{"io.modelcontextprotocol/serverInfo":{"name":"orders","version":"1.0.0"}}}} + +## A3. the same retry, but the balancer sends it to the OTHER instance +> POST /mcp (M2) +> MCP-Protocol-Version: 2026-07-28 +> Mcp-Method: tools/call +> Mcp-Name: cancel_order +> {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"cancel_order","arguments":{"orderId":"A-101"},"inputResponses":{"confirm":{"action":"accept","content":{"ok":true}}},"requestState":"","_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"wire-test","version":"1"},"io.modelcontextprotocol/clientCapabilities":{"elicitation":{"form":{}}}}}} +< 400 +< Content-Type: application/json +< {"jsonrpc":"2.0","id":2,"error":{"code":-32602,"message":"Invalid or expired requestState"}} + +## A4. the right instance, but the state was altered in transit +> POST /mcp (M1) +> MCP-Protocol-Version: 2026-07-28 +> Mcp-Method: tools/call +> Mcp-Name: cancel_order +> {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"cancel_order","arguments":{"orderId":"A-101"},"inputResponses":{"confirm":{"action":"accept","content":{"ok":true}}},"requestState":"","_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"wire-test","version":"1"},"io.modelcontextprotocol/clientCapabilities":{"elicitation":{"form":{}}}}}} +< 400 +< Content-Type: application/json +< {"jsonrpc":"2.0","id":2,"error":{"code":-32602,"message":"Invalid or expired requestState"}} + +# PART B: the same secret on every instance (32 bytes or more). + +## B1. first call on M1 +> POST /mcp (M1) +> MCP-Protocol-Version: 2026-07-28 +> Mcp-Method: tools/call +> Mcp-Name: cancel_order +> {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"cancel_order","arguments":{"orderId":"A-101"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"wire-test","version":"1"},"io.modelcontextprotocol/clientCapabilities":{"elicitation":{"form":{}}}}}} +< 200 +< Content-Type: application/json +< {"jsonrpc":"2.0","id":1,"result":{"inputRequests":{"confirm":{"params":{"mode":"form","message":"Cancel order A-101?","requestedSchema":{"type":"object","properties":{"ok":{"type":"boolean"}}}},"method":"elicitation/create"}},"requestState":"","resultType":"input_required","_meta":{"io.modelcontextprotocol/serverInfo":{"name":"orders","version":"1.0.0"}}}} + +## B2. retry, answer yes, on M2 +> POST /mcp (M2) +> MCP-Protocol-Version: 2026-07-28 +> Mcp-Method: tools/call +> Mcp-Name: cancel_order +> {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"cancel_order","arguments":{"orderId":"A-101"},"inputResponses":{"confirm":{"action":"accept","content":{"ok":true}}},"requestState":"","_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"wire-test","version":"1"},"io.modelcontextprotocol/clientCapabilities":{"elicitation":{"form":{}}}}}} +< 200 +< Content-Type: application/json +< {"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"order A-101 cancelled (answered by instance M2)"}],"resultType":"complete","_meta":{"io.modelcontextprotocol/serverInfo":{"name":"orders","version":"1.0.0"}}}} + +## B3. the user declines, retry on M1 +> POST /mcp (M1) +> MCP-Protocol-Version: 2026-07-28 +> Mcp-Method: tools/call +> Mcp-Name: cancel_order +> {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"cancel_order","arguments":{"orderId":"A-101"},"inputResponses":{"confirm":{"action":"decline"}},"requestState":"","_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"wire-test","version":"1"},"io.modelcontextprotocol/clientCapabilities":{"elicitation":{"form":{}}}}}} +< 200 +< Content-Type: application/json +< {"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"order A-101 kept (answered by instance M1)"}],"resultType":"complete","_meta":{"io.modelcontextprotocol/serverInfo":{"name":"orders","version":"1.0.0"}}}} diff --git a/mcp-stateless/output/07-both-versions.txt b/mcp-stateless/output/07-both-versions.txt new file mode 100644 index 0000000..a9eba28 --- /dev/null +++ b/mcp-stateless/output/07-both-versions.txt @@ -0,0 +1,31 @@ +# One URL, two server generations, split on the MCP-Protocol-Version header +# Rule: MCP-Protocol-Version >= 2026-07-28 goes to the modern pool (M1, M2). Everything else goes to the legacy pool (L1). + +# A 2025-era client: initialize, initialized, tools/call. + +## 1. initialize carries no MCP-Protocol-Version header +> POST router/mcp +> {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"wire-test","version":"1"}}} +< 200 +< Mcp-Session-Id: +< Content-Type: application/json +< X-Served-By: L1 +< {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25","capabilities":{"completions":{},"logging":{},"prompts":{"listChanged":true},"resources":{"subscribe":false,"listChanged":true},"tools":{"listChanged":true}},"serverInfo":{"name":"orders","version":"1.0.0"},"instructions":"Order lookup server used to compare the 2025 and 2026-07-28 MCP protocol generations."}} + +## 2. tools/call with the session and MCP-Protocol-Version: 2025-11-25 +> POST router/mcp +> MCP-Protocol-Version: 2025-11-25 +> Mcp-Session-Id: +> {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"order_status","arguments":{"orderId":"A-101"}}} +< 200 +< Content-Type: text/event-stream +< X-Served-By: L1 +< id: +< event:message +< data: {"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"order A-101 is SHIPPED (answered by instance L1)"}],"isError":false}} + +# A 2026-07-28 client through the same URL: four tools/call, nothing else. +modern call 1 -> M1: 200 order A-101 is SHIPPED (answered by instance M1) +modern call 2 -> M2: 200 order A-101 is SHIPPED (answered by instance M2) +modern call 3 -> M1: 200 order A-101 is SHIPPED (answered by instance M1) +modern call 4 -> M2: 200 order A-101 is SHIPPED (answered by instance M2) diff --git a/mcp-stateless/output/08-sdk-modern-client.txt b/mcp-stateless/output/08-sdk-modern-client.txt new file mode 100644 index 0000000..489f373 --- /dev/null +++ b/mcp-stateless/output/08-sdk-modern-client.txt @@ -0,0 +1,23 @@ +# The 2.2.0 modern SDK client against two 2026-07-28 instances behind round-robin +discover: supportedVersions=[2026-07-28] ttlMs=300000 cacheScope=PUBLIC +tools: [cancel_order, order_status] +order_status #1: order A-100 is PACKED (answered by instance M1) +order_status #2: order A-100 is PACKED (answered by instance M2) +order_status #3: order A-100 is PACKED (answered by instance M1) +order_status #4: order A-100 is PACKED (answered by instance M2) +cancel_order (the client answered the confirmation itself): order A-102 cancelled (answered by instance M2) + +What the balancer saw, in order: + POST server/discover + POST tools/list + POST tools/call + POST tools/call + POST tools/call + POST tools/call + POST tools/call + POST tools/call +total requests: 8 + +# Same client and balancer, but the instances have no shared request-state-secret: +cancel_order: io.modelcontextprotocol.modern.McpException + Invalid or expired requestState diff --git a/mcp-stateless/output/09-sdk-version-mismatch.txt b/mcp-stateless/output/09-sdk-version-mismatch.txt new file mode 100644 index 0000000..13e5b4d --- /dev/null +++ b/mcp-stateless/output/09-sdk-version-mismatch.txt @@ -0,0 +1,6 @@ +# What each SDK client says when it meets a server of the other generation +2025-era client -> modern server: java.lang.RuntimeException + RuntimeException: Client failed to initialize by explicit API call + McpTransportException: Bad Request. Status code:400, response body: {"jsonrpc":"2.0","id":"","error":{"code":-32020,"message":"Missing required header: Mcp-Method"}} +modern client -> 2025-era server: io.modelcontextprotocol.modern.client.transport.McpHttpStatusException + HTTP 400 from http://localhost:/mcp: {"jsonRpcError":{"code":-32601,"message":"Session ID missing"}... (stack trace omitted) diff --git a/mcp-stateless/output/10-sdk-clients-through-router.txt b/mcp-stateless/output/10-sdk-clients-through-router.txt new file mode 100644 index 0000000..195e76e --- /dev/null +++ b/mcp-stateless/output/10-sdk-clients-through-router.txt @@ -0,0 +1,10 @@ +# A 2025-era SDK client and a 2026-07-28 SDK client, one router URL, split on MCP-Protocol-Version +2025-era client: order A-101 is SHIPPED (answered by instance L1) +2026-07-28 client: order A-101 is SHIPPED (answered by instance M2) + +What the router saw (HTTP method and Mcp-Method header; '-' means the header is absent): + 1 x DELETE - + 1 x GET - + 3 x POST - + 1 x POST tools/call + 1 x POST tools/list diff --git a/mcp-stateless/pom.xml b/mcp-stateless/pom.xml new file mode 100644 index 0000000..eedef04 --- /dev/null +++ b/mcp-stateless/pom.xml @@ -0,0 +1,68 @@ + + + 4.0.0 + + + com.ankurm.agents + java-ai-agents + 1.0.0 + + + mcp-stateless + MCP 2026-07-28: migrating a Java MCP server to the stateless spec + + + + 4.2.0 + 2.1.0 + + + + + + org.springframework.boot + spring-boot-dependencies + ${spring-boot.version} + pom + import + + + org.springframework.ai + spring-ai-bom + ${spring-ai.version} + pom + import + + + + + + + org.springframework.ai + spring-ai-starter-mcp-server-webmvc + + + org.springframework.boot + spring-boot-starter-test + test + + + + + mcp-stateless + + + org.springframework.boot + spring-boot-maven-plugin + ${spring-boot.version} + + + repackage + + + + + + diff --git a/mcp-stateless/scripts/curl-modern.sh b/mcp-stateless/scripts/curl-modern.sh new file mode 100755 index 0000000..6c743a4 --- /dev/null +++ b/mcp-stateless/scripts/curl-modern.sh @@ -0,0 +1,8 @@ +#!/usr/bin/env bash +# One self-contained 2026-07-28 request, no handshake. Usage: scripts/curl-modern.sh [port] [order-id] +port="${1:-8082}"; order="${2:-A-101}" +curl -si -X POST "localhost:${port}/mcp" \ + -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \ + -H 'MCP-Protocol-Version: 2026-07-28' -H 'Mcp-Method: tools/call' -H 'Mcp-Name: order_status' \ + -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"order_status","arguments":{"orderId":"'"${order}"'"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"curl","version":"1"},"io.modelcontextprotocol/clientCapabilities":{}}}}' +echo diff --git a/mcp-stateless/scripts/run-all.sh b/mcp-stateless/scripts/run-all.sh new file mode 100755 index 0000000..73dd03b --- /dev/null +++ b/mcp-stateless/scripts/run-all.sh @@ -0,0 +1,7 @@ +#!/usr/bin/env bash +# Regenerates every file in output/. The tests write the transcripts and assert the same facts, +# so a failing build means a number in the post stopped being true. +set -euo pipefail +cd "$(dirname "$0")/.." +mvn -B -q test +ls -1 output diff --git a/mcp-stateless/scripts/run.sh b/mcp-stateless/scripts/run.sh new file mode 100755 index 0000000..2f31ffb --- /dev/null +++ b/mcp-stateless/scripts/run.sh @@ -0,0 +1,9 @@ +#!/usr/bin/env bash +# Starts one instance by hand so you can poke it with curl. +# scripts/run.sh modern 8082 M1 (2026-07-28 server) +# scripts/run.sh legacy 8081 L1 (2025-era server) +set -euo pipefail +cd "$(dirname "$0")/.." +profile="${1:?profile: legacy or modern}"; port="${2:-8080}"; name="${3:-solo}" +[ -f target/mcp-stateless.jar ] || mvn -B -q -DskipTests package +exec java -jar target/mcp-stateless.jar --spring.profiles.active="$profile" --server.port="$port" --instance.name="$name" diff --git a/mcp-stateless/src/main/java/com/ankurm/mcpstateless/CancelOrderTool.java b/mcp-stateless/src/main/java/com/ankurm/mcpstateless/CancelOrderTool.java new file mode 100644 index 0000000..58ddaa6 --- /dev/null +++ b/mcp-stateless/src/main/java/com/ankurm/mcpstateless/CancelOrderTool.java @@ -0,0 +1,71 @@ +package com.ankurm.mcpstateless; + +import java.util.LinkedHashMap; +import java.util.Map; + +import io.modelcontextprotocol.modern.McpSchema.CallToolOutcome; +import io.modelcontextprotocol.modern.McpSchema.CallToolResult; +import io.modelcontextprotocol.modern.McpSchema.ElicitFormRequest; +import io.modelcontextprotocol.modern.McpSchema.ElicitResult; +import io.modelcontextprotocol.modern.McpSchema.InputRequiredResult; +import io.modelcontextprotocol.modern.McpSchema.TextContent; + +import org.springframework.ai.mcp.annotation.McpTool; +import org.springframework.ai.mcp.annotation.McpToolParam; +import org.springframework.ai.mcp.annotation.context.McpModernRequestContext; +import org.springframework.beans.factory.annotation.Value; +import org.springframework.context.annotation.Profile; +import org.springframework.stereotype.Component; + +/** + * The 2026-07-28 replacement for "ask the user in the middle of a tool call". The tool does not call + * back into the client. It returns {@code InputRequiredResult}, the client answers, and the client + * retries the SAME call with the answer attached. Nothing is parked on the server between the two + * requests, which is why any instance can take the retry. + * + *

Modern profile only: a legacy server has no way to express this tool. + */ +@Component +@Profile("modern") +public class CancelOrderTool { + + private final String instance; + + public CancelOrderTool(@Value("${instance.name:solo}") String instance) { + this.instance = instance; + } + + /** A LinkedHashMap, not Map.of: Map.of iterates in a different order in every JVM, which makes the wire output unstable. */ + private static Map schema() { + Map ok = new LinkedHashMap<>(); + ok.put("type", "boolean"); + Map properties = new LinkedHashMap<>(); + properties.put("ok", ok); + Map schema = new LinkedHashMap<>(); + schema.put("type", "object"); + schema.put("properties", properties); + return schema; + } + + @McpTool(name = "cancel_order", description = "Cancels an order after the user confirms", + annotations = @McpTool.McpAnnotations(readOnlyHint = false, destructiveHint = true, + idempotentHint = true, openWorldHint = false)) + public CallToolOutcome cancelOrder(McpModernRequestContext ctx, + @McpToolParam(description = "Order id such as A-101") String orderId) { + + ElicitResult confirmation = ctx.inputResponse("confirm", ElicitResult.class); + if (confirmation == null) { + // First request: no answer yet. Ask, and seal the order id into requestState. + return InputRequiredResult.builder() + .elicit("confirm", ElicitFormRequest.builder("Cancel order " + orderId + "?", schema()).build()) + .requestState("orderId=" + orderId) + .build(); + } + boolean confirmed = confirmation.action() == ElicitResult.Action.ACCEPT + && Boolean.TRUE.equals(confirmation.content().get("ok")); + String text = confirmed + ? "order " + orderId + " cancelled (answered by instance " + instance + ")" + : "order " + orderId + " kept (answered by instance " + instance + ")"; + return CallToolResult.builder().addContent(TextContent.builder(text).build()).build(); + } +} diff --git a/mcp-stateless/src/main/java/com/ankurm/mcpstateless/OrderTools.java b/mcp-stateless/src/main/java/com/ankurm/mcpstateless/OrderTools.java new file mode 100644 index 0000000..f2cef0e --- /dev/null +++ b/mcp-stateless/src/main/java/com/ankurm/mcpstateless/OrderTools.java @@ -0,0 +1,35 @@ +package com.ankurm.mcpstateless; + +import java.util.Map; + +import org.springframework.ai.mcp.annotation.McpTool; +import org.springframework.ai.mcp.annotation.McpToolParam; +import org.springframework.beans.factory.annotation.Value; +import org.springframework.stereotype.Component; + +/** + * The same {@code @McpTool} bean serves both protocol generations. The tool reports which + * instance answered, so a load-balancer test can see the requests spreading out. + */ +@Component +public class OrderTools { + + private static final Map ORDERS = Map.of( + "A-100", "PACKED", + "A-101", "SHIPPED", + "A-102", "DELIVERED"); + + private final String instance; + + public OrderTools(@Value("${instance.name:solo}") String instance) { + this.instance = instance; + } + + @McpTool(name = "order_status", description = "Looks up the status of an order by its id", + annotations = @McpTool.McpAnnotations(readOnlyHint = true, destructiveHint = false, + idempotentHint = true, openWorldHint = false)) + public String orderStatus(@McpToolParam(description = "Order id such as A-101") String orderId) { + String status = ORDERS.getOrDefault(orderId, "UNKNOWN"); + return "order " + orderId + " is " + status + " (answered by instance " + instance + ")"; + } +} diff --git a/mcp-stateless/src/main/java/com/ankurm/mcpstateless/StatelessApp.java b/mcp-stateless/src/main/java/com/ankurm/mcpstateless/StatelessApp.java new file mode 100644 index 0000000..19e75e8 --- /dev/null +++ b/mcp-stateless/src/main/java/com/ankurm/mcpstateless/StatelessApp.java @@ -0,0 +1,16 @@ +package com.ankurm.mcpstateless; + +import org.springframework.boot.SpringApplication; +import org.springframework.boot.autoconfigure.SpringBootApplication; + +/** + * One order-lookup MCP server that can run as a 2025-era stateful server ({@code legacy} profile) + * or as a 2026-07-28 stateless server ({@code modern} profile). The tools are identical in both. + */ +@SpringBootApplication +public class StatelessApp { + + public static void main(String[] args) { + SpringApplication.run(StatelessApp.class, args); + } +} diff --git a/mcp-stateless/src/main/resources/application-legacy.yml b/mcp-stateless/src/main/resources/application-legacy.yml new file mode 100644 index 0000000..3d62756 --- /dev/null +++ b/mcp-stateless/src/main/resources/application-legacy.yml @@ -0,0 +1,6 @@ +# The 2025-era server: initialize handshake, Mcp-Session-Id, one session per client held in server memory. +spring: + ai: + mcp: + server: + protocol: STREAMABLE diff --git a/mcp-stateless/src/main/resources/application-modern.yml b/mcp-stateless/src/main/resources/application-modern.yml new file mode 100644 index 0000000..2559be6 --- /dev/null +++ b/mcp-stateless/src/main/resources/application-modern.yml @@ -0,0 +1,13 @@ +# The 2026-07-28 server: no handshake, no session, every POST stands alone. +spring: + ai: + mcp: + server: + protocol: MODERN + modern: + # Tell clients how long they may cache server/discover and the *list results. Safe here because + # nothing in them depends on who is asking. Anything per-caller must stay PRIVATE. + discover-ttl: 5m + discover-cache-scope: PUBLIC + list-ttl: 5m + list-cache-scope: PUBLIC diff --git a/mcp-stateless/src/main/resources/application.yml b/mcp-stateless/src/main/resources/application.yml new file mode 100644 index 0000000..5a78073 --- /dev/null +++ b/mcp-stateless/src/main/resources/application.yml @@ -0,0 +1,15 @@ +spring: + main: + banner-mode: off + jmx: + enabled: false + ai: + mcp: + server: + name: orders + version: 1.0.0 + instructions: Order lookup server used to compare the 2025 and 2026-07-28 MCP protocol generations. +logging: + level: + root: warn + com.ankurm: info diff --git a/mcp-stateless/src/test/java/com/ankurm/mcpstateless/BothVersionsTest.java b/mcp-stateless/src/test/java/com/ankurm/mcpstateless/BothVersionsTest.java new file mode 100644 index 0000000..e101770 --- /dev/null +++ b/mcp-stateless/src/test/java/com/ankurm/mcpstateless/BothVersionsTest.java @@ -0,0 +1,84 @@ +package com.ankurm.mcpstateless; + +import static org.assertj.core.api.Assertions.assertThat; + +import java.util.List; +import java.util.Map; + +import com.ankurm.mcpstateless.support.Instance; +import com.ankurm.mcpstateless.support.Proxy; +import com.ankurm.mcpstateless.support.Transcript; +import com.ankurm.mcpstateless.support.Wire; +import com.ankurm.mcpstateless.support.Wire.Reply; + +import org.junit.jupiter.api.AfterAll; +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.Test; + +/** + * Spring AI picks ONE protocol per application ({@code spring.ai.mcp.server.protocol}), so serving both + * generations during a migration means two deployments behind one URL, split on the version header. + */ +class BothVersionsTest { + + static Instance legacy; + static Instance modern1; + static Instance modern2; + + @BeforeAll + static void start() { + legacy = Instance.start("legacy", "L1"); + modern1 = Instance.start("modern", "M1"); + modern2 = Instance.start("modern", "M2"); + } + + @AfterAll + static void stop() { + legacy.close(); + modern1.close(); + modern2.close(); + } + + /** The routing rule: a request that names 2026-07-28 or later in MCP-Protocol-Version goes to the modern pool. */ + static boolean isModern(Map headers) { + String v = headers.get("mcp-protocol-version"); + return v != null && v.compareTo(Wire.MODERN_VERSION) >= 0; + } + + @Test + void oneUrlTwoGenerations() { + Transcript t = new Transcript("07-both-versions.txt", + "One URL, two server generations, split on the MCP-Protocol-Version header"); + Proxy.Pool legacyPool = new Proxy.Pool(List.of(legacy), true); + Proxy.Pool modernPool = new Proxy.Pool(List.of(modern1, modern2)); + try (Proxy router = new Proxy(h -> isModern(h) ? modernPool : legacyPool)) { + String url = router.url(); + t.note("Rule: MCP-Protocol-Version >= 2026-07-28 goes to the modern pool (M1, M2). Everything else goes to the legacy pool (L1)."); + + t.blank().note("A 2025-era client: initialize, initialized, tools/call."); + Reply init = Wire.post(url, Wire.legacyHeaders(null), Wire.INITIALIZE); + t.exchange("1. initialize carries no MCP-Protocol-Version header", "router/mcp", Wire.legacyHeaders(null), + Wire.INITIALIZE, init); + assertThat(init.status()).isEqualTo(200); + assertThat(init.header("X-Served-By")).isEqualTo("L1"); + Map h = Wire.legacyHeaders(init.header("Mcp-Session-Id")); + assertThat(Wire.post(url, h, Wire.INITIALIZED).status()).isEqualTo(202); + Reply old = Wire.post(url, h, Wire.legacyCall(2, "A-101")); + t.exchange("2. tools/call with the session and MCP-Protocol-Version: 2025-11-25", "router/mcp", h, + Wire.legacyCall(2, "A-101"), old); + assertThat(old.header("X-Served-By")).isEqualTo("L1"); + assertThat(old.text()).isEqualTo("order A-101 is SHIPPED (answered by instance L1)"); + + t.blank().note("A 2026-07-28 client through the same URL: four tools/call, nothing else."); + String args = "{\"orderId\":\"A-101\"}"; + for (int i = 0; i < 4; i++) { + Reply r = Wire.post(url, Wire.modernHeaders("tools/call", "order_status"), + Wire.modernCall(60 + i, "order_status", args)); + t.line("modern call " + (i + 1) + " -> " + r.header("X-Served-By") + ": " + r.status() + " " + r.text()); + assertThat(r.status()).isEqualTo(200); + assertThat(r.header("X-Served-By")).isEqualTo(i % 2 == 0 ? "M1" : "M2"); + } + } + t.write(); + } +} diff --git a/mcp-stateless/src/test/java/com/ankurm/mcpstateless/LegacyBehindLoadBalancerTest.java b/mcp-stateless/src/test/java/com/ankurm/mcpstateless/LegacyBehindLoadBalancerTest.java new file mode 100644 index 0000000..ded2cbf --- /dev/null +++ b/mcp-stateless/src/test/java/com/ankurm/mcpstateless/LegacyBehindLoadBalancerTest.java @@ -0,0 +1,114 @@ +package com.ankurm.mcpstateless; + +import static org.assertj.core.api.Assertions.assertThat; + +import java.util.ArrayList; +import java.util.List; +import java.util.Map; + +import com.ankurm.mcpstateless.support.Instance; +import com.ankurm.mcpstateless.support.Proxy; +import com.ankurm.mcpstateless.support.Transcript; +import com.ankurm.mcpstateless.support.Wire; +import com.ankurm.mcpstateless.support.Wire.Reply; + +import org.junit.jupiter.api.AfterAll; +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.Test; + +/** The same 2025-era server twice, behind a balancer that does not know what an MCP session is. */ +class LegacyBehindLoadBalancerTest { + + static Instance l1; + static Instance l2; + + @BeforeAll + static void start() { + l1 = Instance.start("legacy", "L1"); + l2 = Instance.start("legacy", "L2"); + } + + @AfterAll + static void stop() { + l1.close(); + l2.close(); + } + + @Test + void roundRobinBreaksTheSessionAndAffinityMendsItUntilAnInstanceDies() { + Transcript t = new Transcript("02-legacy-behind-lb.txt", + "Two 2025-era instances behind a balancer: round-robin, then session affinity, then an instance dies"); + + // ---- round-robin: the session exists on one instance only ------------------------------------------ + t.note("PART A: plain round-robin. Request n goes to L1 when n is even and to L2 when n is odd."); + Proxy.Pool roundRobin = new Proxy.Pool(List.of(l1, l2)); + try (Proxy lb = new Proxy(h -> roundRobin)) { + String url = lb.url(); + Reply init = Wire.post(url, Wire.legacyHeaders(null), Wire.INITIALIZE); + String session = init.header("Mcp-Session-Id"); + t.exchange("A1. initialize", "balancer/mcp", Wire.legacyHeaders(null), Wire.INITIALIZE, init); + assertThat(init.header("X-Served-By")).isEqualTo("L1"); + + Map h = Wire.legacyHeaders(session); + Reply initialized = Wire.post(url, h, Wire.INITIALIZED); + t.exchange("A2. notifications/initialized", "balancer/mcp", h, Wire.INITIALIZED, initialized); + assertThat(initialized.header("X-Served-By")).isEqualTo("L2"); + assertThat(initialized.status()).isEqualTo(404); + + t.blank().note("Six tools/call with the same session id, through the same balancer:"); + List outcomes = new ArrayList<>(); + int ok = 0; + for (int i = 0; i < 6; i++) { + Reply r = Wire.post(url, h, Wire.legacyCall(10 + i, "A-101")); + String detail = r.status() == 200 ? "200 OK" : r.status() + " " + + r.json().path("jsonRpcError").path("message").asString().replaceAll("[0-9a-f-]{36}", ""); + outcomes.add("call " + (i + 1) + " -> " + r.header("X-Served-By") + ": " + detail); + if (r.status() == 200) { + ok++; + } + } + outcomes.forEach(t::line); + t.line("succeeded: " + ok + " of 6"); + assertThat(ok).isEqualTo(3); + assertThat(outcomes).filteredOn(s -> s.contains("404 Session not found")).hasSize(3); + } + + // ---- affinity: the workaround the 2025 protocol forces --------------------------------------------- + t.blank().note("PART B: the balancer learns Mcp-Session-Id from the initialize response and pins the session."); + // One Pool for the whole proxy, because the pool is where the learned session-to-instance table lives. + Proxy.Pool pinned = new Proxy.Pool(List.of(l1, l2), true); + try (Proxy lb = new Proxy(h -> pinned)) { + String url = lb.url(); + Reply init = Wire.post(url, Wire.legacyHeaders(null), Wire.INITIALIZE); + String session = init.header("Mcp-Session-Id"); + Map h = Wire.legacyHeaders(session); + Reply initialized = Wire.post(url, h, Wire.INITIALIZED); + assertThat(initialized.status()).isEqualTo(202); + int ok = 0; + for (int i = 0; i < 6; i++) { + Reply r = Wire.post(url, h, Wire.legacyCall(20 + i, "A-101")); + if (r.status() == 200 && "L1".equals(r.header("X-Served-By"))) { + ok++; + } + } + t.line("initialize served by " + init.header("X-Served-By") + ", then 6 calls pinned to the same instance"); + t.line("succeeded: " + ok + " of 6"); + assertThat(ok).isEqualTo(6); + + // ---- the pinned instance goes away (deploy, crash, autoscaler) ------------------------------ + t.blank().note("PART C: the pinned instance L1 is stopped, as in a rolling deploy."); + l1.close(); + Reply after = Wire.post(url, h, Wire.legacyCall(30, "A-101")); + t.exchange("C1. the same session after L1 is gone", "balancer/mcp", h, Wire.legacyCall(30, "A-101"), after); + assertThat(after.header("X-Served-By")).isEqualTo("L2"); + assertThat(after.status()).isEqualTo(404); + + Reply again = Wire.post(url, Wire.legacyHeaders(null), Wire.INITIALIZE); + t.exchange("C2. the client has to start over with initialize", "balancer/mcp", Wire.legacyHeaders(null), + Wire.INITIALIZE, again); + assertThat(again.status()).isEqualTo(200); + assertThat(again.header("X-Served-By")).isEqualTo("L2"); + } + t.write(); + } +} diff --git a/mcp-stateless/src/test/java/com/ankurm/mcpstateless/LegacyHandshakeTest.java b/mcp-stateless/src/test/java/com/ankurm/mcpstateless/LegacyHandshakeTest.java new file mode 100644 index 0000000..c528d49 --- /dev/null +++ b/mcp-stateless/src/test/java/com/ankurm/mcpstateless/LegacyHandshakeTest.java @@ -0,0 +1,74 @@ +package com.ankurm.mcpstateless; + +import static org.assertj.core.api.Assertions.assertThat; + +import java.util.Map; + +import com.ankurm.mcpstateless.support.Instance; +import com.ankurm.mcpstateless.support.Transcript; +import com.ankurm.mcpstateless.support.Wire; +import com.ankurm.mcpstateless.support.Wire.Reply; + +import org.junit.jupiter.api.AfterAll; +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.Test; + +/** What the 2025-era protocol needs before the first useful call, and what the server remembers afterwards. */ +class LegacyHandshakeTest { + + static Instance server; + + @BeforeAll + static void start() { + server = Instance.start("legacy", "L1"); + } + + @AfterAll + static void stop() { + server.close(); + } + + @Test + void handshakeThenCallNeedsAServerSideSession() { + Transcript t = new Transcript("01-legacy-handshake.txt", + "2025-era server (protocol STREAMABLE): the session lives in the server's memory"); + String url = server.url(); + t.note("Error bodies are shown without the Java stack trace the SDK serialises into them."); + + // 1. A call before any handshake is refused. + Reply early = Wire.post(url, Wire.legacyHeaders(null), Wire.legacyCall(2, "A-101")); + t.exchange("1. tools/call with no session yet", "/mcp", Wire.legacyHeaders(null), Wire.legacyCall(2, "A-101"), early); + assertThat(early.status()).isEqualTo(400); + assertThat(early.json().path("jsonRpcError").path("message").asString()).isEqualTo("Session ID missing"); + + // 2. initialize creates the session and returns its id in a header. + Reply init = Wire.post(url, Wire.legacyHeaders(null), Wire.INITIALIZE); + t.exchange("2. initialize", "/mcp", Wire.legacyHeaders(null), Wire.INITIALIZE, init); + String session = init.header("Mcp-Session-Id"); + assertThat(init.status()).isEqualTo(200); + assertThat(session).isNotBlank(); + assertThat(init.json().path("result").path("protocolVersion").asString()).isEqualTo(Wire.LEGACY_VERSION); + + // 3. The client confirms the handshake. + Map withSession = Wire.legacyHeaders(session); + Reply initialized = Wire.post(url, withSession, Wire.INITIALIZED); + t.exchange("3. notifications/initialized", "/mcp", withSession, Wire.INITIALIZED, initialized); + assertThat(initialized.status()).isEqualTo(202); + + // 4. Now the call works, and only because the session id names state held by THIS instance. + Reply call = Wire.post(url, withSession, Wire.legacyCall(2, "A-101")); + t.exchange("4. tools/call with the session", "/mcp", withSession, Wire.legacyCall(2, "A-101"), call); + assertThat(call.status()).isEqualTo(200); + assertThat(call.text()).isEqualTo("order A-101 is SHIPPED (answered by instance L1)"); + + // 5. A session id this instance has never seen is a 404, not a recoverable condition. + Map stranger = Wire.legacyHeaders("00000000-0000-0000-0000-000000000000"); + Reply unknown = Wire.post(url, stranger, Wire.legacyCall(2, "A-101")); + t.exchange("5. tools/call with a session id this server never issued", "/mcp", stranger, + Wire.legacyCall(2, "A-101"), unknown); + assertThat(unknown.status()).isEqualTo(404); + assertThat(unknown.json().path("jsonRpcError").path("message").asString()).startsWith("Session not found"); + + t.write(); + } +} diff --git a/mcp-stateless/src/test/java/com/ankurm/mcpstateless/ModernBehindLoadBalancerTest.java b/mcp-stateless/src/test/java/com/ankurm/mcpstateless/ModernBehindLoadBalancerTest.java new file mode 100644 index 0000000..bb70fbf --- /dev/null +++ b/mcp-stateless/src/test/java/com/ankurm/mcpstateless/ModernBehindLoadBalancerTest.java @@ -0,0 +1,77 @@ +package com.ankurm.mcpstateless; + +import static org.assertj.core.api.Assertions.assertThat; + +import java.util.ArrayList; +import java.util.List; + +import com.ankurm.mcpstateless.support.Instance; +import com.ankurm.mcpstateless.support.Proxy; +import com.ankurm.mcpstateless.support.Transcript; +import com.ankurm.mcpstateless.support.Wire; +import com.ankurm.mcpstateless.support.Wire.Reply; + +import org.junit.jupiter.api.AfterAll; +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.Test; + +/** The 2026-07-28 server twice behind the same naive round-robin balancer that broke the 2025 one. */ +class ModernBehindLoadBalancerTest { + + static Instance m1; + static Instance m2; + + @BeforeAll + static void start() { + m1 = Instance.start("modern", "M1"); + m2 = Instance.start("modern", "M2"); + } + + @AfterAll + static void stop() { + m1.close(); + m2.close(); + } + + @Test + void anyInstanceCanTakeAnyRequestAndAnInstanceCanDisappear() { + Transcript t = new Transcript("05-modern-behind-lb.txt", + "Two 2026-07-28 instances behind plain round-robin: no affinity, no handshake, no state to lose"); + Proxy.Pool pool = new Proxy.Pool(List.of(m1, m2)); + try (Proxy lb = new Proxy(h -> pool)) { + String url = lb.url(); + String args = "{\"orderId\":\"A-102\"}"; + + t.note("PART A: six tools/call, no initialize, no session id, one URL."); + List served = new ArrayList<>(); + int ok = 0; + for (int i = 0; i < 6; i++) { + Reply r = Wire.post(url, Wire.modernHeaders("tools/call", "order_status"), + Wire.modernCall(40 + i, "order_status", args)); + served.add(r.header("X-Served-By")); + if (r.status() == 200 && r.text().endsWith("(answered by instance " + r.header("X-Served-By") + ")")) { + ok++; + } + t.line("call " + (i + 1) + " -> " + r.header("X-Served-By") + ": " + r.status() + " " + r.text()); + } + t.line("succeeded: " + ok + " of 6"); + assertThat(ok).isEqualTo(6); + assertThat(served).containsExactly("M1", "M2", "M1", "M2", "M1", "M2"); + + t.blank().note("PART B: M1 is stopped, as in a rolling deploy. The client changes nothing."); + m1.close(); + int ok2 = 0; + for (int i = 0; i < 4; i++) { + Reply r = Wire.post(url, Wire.modernHeaders("tools/call", "order_status"), + Wire.modernCall(50 + i, "order_status", args)); + if (r.status() == 200 && "M2".equals(r.header("X-Served-By"))) { + ok2++; + } + t.line("call " + (i + 1) + " -> " + r.header("X-Served-By") + ": " + r.status() + " " + r.text()); + } + t.line("succeeded: " + ok2 + " of 4"); + assertThat(ok2).isEqualTo(4); + } + t.write(); + } +} diff --git a/mcp-stateless/src/test/java/com/ankurm/mcpstateless/ModernWireTest.java b/mcp-stateless/src/test/java/com/ankurm/mcpstateless/ModernWireTest.java new file mode 100644 index 0000000..d2399ea --- /dev/null +++ b/mcp-stateless/src/test/java/com/ankurm/mcpstateless/ModernWireTest.java @@ -0,0 +1,144 @@ +package com.ankurm.mcpstateless; + +import static org.assertj.core.api.Assertions.assertThat; + +import java.util.LinkedHashMap; +import java.util.Map; + +import com.ankurm.mcpstateless.support.Instance; +import com.ankurm.mcpstateless.support.Transcript; +import com.ankurm.mcpstateless.support.Wire; +import com.ankurm.mcpstateless.support.Wire.Reply; + +import org.junit.jupiter.api.AfterAll; +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.Test; + +/** The 2026-07-28 wire contract as one real server enforces it: what a request must carry, and how it fails. */ +class ModernWireTest { + + static Instance server; + + @BeforeAll + static void start() { + server = Instance.start("modern", "M1"); + } + + @AfterAll + static void stop() { + server.close(); + } + + @Test + void everyRequestStandsAlone() { + Transcript t = new Transcript("03-modern-wire.txt", + "2026-07-28 server (protocol MODERN): no handshake, no session, three self-contained POSTs"); + String url = server.url(); + + Map discoverHeaders = Wire.modernHeaders("server/discover", null); + Reply discover = Wire.post(url, discoverHeaders, Wire.modernDiscover()); + t.exchange("1. server/discover replaces initialize", "/mcp", discoverHeaders, Wire.modernDiscover(), discover); + assertThat(discover.status()).isEqualTo(200); + assertThat(discover.header("Mcp-Session-Id")).isNull(); + assertThat(discover.json().path("result").path("supportedVersions").get(0).asString()).isEqualTo(Wire.MODERN_VERSION); + assertThat(discover.json().path("result").path("ttlMs").asLong()).isEqualTo(300_000L); + assertThat(discover.json().path("result").path("cacheScope").asString()).isEqualTo("public"); + + Map listHeaders = Wire.modernHeaders("tools/list", null); + Reply list = Wire.post(url, listHeaders, Wire.modernList()); + t.exchange("2. tools/list", "/mcp", listHeaders, Wire.modernList(), list); + assertThat(list.status()).isEqualTo(200); + assertThat(list.json().path("result").path("tools")).hasSize(2); + for (var tool : list.json().path("result").path("tools")) { + if (tool.path("name").asString().equals("order_status")) { + assertThat(tool.path("annotations").path("readOnlyHint").asBoolean()).isTrue(); + } + else { + assertThat(tool.path("annotations").path("destructiveHint").asBoolean()).isTrue(); + } + } + + String args = "{\"orderId\":\"A-101\"}"; + Map callHeaders = Wire.modernHeaders("tools/call", "order_status"); + Reply call = Wire.post(url, callHeaders, Wire.modernCall(3, "order_status", args)); + t.exchange("3. tools/call carries the tool name in a header as well as in the body", "/mcp", callHeaders, + Wire.modernCall(3, "order_status", args), call); + assertThat(call.status()).isEqualTo(200); + assertThat(call.header("Mcp-Session-Id")).isNull(); + assertThat(call.text()).isEqualTo("order A-101 is SHIPPED (answered by instance M1)"); + assertThat(call.json().path("result").path("resultType").asString()).isEqualTo("complete"); + t.write(); + } + + @Test + void theServerChecksTheHeadersAgainstTheBody() { + Transcript t = new Transcript("04-modern-errors.txt", "2026-07-28 server: how a malformed request fails"); + String url = server.url(); + String args = "{\"orderId\":\"A-101\"}"; + String call = Wire.modernCall(3, "order_status", args); + + // Mcp-Name is required for tools/call + Map noName = Wire.modernHeaders("tools/call", null); + Reply r1 = Wire.post(url, noName, call); + t.exchange("1. tools/call without Mcp-Name", "/mcp", noName, call, r1); + assertThat(r1.status()).isEqualTo(400); + assertThat(r1.json().path("error").path("code").asInt()).isEqualTo(-32020); + + // Mcp-Method must agree with the body + Map wrongMethod = Wire.modernHeaders("tools/list", "order_status"); + Reply r2 = Wire.post(url, wrongMethod, call); + t.exchange("2. Mcp-Method says tools/list, the body says tools/call", "/mcp", wrongMethod, call, r2); + assertThat(r2.status()).isEqualTo(400); + assertThat(r2.json().path("error").path("code").asInt()).isEqualTo(-32020); + + // The body must carry _meta, the header alone is not enough + String noMeta = "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}"; + Map listHeaders = Wire.modernHeaders("tools/list", null); + Reply r3 = Wire.post(url, listHeaders, noMeta); + t.exchange("3. the version header is present but params._meta is missing", "/mcp", listHeaders, noMeta, r3); + assertThat(r3.status()).isEqualTo(400); + assertThat(r3.json().path("error").path("message").asString()).isEqualTo("params._meta is required"); + + // A version the server does not speak + Map future = Wire.modernHeaders("tools/list", null); + future.put("MCP-Protocol-Version", "2027-01-01"); + String futureBody = "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":" + + "{\"_meta\":{\"io.modelcontextprotocol/protocolVersion\":\"2027-01-01\"}}}"; + Reply r4 = Wire.post(url, future, futureBody); + t.exchange("4. a protocol version the server does not support", "/mcp", future, futureBody, r4); + assertThat(r4.status()).isEqualTo(400); + assertThat(r4.json().path("error").path("code").asInt()).isEqualTo(-32022); + assertThat(r4.json().path("error").path("data").path("supported").get(0).asString()).isEqualTo(Wire.MODERN_VERSION); + + // What a 2025 client sends first + Reply r5 = Wire.post(url, Wire.legacyHeaders(null), Wire.INITIALIZE); + t.exchange("5. a 2025-era client's first request, initialize", "/mcp", Wire.legacyHeaders(null), Wire.INITIALIZE, r5); + assertThat(r5.status()).isEqualTo(400); + assertThat(r5.json().path("error").path("code").asInt()).isEqualTo(-32020); + + // A session id is simply not part of this protocol; this server does not reject it either + Map stray = new LinkedHashMap<>(Wire.modernHeaders("tools/call", "order_status")); + stray.put("Mcp-Session-Id", "left-over-from-a-2025-client"); + Reply r6 = Wire.post(url, stray, call); + t.exchange("6. a stray Mcp-Session-Id on a modern request", "/mcp", stray, call, r6); + assertThat(r6.status()).isEqualTo(200); + + // POST only + Reply r7 = Wire.get(url); + t.blank().line("## 7. GET /mcp").line("< " + r7.status()).line("< Allow: " + r7.header("Allow")); + assertThat(r7.status()).isEqualTo(405); + + // Unknown tool and invalid arguments + Map nope = Wire.modernHeaders("tools/call", "nope"); + Reply r8 = Wire.post(url, nope, Wire.modernCall(3, "nope", "{}")); + t.exchange("8. unknown tool", "/mcp", nope, Wire.modernCall(3, "nope", "{}"), r8); + assertThat(r8.json().path("error").path("code").asInt()).isEqualTo(-32602); + + Map noArg = Wire.modernHeaders("tools/call", "order_status"); + Reply r9 = Wire.post(url, noArg, Wire.modernCall(3, "order_status", "{}")); + t.exchange("9. a missing argument", "/mcp", noArg, Wire.modernCall(3, "order_status", "{}"), r9); + assertThat(r9.status()).isEqualTo(200); + assertThat(r9.json().path("result").path("isError").asBoolean()).isTrue(); + t.write(); + } +} diff --git a/mcp-stateless/src/test/java/com/ankurm/mcpstateless/MultiRoundTripTest.java b/mcp-stateless/src/test/java/com/ankurm/mcpstateless/MultiRoundTripTest.java new file mode 100644 index 0000000..7e6ea82 --- /dev/null +++ b/mcp-stateless/src/test/java/com/ankurm/mcpstateless/MultiRoundTripTest.java @@ -0,0 +1,92 @@ +package com.ankurm.mcpstateless; + +import static org.assertj.core.api.Assertions.assertThat; + +import java.nio.charset.StandardCharsets; +import java.util.Base64; +import java.util.Map; + +import com.ankurm.mcpstateless.support.Instance; +import com.ankurm.mcpstateless.support.Transcript; +import com.ankurm.mcpstateless.support.Wire; +import com.ankurm.mcpstateless.support.Wire.Reply; + +import org.junit.jupiter.api.Test; + +/** + * The replacement for asking the user in the middle of a call: return input_required, let the client retry. + * The retry may land on a different instance, and that is where the sealed requestState needs a shared secret. + */ +class MultiRoundTripTest { + + static final String ARGS = "{\"orderId\":\"A-101\"}"; + static final String YES = "{\"action\":\"accept\",\"content\":{\"ok\":true}}"; + static final String NO = "{\"action\":\"decline\"}"; + + private static Reply firstRound(Instance on, Transcript t, String label) { + Map h = Wire.modernHeaders("tools/call", "cancel_order"); + String body = Wire.modernCall(1, "cancel_order", ARGS); + Reply r = Wire.post(on.url(), h, body); + t.exchange(label, "/mcp (" + on.name() + ")", h, body, r); + return r; + } + + private static Reply retry(Instance on, Transcript t, String label, String state, String answer) { + Map h = Wire.modernHeaders("tools/call", "cancel_order"); + String body = Wire.modernRetry(2, "cancel_order", ARGS, answer, state); + Reply r = Wire.post(on.url(), h, body); + t.exchange(label, "/mcp (" + on.name() + ")", h, body.replace(state, ""), r); + return r; + } + + @Test + void withoutASharedSecretTheRetryMustReturnToTheSameInstance() { + Transcript t = new Transcript("06-modern-mrtr.txt", + "Multi-round-trip request: cancel_order asks for confirmation by returning input_required"); + try (Instance m1 = Instance.start("modern", "M1"); Instance m2 = Instance.start("modern", "M2")) { + t.note("PART A: no spring.ai.mcp.server.modern.request-state-secret, so each instance seals with its own random key."); + Reply first = firstRound(m1, t, "A1. first call, no answer yet"); + assertThat(first.status()).isEqualTo(200); + assertThat(first.json().path("result").path("resultType").asString()).isEqualTo("input_required"); + assertThat(first.json().path("result").path("inputRequests").path("confirm").path("method").asString()) + .isEqualTo("elicitation/create"); + String state = first.json().path("result").path("requestState").asString(); + + // What "sealed" means: signed, not encrypted + String payload = new String(Base64.getUrlDecoder().decode(state.split("\\.")[0]), StandardCharsets.UTF_8); + t.blank().note("The part of requestState before the dot is base64url JSON, readable by anyone who holds it:"); + t.line(" " + payload.replaceAll("\"exp\":[0-9]+", "\"exp\":")); + assertThat(payload).contains("\"s\":\"orderId=A-101\"").contains("\"m\":\"tools/call\"") + .contains("\"n\":\"cancel_order\""); + + Reply sameInstance = retry(m1, t, "A2. retry, answer yes, back on the SAME instance", state, YES); + assertThat(sameInstance.text()).isEqualTo("order A-101 cancelled (answered by instance M1)"); + + Reply otherInstance = retry(m2, t, "A3. the same retry, but the balancer sends it to the OTHER instance", state, YES); + assertThat(otherInstance.status()).isEqualTo(400); + assertThat(otherInstance.json().path("error").path("code").asInt()).isEqualTo(-32602); + assertThat(otherInstance.json().path("error").path("message").asString()) + .isEqualTo("Invalid or expired requestState"); + + String tampered = state.substring(0, state.length() - 3) + (state.endsWith("AAA") ? "BBB" : "AAA"); + Reply forged = retry(m1, t, "A4. the right instance, but the state was altered in transit", tampered, YES); + assertThat(forged.status()).isEqualTo(400); + assertThat(forged.json().path("error").path("message").asString()).isEqualTo("Invalid or expired requestState"); + } + + t.blank().note("PART B: the same secret on every instance (32 bytes or more)."); + Map secret = Map.of("spring.ai.mcp.server.modern.request-state-secret", + "0123456789abcdef0123456789abcdef-demo-only-secret"); + try (Instance m1 = Instance.start("modern", "M1", secret); Instance m2 = Instance.start("modern", "M2", secret)) { + Reply first = firstRound(m1, t, "B1. first call on M1"); + String state = first.json().path("result").path("requestState").asString(); + Reply other = retry(m2, t, "B2. retry, answer yes, on M2", state, YES); + assertThat(other.status()).isEqualTo(200); + assertThat(other.text()).isEqualTo("order A-101 cancelled (answered by instance M2)"); + + Reply declined = retry(m1, t, "B3. the user declines, retry on M1", state, NO); + assertThat(declined.text()).isEqualTo("order A-101 kept (answered by instance M1)"); + } + t.write(); + } +} diff --git a/mcp-stateless/src/test/java/com/ankurm/mcpstateless/SdkClientsTest.java b/mcp-stateless/src/test/java/com/ankurm/mcpstateless/SdkClientsTest.java new file mode 100644 index 0000000..f3adcae --- /dev/null +++ b/mcp-stateless/src/test/java/com/ankurm/mcpstateless/SdkClientsTest.java @@ -0,0 +1,167 @@ +package com.ankurm.mcpstateless; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.assertThatThrownBy; + +import java.net.URI; +import java.util.List; +import java.util.Map; + +import com.ankurm.mcpstateless.support.Instance; +import com.ankurm.mcpstateless.support.Proxy; +import com.ankurm.mcpstateless.support.Transcript; +import com.ankurm.mcpstateless.support.Wire; + +import io.modelcontextprotocol.modern.McpSchema.CallToolResult; +import io.modelcontextprotocol.modern.McpSchema.DiscoverResult; +import io.modelcontextprotocol.modern.McpSchema.ElicitResult; +import io.modelcontextprotocol.modern.McpSchema.Implementation; +import io.modelcontextprotocol.modern.McpSchema.TextContent; +import io.modelcontextprotocol.modern.client.McpClient; +import io.modelcontextprotocol.modern.client.McpSyncClient; +import io.modelcontextprotocol.modern.client.transport.HttpClientMcpTransport; + +import org.junit.jupiter.api.Test; + +/** Real SDK clients, not hand-written HTTP: the 2.2.0 modern client and the 2025-era client against both server generations. */ +class SdkClientsTest { + + static final Map SECRET = Map.of("spring.ai.mcp.server.modern.request-state-secret", + "0123456789abcdef0123456789abcdef-demo-only-secret"); + + static McpSyncClient modernClient(String url) { + URI uri = URI.create(url); + return McpClient.sync(HttpClientMcpTransport.builder(uri).build()) + .clientInfo(Implementation.builder("sdk-modern-client", "1").build()) + .formElicitation(req -> ElicitResult.builder(ElicitResult.Action.ACCEPT).content(Map.of("ok", true)).build()) + .build(); + } + + /** First line only, ports masked and the serialised Java stack trace cut off, so reruns diff cleanly. */ + static String shorten(String message) { + String m = message.lines().findFirst().orElse("").replaceAll("localhost:[0-9]+", "localhost:") + .replaceAll("\"id\":\"[0-9a-f]{8}-[0-9]+\"", "\"id\":\"\""); + int cut = m.indexOf(",\"cause\""); + return cut > 0 ? m.substring(0, cut) + "... (stack trace omitted)" : m; + } + + static String text(CallToolResult r) { + return ((TextContent) r.content().get(0)).text(); + } + + @Test + void modernClientThroughARoundRobinBalancer() { + Transcript t = new Transcript("08-sdk-modern-client.txt", + "The 2.2.0 modern SDK client against two 2026-07-28 instances behind round-robin"); + try (Instance m1 = Instance.start("modern", "M1", SECRET); Instance m2 = Instance.start("modern", "M2", SECRET)) { + Proxy.Pool pool = new Proxy.Pool(List.of(m1, m2)); + try (Proxy lb = new Proxy(h -> pool)) { + McpSyncClient client = modernClient(lb.url()); + DiscoverResult discover = client.discover(); + t.line("discover: supportedVersions=" + discover.supportedVersions() + " ttlMs=" + discover.ttlMs() + + " cacheScope=" + discover.cacheScope()); + t.line("tools: " + client.listTools().list().tools().stream().map(x -> x.name()).sorted().toList()); + for (int i = 0; i < 4; i++) { + CallToolResult r = client.tool("order_status").arguments(Map.of("orderId", "A-100")).call(); + t.line("order_status #" + (i + 1) + ": " + text(r)); + } + CallToolResult cancel = client.tool("cancel_order").arguments(Map.of("orderId", "A-102")).call(); + t.line("cancel_order (the client answered the confirmation itself): " + text(cancel)); + t.blank().line("What the balancer saw, in order:"); + lb.seen().forEach(s -> t.line(" " + s)); + t.line("total requests: " + lb.seen().size()); + + assertThat(discover.supportedVersions()).containsExactly(Wire.MODERN_VERSION); + assertThat(discover.ttlMs()).isEqualTo(300_000L); + assertThat(text(cancel)).isEqualTo("order A-102 cancelled (answered by instance M2)"); + assertThat(lb.seen()).hasSize(8).noneMatch(x -> x.contains("initialize")); + } + } + + t.blank().note("Same client and balancer, but the instances have no shared request-state-secret:"); + try (Instance m1 = Instance.start("modern", "M1"); Instance m2 = Instance.start("modern", "M2")) { + Proxy.Pool pool = new Proxy.Pool(List.of(m1, m2)); + try (Proxy lb = new Proxy(h -> pool)) { + McpSyncClient client = modernClient(lb.url()); + Throwable failure = org.assertj.core.api.Assertions.catchThrowable( + () -> client.tool("cancel_order").arguments(Map.of("orderId", "A-102")).call()); + t.line("cancel_order: " + failure.getClass().getName()); + t.line(" " + shorten(String.valueOf(failure.getMessage()))); + assertThat(failure).isNotNull(); + assertThat(String.valueOf(failure.getMessage())).contains("Invalid or expired requestState"); + } + } + t.write(); + } + + @Test + void oldAndNewClientsAgainstTheWrongServer() { + Transcript t = new Transcript("09-sdk-version-mismatch.txt", + "What each SDK client says when it meets a server of the other generation"); + try (Instance legacy = Instance.start("legacy", "L1"); Instance modern = Instance.start("modern", "M1")) { + + // 2025-era client -> modern server + String base = "http://localhost:" + modern.port(); + var oldClient = io.modelcontextprotocol.client.McpClient + .sync(io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport.builder(base) + .endpoint("/mcp").build()) + .build(); + Throwable a = org.assertj.core.api.Assertions.catchThrowable(oldClient::initialize); + t.line("2025-era client -> modern server: " + a.getClass().getName()); + for (Throwable c = a; c != null; c = c.getCause()) { + t.line(" " + c.getClass().getSimpleName() + ": " + shorten(String.valueOf(c.getMessage()))); + } + assertThat(a).isNotNull(); + + // modern client -> 2025-era server + McpSyncClient newClient = modernClient(legacy.url()); + Throwable b = org.assertj.core.api.Assertions.catchThrowable(newClient::discover); + t.line("modern client -> 2025-era server: " + b.getClass().getName()); + t.line(" " + shorten(String.valueOf(b.getMessage()))); + assertThat(b).isNotNull(); + } + t.write(); + } + + @Test + void bothSdkClientsThroughOneUrl() { + Transcript t = new Transcript("10-sdk-clients-through-router.txt", + "A 2025-era SDK client and a 2026-07-28 SDK client, one router URL, split on MCP-Protocol-Version"); + try (Instance legacy = Instance.start("legacy", "L1"); + Instance m1 = Instance.start("modern", "M1", SECRET); + Instance m2 = Instance.start("modern", "M2", SECRET)) { + Proxy.Pool legacyPool = new Proxy.Pool(List.of(legacy), true); + Proxy.Pool modernPool = new Proxy.Pool(List.of(m1, m2)); + try (Proxy router = new Proxy(h -> BothVersionsTest.isModern(h) ? modernPool : legacyPool)) { + String base = router.url().replace("/mcp", ""); + + var oldClient = io.modelcontextprotocol.client.McpClient + .sync(io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport.builder(base) + .endpoint("/mcp").build()) + .build(); + oldClient.initialize(); + var oldResult = oldClient.callTool(new io.modelcontextprotocol.spec.McpSchema.CallToolRequest( + "order_status", Map.of("orderId", "A-101"))); + String oldText = ((io.modelcontextprotocol.spec.McpSchema.TextContent) oldResult.content().get(0)).text(); + t.line("2025-era client: " + oldText); + oldClient.closeGracefully(); + + McpSyncClient newClient = modernClient(router.url()); + String newText = text(newClient.tool("order_status").arguments(Map.of("orderId", "A-101")).call()); + t.line("2026-07-28 client: " + newText); + + // The 2025 client's GET (its optional server-to-client stream) races with its other calls, so count, don't order. + t.blank().line("What the router saw (HTTP method and Mcp-Method header; '-' means the header is absent):"); + java.util.Map counts = router.seen().stream() + .collect(java.util.stream.Collectors.groupingBy(x -> x, java.util.TreeMap::new, + java.util.stream.Collectors.counting())); + counts.forEach((k, v) -> t.line(" " + v + " x " + k)); + assertThat(oldText).isEqualTo("order A-101 is SHIPPED (answered by instance L1)"); + assertThat(newText).startsWith("order A-101 is SHIPPED (answered by instance M"); + assertThat(counts).containsEntry("POST -", 3L).containsEntry("GET -", 1L).containsEntry("DELETE -", 1L) + .containsEntry("POST tools/list", 1L).containsEntry("POST tools/call", 1L); + } + } + t.write(); + } +} diff --git a/mcp-stateless/src/test/java/com/ankurm/mcpstateless/support/Instance.java b/mcp-stateless/src/test/java/com/ankurm/mcpstateless/support/Instance.java new file mode 100644 index 0000000..6869a74 --- /dev/null +++ b/mcp-stateless/src/test/java/com/ankurm/mcpstateless/support/Instance.java @@ -0,0 +1,61 @@ +package com.ankurm.mcpstateless.support; + +import java.util.LinkedHashMap; +import java.util.Map; + +import com.ankurm.mcpstateless.StatelessApp; + +import org.springframework.boot.builder.SpringApplicationBuilder; +import org.springframework.context.ConfigurableApplicationContext; + +/** One real server process-in-a-JVM: a full Spring Boot application on its own random port. */ +public final class Instance implements AutoCloseable { + + private final String name; + private final ConfigurableApplicationContext context; + private final int port; + + private Instance(String name, ConfigurableApplicationContext context) { + this.name = name; + this.context = context; + this.port = Integer.parseInt(context.getEnvironment().getProperty("local.server.port")); + } + + /** @param profile {@code legacy} or {@code modern}; @param extra extra properties, e.g. the request-state secret */ + public static Instance start(String profile, String name, Map extra) { + Map props = new LinkedHashMap<>(); + props.put("server.port", 0); + props.put("instance.name", name); + props.put("spring.main.web-application-type", "servlet"); + props.putAll(extra); + return new Instance(name, new SpringApplicationBuilder(StatelessApp.class) + .profiles(profile) + .properties(props) + .run("--logging.level.root=error")); + } + + public static Instance start(String profile, String name) { + return start(profile, name, Map.of()); + } + + public String name() { + return name; + } + + public int port() { + return port; + } + + public String url() { + return "http://localhost:" + port + "/mcp"; + } + + public boolean running() { + return context.isActive(); + } + + @Override + public void close() { + context.close(); + } +} diff --git a/mcp-stateless/src/test/java/com/ankurm/mcpstateless/support/Proxy.java b/mcp-stateless/src/test/java/com/ankurm/mcpstateless/support/Proxy.java new file mode 100644 index 0000000..6600024 --- /dev/null +++ b/mcp-stateless/src/test/java/com/ankurm/mcpstateless/support/Proxy.java @@ -0,0 +1,157 @@ +package com.ankurm.mcpstateless.support; + +import java.io.IOException; +import java.net.InetSocketAddress; +import java.net.URI; +import java.net.http.HttpClient; +import java.net.http.HttpRequest; +import java.net.http.HttpResponse; +import java.time.Duration; +import java.util.List; +import java.util.Locale; +import java.util.Map; +import java.util.Set; +import java.util.concurrent.ConcurrentHashMap; +import java.util.concurrent.atomic.AtomicInteger; +import java.util.function.Function; + +import com.sun.net.httpserver.HttpServer; + +/** + * A deliberately plain HTTP reverse proxy, standing in for a cloud load balancer. A {@link Pool} hands out + * its backends round-robin. A request whose backend refuses the connection is retried on the next one, + * as any real balancer does with a failed health check. It never looks at MCP, except that a pool can + * be told to learn session affinity from the {@code Mcp-Session-Id} response header. + */ +public final class Proxy implements AutoCloseable { + + /** A set of interchangeable servers. */ + public static final class Pool { + + private final List backends; + private final boolean sticky; + private final AtomicInteger next = new AtomicInteger(); + private final Map bySession = new ConcurrentHashMap<>(); + + public Pool(List backends, boolean sticky) { + this.backends = backends; + this.sticky = sticky; + } + + public Pool(List backends) { + this(backends, false); + } + + List candidates(String sessionId) { + if (sticky && sessionId != null && bySession.containsKey(sessionId) && bySession.get(sessionId).running()) { + return List.of(bySession.get(sessionId)); + } + int start = Math.floorMod(next.getAndIncrement(), backends.size()); + return java.util.stream.IntStream.range(0, backends.size()) + .mapToObj(i -> backends.get((start + i) % backends.size())).toList(); + } + + void learn(String sessionId, Instance served) { + if (sticky && sessionId != null) { + bySession.put(sessionId, served); + } + } + } + + private static final Set SKIP_REQUEST = Set.of("host", "content-length", "connection", "expect", "upgrade"); + private static final Set SKIP_RESPONSE = Set.of("transfer-encoding", "content-length", "connection"); + + private final java.util.List seen = new java.util.concurrent.CopyOnWriteArrayList<>(); + private final HttpServer server; + private final HttpClient client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(2)).build(); + private final Function, Pool> route; + + /** @param route picks the pool from the request headers (lower-cased names) */ + public Proxy(Function, Pool> route) { + this.route = route; + try { + server = HttpServer.create(new InetSocketAddress("localhost", 0), 0); + } + catch (IOException e) { + throw new IllegalStateException(e); + } + server.createContext("/", exchange -> { + try { + byte[] body = exchange.getRequestBody().readAllBytes(); + Map headers = new ConcurrentHashMap<>(); + exchange.getRequestHeaders().forEach((k, v) -> headers.put(k.toLowerCase(Locale.ROOT), v.get(0))); + seen.add(exchange.getRequestMethod() + " " + headers.getOrDefault("mcp-method", "-")); + if (exchange.getRequestMethod().equals("GET")) { + // The optional server-initiated SSE stream of the 2025 transport. A real balancer would have to hold + // that connection open and pinned to one instance. This one answers 405, which the 2025 clients accept. + exchange.getResponseHeaders().add("Allow", "POST"); + exchange.sendResponseHeaders(405, -1); + return; + } + Pool pool = route.apply(headers); + String session = headers.get("mcp-session-id"); + HttpResponse response = null; + Instance served = null; + for (Instance candidate : pool.candidates(session)) { + if (!candidate.running()) { + continue; + } + HttpRequest.Builder b = HttpRequest.newBuilder( + URI.create("http://localhost:" + candidate.port() + exchange.getRequestURI())) + .method(exchange.getRequestMethod(), HttpRequest.BodyPublishers.ofByteArray(body)); + exchange.getRequestHeaders().forEach((k, v) -> { + if (!SKIP_REQUEST.contains(k.toLowerCase(Locale.ROOT))) { + b.header(k, v.get(0)); + } + }); + try { + response = client.send(b.build(), HttpResponse.BodyHandlers.ofByteArray()); + served = candidate; + break; + } + catch (IOException refused) { + // connection refused: try the next backend + } + } + if (response == null) { + exchange.sendResponseHeaders(502, -1); + return; + } + response.headers().map().forEach((k, v) -> { + if (!SKIP_RESPONSE.contains(k.toLowerCase(Locale.ROOT))) { + exchange.getResponseHeaders().add(k, v.get(0)); + } + }); + exchange.getResponseHeaders().add("X-Served-By", served.name()); + final Instance finalServed = served; + response.headers().firstValue("Mcp-Session-Id").ifPresent(id -> pool.learn(id, finalServed)); + byte[] out = response.body(); + exchange.sendResponseHeaders(response.statusCode(), out.length == 0 ? -1 : out.length); + if (out.length > 0) { + exchange.getResponseBody().write(out); + } + } + catch (Exception e) { + exchange.sendResponseHeaders(500, -1); + } + finally { + exchange.close(); + } + }); + server.start(); + } + + /** Every request the proxy has received, as {@code HTTP-METHOD mcp-method-header}. */ + public java.util.List seen() { + return seen; + } + + public String url() { + return "http://localhost:" + server.getAddress().getPort() + "/mcp"; + } + + @Override + public void close() { + server.stop(0); + } +} diff --git a/mcp-stateless/src/test/java/com/ankurm/mcpstateless/support/Transcript.java b/mcp-stateless/src/test/java/com/ankurm/mcpstateless/support/Transcript.java new file mode 100644 index 0000000..74c3806 --- /dev/null +++ b/mcp-stateless/src/test/java/com/ankurm/mcpstateless/support/Transcript.java @@ -0,0 +1,128 @@ +package com.ankurm.mcpstateless.support; + +import java.io.IOException; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.List; +import java.util.Map; + +import tools.jackson.databind.JsonNode; +import tools.jackson.databind.node.ObjectNode; + +/** + * Writes {@code output/NN-name.txt}. The test that fills a transcript also asserts the same facts, so a + * number quoted in the post is a number the build checks. Random values are replaced so reruns diff cleanly. + */ +public final class Transcript { + + private static final List SHOWN = List.of("mcp-session-id", "content-type", "allow", "x-served-by"); + private static final List REQUEST_HEADERS = List.of("MCP-Protocol-Version", "Mcp-Method", "Mcp-Name", + "Mcp-Session-Id"); + + private final StringBuilder out = new StringBuilder(); + private final String file; + + public Transcript(String file, String title) { + this.file = file; + out.append("# ").append(title).append('\n'); + } + + public Transcript note(String text) { + out.append("# ").append(text).append('\n'); + return this; + } + + public Transcript blank() { + out.append('\n'); + return this; + } + + public Transcript line(String text) { + out.append(text).append('\n'); + return this; + } + + /** One request/response pair. {@code via} says where the request was sent. */ + public Transcript exchange(String label, String via, Map requestHeaders, String requestBody, + Wire.Reply reply) { + out.append('\n').append("## ").append(label).append('\n'); + out.append("> POST ").append(via).append('\n'); + for (String name : REQUEST_HEADERS) { + requestHeaders.forEach((k, v) -> { + if (k.equalsIgnoreCase(name)) { + out.append("> ").append(k).append(": ").append(clean(v)).append('\n'); + } + }); + } + out.append("> ").append(clean(compact(requestBody))).append('\n'); + out.append("< ").append(reply.status()).append('\n'); + for (String name : SHOWN) { + String v = reply.header(name); + if (v != null) { + out.append("< ").append(canonical(name)).append(": ").append(clean(v)).append('\n'); + } + } + String body = reply.body(); + if (!body.isBlank()) { + for (String l : body.strip().split("\n")) { + if (!l.isBlank()) { + out.append("< ").append(clean(compact(l))).append('\n'); + } + } + } + return this; + } + + private static String canonical(String lower) { + return switch (lower) { + case "mcp-session-id" -> "Mcp-Session-Id"; + case "content-type" -> "Content-Type"; + case "x-served-by" -> "X-Served-By"; + default -> "Allow"; + }; + } + + /** Re-serialises JSON on one line and drops the Java stack trace the 2.x SDK serialises into 2025-era error bodies. */ + private static String compact(String s) { + String t = s.strip(); + String prefix = ""; + if (t.startsWith("data:")) { + prefix = "data: "; + t = t.substring(5).strip(); + } + if (!t.startsWith("{")) { + return s.strip(); + } + try { + JsonNode n = Wire.JSON.readTree(t); + if (n instanceof ObjectNode o && o.has("stackTrace")) { + o.remove(List.of("stackTrace", "suppressed", "localizedMessage", "cause", "message")); + } + return prefix + Wire.JSON.writeValueAsString(n); + } + catch (Exception e) { + return s.strip(); + } + } + + private static String clean(String s) { + s = s.replaceAll("\"requestState\":\"[^\"]+\"", "\"requestState\":\"\""); + return s.replaceAll("[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}", ""); + } + + public void write() { + try { + Path dir = Path.of(System.getProperty("user.dir"), "output"); + Files.createDirectories(dir); + Files.writeString(dir.resolve(file), out.toString(), StandardCharsets.UTF_8); + } + catch (IOException e) { + throw new IllegalStateException(e); + } + } + + public String text() { + return out.toString(); + } +} diff --git a/mcp-stateless/src/test/java/com/ankurm/mcpstateless/support/Wire.java b/mcp-stateless/src/test/java/com/ankurm/mcpstateless/support/Wire.java new file mode 100644 index 0000000..df7d35d --- /dev/null +++ b/mcp-stateless/src/test/java/com/ankurm/mcpstateless/support/Wire.java @@ -0,0 +1,139 @@ +package com.ankurm.mcpstateless.support; + +import java.net.URI; +import java.net.http.HttpClient; +import java.net.http.HttpRequest; +import java.net.http.HttpResponse; +import java.time.Duration; +import java.util.LinkedHashMap; +import java.util.Map; + +import tools.jackson.databind.JsonNode; +import tools.jackson.databind.json.JsonMapper; + +/** Raw HTTP to an MCP endpoint, so the tests see exactly what is on the wire and nothing is hidden by a client library. */ +public final class Wire { + + public static final String LEGACY_VERSION = "2025-11-25"; + public static final String MODERN_VERSION = "2026-07-28"; + public static final JsonMapper JSON = JsonMapper.builder().build(); + + private static final HttpClient HTTP = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(5)).build(); + + private Wire() { + } + + public record Reply(int status, Map headers, String body) { + + public String header(String name) { + return headers.get(name.toLowerCase()); + } + + /** The JSON-RPC message: the body itself, or the {@code data:} line of an SSE frame. */ + public JsonNode json() { + String text = body; + for (String line : body.split("\n")) { + if (line.startsWith("data:")) { + text = line.substring(5).trim(); + } + } + return JSON.readTree(text); + } + + public String text() { + return json().path("result").path("content").path(0).path("text").asString(); + } + } + + public static Reply post(String url, Map headers, String body) { + try { + HttpRequest.Builder b = HttpRequest.newBuilder(URI.create(url)) + .timeout(Duration.ofSeconds(10)) + .POST(HttpRequest.BodyPublishers.ofString(body)); + headers.forEach(b::header); + HttpResponse r = HTTP.send(b.build(), HttpResponse.BodyHandlers.ofString()); + Map h = new LinkedHashMap<>(); + r.headers().map().forEach((k, v) -> h.put(k.toLowerCase(), String.join(", ", v))); + return new Reply(r.statusCode(), h, r.body()); + } + catch (Exception e) { + throw new IllegalStateException("POST " + url + " failed", e); + } + } + + public static Reply get(String url) { + try { + HttpResponse r = HTTP.send(HttpRequest.newBuilder(URI.create(url)).GET().build(), + HttpResponse.BodyHandlers.ofString()); + Map h = new LinkedHashMap<>(); + r.headers().map().forEach((k, v) -> h.put(k.toLowerCase(), String.join(", ", v))); + return new Reply(r.statusCode(), h, r.body()); + } + catch (Exception e) { + throw new IllegalStateException("GET " + url + " failed", e); + } + } + + // ---- 2025-era requests ------------------------------------------------------------------------------- + + public static Map legacyHeaders(String sessionId) { + Map h = new LinkedHashMap<>(); + h.put("Content-Type", "application/json"); + h.put("Accept", "application/json, text/event-stream"); + if (sessionId != null) { + h.put("Mcp-Session-Id", sessionId); + h.put("MCP-Protocol-Version", LEGACY_VERSION); + } + return h; + } + + public static final String INITIALIZE = "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":" + + "{\"protocolVersion\":\"" + LEGACY_VERSION + "\",\"capabilities\":{}," + + "\"clientInfo\":{\"name\":\"wire-test\",\"version\":\"1\"}}}"; + + public static final String INITIALIZED = "{\"jsonrpc\":\"2.0\",\"method\":\"notifications/initialized\"}"; + + public static String legacyCall(int id, String orderId) { + return "{\"jsonrpc\":\"2.0\",\"id\":" + id + ",\"method\":\"tools/call\",\"params\":" + + "{\"name\":\"order_status\",\"arguments\":{\"orderId\":\"" + orderId + "\"}}}"; + } + + // ---- 2026-07-28 requests ----------------------------------------------------------------------------- + + public static final String META = "\"_meta\":{\"io.modelcontextprotocol/protocolVersion\":\"" + MODERN_VERSION + "\"," + + "\"io.modelcontextprotocol/clientInfo\":{\"name\":\"wire-test\",\"version\":\"1\"}," + + "\"io.modelcontextprotocol/clientCapabilities\":{\"elicitation\":{\"form\":{}}}}"; + + /** Headers for a modern request. {@code name} is the tool/prompt/resource name, or null for methods without one. */ + public static Map modernHeaders(String method, String name) { + Map h = new LinkedHashMap<>(); + h.put("Content-Type", "application/json"); + h.put("Accept", "application/json, text/event-stream"); + h.put("MCP-Protocol-Version", MODERN_VERSION); + h.put("Mcp-Method", method); + if (name != null) { + h.put("Mcp-Name", name); + } + return h; + } + + public static String modernDiscover() { + return "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"server/discover\",\"params\":{" + META + "}}"; + } + + public static String modernList() { + return "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{" + META + "}}"; + } + + public static String modernCall(int id, String tool, String arguments) { + return "{\"jsonrpc\":\"2.0\",\"id\":" + id + ",\"method\":\"tools/call\",\"params\":{\"name\":\"" + tool + + "\",\"arguments\":" + arguments + "," + META + "}}"; + } + + /** The retry of an input-required call: the same call plus the client's answer and the server's sealed state. */ + public static String modernRetry(int id, String tool, String arguments, String answerJson, String requestState) { + return "{\"jsonrpc\":\"2.0\",\"id\":" + id + ",\"method\":\"tools/call\",\"params\":{\"name\":\"" + tool + + "\",\"arguments\":" + arguments + ",\"inputResponses\":{\"confirm\":" + answerJson + + "},\"requestState\":\"" + requestState + "\"," + META + "}}"; + } +} diff --git a/pom.xml b/pom.xml index 5b068e1..9561dc3 100644 --- a/pom.xml +++ b/pom.xml @@ -21,6 +21,7 @@ mcp-sdk-plain koog claude-code-spring + mcp-stateless