Add mcp-server module: order-lookup service exposed via @McpTool/@McpResource/@McpPrompt over Streamable HTTP
Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01FtpJvZfg4nvLvtzgJTDWpB
This commit is contained in:
Claude
@@ -6,5 +6,6 @@ Runnable companion code for the Spring AI articles on [ankurm.com](https://ankur
|
||||
|---|---|---|
|
||||
| [`getting-started/`](getting-started) | One `ChatClient` bean, three endpoints (plain call, templated system prompt, streaming), and a test proving `spring.ai.model.chat` switches providers with zero code change. Spring Boot 4.1.1, Spring AI 2.0.1, Java 25. | [Spring AI 2.0 in 10 Minutes: ChatClient on Spring Boot 4.1](https://ankurm.com/spring-ai-2-0-chatclient-boot-4-1/) |
|
||||
| [`rag/`](rag) | Ingest PDFs, chunk, retrieve from pgvector, rerank, answer, check the answer. Spring Boot 4.1.1, Spring AI 2.0.1, Java 25. | [Production-grade RAG with Spring AI](https://ankurm.com/production-rag-spring-ai-java/) and [the complete example](https://ankurm.com/spring-ai-rag-complete-example/) |
|
||||
| [`mcp-server/`](mcp-server) | An order-lookup service exposed as MCP tools, a resource, and a prompt with `@McpTool`/`@McpResource`/`@McpPrompt`, served over Streamable HTTP (Spring AI 2.0's default MCP server transport). Spring Boot 4.1.1, Spring AI 2.0.1, Java 25. | [Build an MCP Server with Spring AI 2.0](https://ankurm.com/spring-ai-2-0-mcp-server-streamable-http/) |
|
||||
|
||||
Upgrading from Spring AI 1.x: [migration guide](https://ankurm.com/spring-ai-1-to-2-migration-guide/).
|
||||
|
||||
@@ -0,0 +1 @@
|
||||
target/
|
||||
@@ -0,0 +1,91 @@
|
||||
# mcp-server
|
||||
|
||||
An existing Spring service -- an order-lookup repository, nothing MCP-aware about it -- exposed
|
||||
as MCP tools, resources, and a prompt with `@McpTool`/`@McpResource`/`@McpPrompt`, served over
|
||||
Streamable HTTP: Spring AI 2.0's default MCP server transport.
|
||||
|
||||
Companion code for [Build an MCP Server with Spring AI 2.0](https://ankurm.com/spring-ai-2-0-mcp-server-streamable-http/) on [ankurm.com](https://ankurm.com).
|
||||
|
||||
## Versions
|
||||
|
||||
Spring Boot **4.1.1**, Spring AI **2.0.1**, Java **25** (LTS) -- same baseline as the rest of this
|
||||
repository.
|
||||
|
||||
## Quickstart
|
||||
|
||||
```
|
||||
./scripts/run.sh
|
||||
```
|
||||
|
||||
Then, in another shell:
|
||||
|
||||
```
|
||||
curl -X POST http://localhost:8080/mcp \
|
||||
-H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
|
||||
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'
|
||||
```
|
||||
|
||||
or point [MCP Inspector](https://github.com/modelcontextprotocol/inspector) or Claude Desktop's
|
||||
MCP settings at `http://localhost:8080/mcp`.
|
||||
|
||||
## What's exposed
|
||||
|
||||
| Kind | Name | What it does |
|
||||
|---|---|---|
|
||||
| Tool | `lookup_order` | Looks up one order by ID; returns customer, status, items, total |
|
||||
| Resource | `orders://catalog` | Every order ID currently in the system, one per line |
|
||||
| Prompt | `summarize_order` | A ready-made prompt asking a model to summarize one order for support |
|
||||
|
||||
All three live in [`OrderTools.java`](src/main/java/com/ankurm/mcpserver/tools/OrderTools.java),
|
||||
which imports nothing MCP-specific except the three annotations -- the domain type
|
||||
([`Order.java`](src/main/java/com/ankurm/mcpserver/domain/Order.java)) and the repository behind
|
||||
it ([`OrderRepository.java`](src/main/java/com/ankurm/mcpserver/domain/OrderRepository.java))
|
||||
would exist whether or not MCP was ever wired in.
|
||||
|
||||
## The one property that matters
|
||||
|
||||
```yaml
|
||||
spring:
|
||||
ai:
|
||||
mcp:
|
||||
server:
|
||||
protocol: streamable
|
||||
```
|
||||
|
||||
The jar's own `spring-configuration-metadata.json` lists `streamable` as this property's default
|
||||
-- but leave it out of `application.yml` and the `/mcp` endpoint never gets registered at all
|
||||
(a plain 404, not a clearer error). See
|
||||
[`output/06-protocol-property-unset-404.txt`](output/06-protocol-property-unset-404.txt) for the
|
||||
real condition-evaluation log line that explains why, and the article for the full story.
|
||||
|
||||
## Tests and captured output
|
||||
|
||||
`OrderMcpServerTest` drives the real, running server over its real Streamable HTTP transport
|
||||
using the official MCP Java SDK client (`io.modelcontextprotocol.sdk:mcp`, the same library MCP
|
||||
Inspector and Claude Desktop are themselves built on) -- not a mock -- and asserts on the parsed,
|
||||
typed results. `OrderMcpTranscriptTest` separately captures the literal JSON-RPC bytes that cross
|
||||
the wire, with a plain synchronous `java.net.http.HttpClient` driving the protocol by hand
|
||||
(initialize, read the `Mcp-Session-Id` header, `notifications/initialized`, then one request per
|
||||
method): an earlier version tried to capture the SDK client's own traffic with a shared servlet
|
||||
filter and that was intermittently flaky, because the Streamable HTTP transport writes responses
|
||||
during an async servlet dispatch and can multiplex more than one JSON-RPC message onto one
|
||||
long-lived HTTP exchange -- one request per `HttpClient.send()`, read back synchronously,
|
||||
sidesteps that instead of fighting it. Either way, every request and response quoted in the
|
||||
article is real, not reconstructed.
|
||||
|
||||
| Output file | What it captures |
|
||||
|---|---|
|
||||
| `output/01-initialize-and-list-tools.txt` | The MCP handshake, then `tools/list` |
|
||||
| `output/02-call-tool-lookup-order.txt` | `tools/call` for a real order |
|
||||
| `output/03-read-resource-catalog.txt` | `resources/read` for the order catalog |
|
||||
| `output/04-get-prompt-summarize-order.txt` | `prompts/get` for the summarize prompt |
|
||||
| `output/05-call-tool-lookup-order-not-found.txt` | `tools/call` for an order ID that doesn't exist -- a tool error, not a protocol error |
|
||||
| `output/06-protocol-property-unset-404.txt` | Captured manually: the 404 you get without `spring.ai.mcp.server.protocol` set, and the real Boot condition-evaluation log line that explains it |
|
||||
|
||||
Run `mvn -o test` (or `./scripts/run-all.sh`) to regenerate 01 through 05.
|
||||
|
||||
## Regenerating output
|
||||
|
||||
```
|
||||
./scripts/run-all.sh
|
||||
```
|
||||
@@ -0,0 +1,21 @@
|
||||
# POST /mcp -- initialize, then tools/list
|
||||
|
||||
Request (initialize):
|
||||
|
||||
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"transcript-capture","version":"1.0"}}}
|
||||
|
||||
Response (200):
|
||||
|
||||
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"completions":{},"logging":{},"prompts":{"listChanged":true},"resources":{"subscribe":false,"listChanged":true},"tools":{"listChanged":true}},"serverInfo":{"name":"order-lookup-server","version":"1.0.0"}}}
|
||||
|
||||
Request (tools/list):
|
||||
|
||||
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
|
||||
|
||||
Response (200):
|
||||
|
||||
id:59682b84-e49c-42d2-908e-a8105aa31514
|
||||
event:message
|
||||
data:{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"lookup_order","title":"lookup_order","description":"Look up a single order by its ID and return its customer, status, items, and total.","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"orderId":{"type":"string","description":"The order ID, e.g. ORD-1001"}},"required":["orderId"]},"annotations":{"title":"","readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":true}}]}}
|
||||
|
||||
|
||||
@@ -0,0 +1,13 @@
|
||||
# POST /mcp -- tools/call lookup_order, a real order
|
||||
|
||||
Request:
|
||||
|
||||
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"lookup_order","arguments":{"orderId":"ORD-1001"}}}
|
||||
|
||||
Response (200):
|
||||
|
||||
id:59682b84-e49c-42d2-908e-a8105aa31514
|
||||
event:message
|
||||
data:{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"{\"id\":\"ORD-1001\",\"customer\":\"Priya Nair\",\"status\":\"SHIPPED\",\"items\":[\"Mechanical keyboard\",\"USB-C cable\"],\"total\":4899.00}"}],"isError":false}}
|
||||
|
||||
|
||||
@@ -0,0 +1,13 @@
|
||||
# POST /mcp -- resources/read orders://catalog
|
||||
|
||||
Request:
|
||||
|
||||
{"jsonrpc":"2.0","id":4,"method":"resources/read","params":{"uri":"orders://catalog"}}
|
||||
|
||||
Response (200):
|
||||
|
||||
id:59682b84-e49c-42d2-908e-a8105aa31514
|
||||
event:message
|
||||
data:{"jsonrpc":"2.0","id":4,"result":{"contents":[{"uri":"orders://catalog","mimeType":"text/plain","text":"ORD-1001\nORD-1002\nORD-1003\nORD-1004"}]}}
|
||||
|
||||
|
||||
@@ -0,0 +1,13 @@
|
||||
# POST /mcp -- prompts/get summarize_order
|
||||
|
||||
Request:
|
||||
|
||||
{"jsonrpc":"2.0","id":5,"method":"prompts/get","params":{"name":"summarize_order","arguments":{"orderId":"ORD-1002"}}}
|
||||
|
||||
Response (200):
|
||||
|
||||
id:59682b84-e49c-42d2-908e-a8105aa31514
|
||||
event:message
|
||||
data:{"jsonrpc":"2.0","id":5,"result":{"messages":[{"role":"assistant","content":{"type":"text","text":"Call the lookup_order tool for order ORD-1002, then write a single short paragraph a customer support agent could paste into a reply: state the order status in plain language, list the items, and mention the total. Do not invent any detail the tool did not return."}}]}}
|
||||
|
||||
|
||||
@@ -0,0 +1,13 @@
|
||||
# POST /mcp -- tools/call lookup_order, an order ID that does not exist
|
||||
|
||||
Request:
|
||||
|
||||
{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"lookup_order","arguments":{"orderId":"ORD-9999"}}}
|
||||
|
||||
Response (200), note isError:true inside a 200 -- HTTP itself never fails for a tool error:
|
||||
|
||||
id:59682b84-e49c-42d2-908e-a8105aa31514
|
||||
event:message
|
||||
data:{"jsonrpc":"2.0","id":6,"result":{"content":[{"type":"text","text":"No order with ID ORD-9999\nNo order with ID ORD-9999"}],"isError":true}}
|
||||
|
||||
|
||||
@@ -0,0 +1,35 @@
|
||||
# The 404 that shows up with no spring.ai.mcp.server.protocol set, and why
|
||||
|
||||
Captured manually against a standalone run of this module with application.yml's
|
||||
`spring.ai.mcp.server.protocol: streamable` line removed -- everything else identical.
|
||||
Reproduced with: `mvn -o spring-boot:run --server.port=18099 --debug`, then:
|
||||
|
||||
$ curl -X POST http://localhost:18099/mcp -H "Content-Type: application/json" \
|
||||
-H "Accept: application/json, text/event-stream" \
|
||||
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
|
||||
|
||||
{"timestamp":"2026-09-23T11:44:01.196Z","status":404,"error":"Not Found","path":"/mcp"}
|
||||
|
||||
The real reason, from Boot's own --debug condition-evaluation report (trimmed to the one line
|
||||
that matters):
|
||||
|
||||
McpServerStreamableHttpWebMvcAutoConfiguration:
|
||||
Did not match:
|
||||
- AllNestedConditions 1 matched 1 did not; NestedCondition on
|
||||
McpServerAutoConfiguration.EnabledStreamableServerCondition.StreamableEnabledCondition
|
||||
@ConditionalOnProperty (spring.ai.mcp.server.protocol=STREAMABLE) did not find
|
||||
property 'protocol'; NestedCondition on
|
||||
McpServerAutoConfiguration.EnabledStreamableServerCondition.McpServerEnabledCondition
|
||||
@ConditionalOnProperty (spring.ai.mcp.server.enabled=true) matched
|
||||
|
||||
The jar's spring-configuration-metadata.json lists "streamable" as spring.ai.mcp.server.protocol's
|
||||
default value -- but that default is only ever applied when something actually binds the
|
||||
@ConfigurationProperties object (McpServerProperties). The @ConditionalOnProperty guarding
|
||||
McpServerStreamableHttpWebMvcAutoConfiguration runs before any binding happens, checking the
|
||||
Spring Environment directly for a literal "spring.ai.mcp.server.protocol" entry. No entry, no
|
||||
match, no RouterFunction registered for /mcp -- the endpoint simply does not exist, and every
|
||||
request to it 404s exactly like a request to a path nobody ever mapped, which is exactly what it
|
||||
is. Setting spring.ai.mcp.server.protocol: streamable explicitly in application.yml fixes it, and
|
||||
that same run then returns a normal 200 with a real MCP initialize response, e.g.:
|
||||
|
||||
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"completions":{},"logging":{},"prompts":{"listChanged":true},"resources":{"subscribe":false,"listChanged":true},"tools":{"listChanged":true}},"serverInfo":{"name":"order-lookup-server","version":"1.0.0"}}}
|
||||
@@ -0,0 +1,70 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<project xmlns="http://maven.apache.org/POM/4.0.0"
|
||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
|
||||
<parent>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-parent</artifactId>
|
||||
<version>4.1.1</version>
|
||||
<relativePath/>
|
||||
</parent>
|
||||
|
||||
<groupId>com.ankurm</groupId>
|
||||
<artifactId>mcp-server</artifactId>
|
||||
<version>1.0.0</version>
|
||||
<name>mcp-server</name>
|
||||
<description>An existing Spring Boot service exposed as MCP tools with @McpTool/@McpResource, over Streamable HTTP -- Spring AI 2.0's default MCP server transport</description>
|
||||
|
||||
<properties>
|
||||
<java.version>25</java.version>
|
||||
<!-- Spring AI is not managed by the Spring Boot BOM: this pair is yours to keep compatible. -->
|
||||
<spring-ai.version>2.0.1</spring-ai.version>
|
||||
</properties>
|
||||
|
||||
<dependencyManagement>
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>org.springframework.ai</groupId>
|
||||
<artifactId>spring-ai-bom</artifactId>
|
||||
<version>${spring-ai.version}</version>
|
||||
<type>pom</type>
|
||||
<scope>import</scope>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
</dependencyManagement>
|
||||
|
||||
<dependencies>
|
||||
<!-- spring-ai-starter-mcp-server-webmvc's own POM still declares spring-boot-starter-web,
|
||||
not the newer spring-boot-starter-webmvc split; see the "going deeper" note in the
|
||||
article. Both resolve to the same servlet-stack Spring MVC, so this compiles and runs
|
||||
either way; it is simply not yet updated for Boot 4's naming. -->
|
||||
<dependency>
|
||||
<groupId>org.springframework.ai</groupId>
|
||||
<artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
|
||||
</dependency>
|
||||
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-test</artifactId>
|
||||
<scope>test</scope>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
|
||||
<build>
|
||||
<plugins>
|
||||
<plugin>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-maven-plugin</artifactId>
|
||||
</plugin>
|
||||
<plugin>
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
<artifactId>maven-surefire-plugin</artifactId>
|
||||
<configuration>
|
||||
<argLine>-Duser.timezone=UTC -Dstdout.encoding=UTF-8 -Dfile.encoding=UTF-8</argLine>
|
||||
</configuration>
|
||||
</plugin>
|
||||
</plugins>
|
||||
</build>
|
||||
</project>
|
||||
@@ -0,0 +1,14 @@
|
||||
#!/usr/bin/env bash
|
||||
# Regenerates every reproducible file under output/. Run from the module root
|
||||
# (spring-ai/mcp-server). Needs Maven with the dependencies already resolved once online.
|
||||
#
|
||||
# output/06-*.txt is NOT regenerated here -- it was captured manually against a standalone run
|
||||
# with spring.ai.mcp.server.protocol commented out in application.yml. See its own header.
|
||||
set -eu
|
||||
cd "$(dirname "$0")/.."
|
||||
|
||||
mvn -q -o test
|
||||
echo
|
||||
echo "Regenerated output/01 through 05 -- real JSON-RPC exchanges captured by"
|
||||
echo "OrderMcpTranscriptTest against the real running Streamable HTTP endpoint."
|
||||
echo "output/06-protocol-property-unset-404.txt was captured manually -- see its header."
|
||||
@@ -0,0 +1,18 @@
|
||||
#!/usr/bin/env bash
|
||||
# Starts the application, killing any previous instance first.
|
||||
#
|
||||
# Usage:
|
||||
# ./scripts/run.sh
|
||||
#
|
||||
# Then, in another shell (or point MCP Inspector / Claude Desktop at the same URL):
|
||||
# curl -X POST http://localhost:8080/mcp \
|
||||
# -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
|
||||
# -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'
|
||||
set -eu
|
||||
cd "$(dirname "$0")/.."
|
||||
|
||||
for p in $(ps -eo pid,cmd | grep '[M]cpServerApplication' | awk '{print $1}'); do
|
||||
kill -9 "$p"
|
||||
done
|
||||
|
||||
mvn -q -o org.springframework.boot:spring-boot-maven-plugin:run
|
||||
@@ -0,0 +1,13 @@
|
||||
package com.ankurm.mcpserver;
|
||||
|
||||
import org.springframework.boot.SpringApplication;
|
||||
import org.springframework.boot.autoconfigure.SpringBootApplication;
|
||||
|
||||
@SpringBootApplication
|
||||
public class McpServerApplication {
|
||||
|
||||
public static void main(String[] args) {
|
||||
SpringApplication.run(McpServerApplication.class, args);
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,11 @@
|
||||
package com.ankurm.mcpserver.domain;
|
||||
|
||||
import java.math.BigDecimal;
|
||||
import java.util.List;
|
||||
|
||||
/**
|
||||
* The existing domain type this module pretends predates MCP entirely -- the point of this
|
||||
* article is exposing a service that already looks like this, not designing one around MCP.
|
||||
*/
|
||||
public record Order(String id, String customer, OrderStatus status, List<String> items, BigDecimal total) {
|
||||
}
|
||||
@@ -0,0 +1,41 @@
|
||||
package com.ankurm.mcpserver.domain;
|
||||
|
||||
import java.math.BigDecimal;
|
||||
import java.util.LinkedHashMap;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import java.util.Optional;
|
||||
|
||||
import org.springframework.stereotype.Repository;
|
||||
|
||||
/**
|
||||
* Stand-in for a real order-lookup service (a JPA repository, a call to another microservice,
|
||||
* whatever it actually is at your shop). The MCP-facing code in {@code tools} never needs to
|
||||
* change if this gets replaced with the real thing -- it depends on this interface's shape, not
|
||||
* its storage.
|
||||
*/
|
||||
@Repository
|
||||
public class OrderRepository {
|
||||
|
||||
private final Map<String, Order> orders = new LinkedHashMap<>();
|
||||
|
||||
public OrderRepository() {
|
||||
orders.put("ORD-1001", new Order("ORD-1001", "Priya Nair", OrderStatus.SHIPPED,
|
||||
List.of("Mechanical keyboard", "USB-C cable"), new BigDecimal("4899.00")));
|
||||
orders.put("ORD-1002", new Order("ORD-1002", "Rohan Mehta", OrderStatus.PENDING,
|
||||
List.of("27\" monitor"), new BigDecimal("18999.00")));
|
||||
orders.put("ORD-1003", new Order("ORD-1003", "Ankita Rao", OrderStatus.DELIVERED,
|
||||
List.of("Laptop stand", "Wireless mouse", "USB hub"), new BigDecimal("3450.00")));
|
||||
orders.put("ORD-1004", new Order("ORD-1004", "Vikram Shah", OrderStatus.CANCELLED,
|
||||
List.of("Graphics card"), new BigDecimal("42999.00")));
|
||||
}
|
||||
|
||||
public Optional<Order> findById(String id) {
|
||||
return Optional.ofNullable(orders.get(id));
|
||||
}
|
||||
|
||||
public List<Order> findAll() {
|
||||
return List.copyOf(orders.values());
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,5 @@
|
||||
package com.ankurm.mcpserver.domain;
|
||||
|
||||
public enum OrderStatus {
|
||||
PENDING, SHIPPED, DELIVERED, CANCELLED
|
||||
}
|
||||
@@ -0,0 +1,53 @@
|
||||
package com.ankurm.mcpserver.tools;
|
||||
|
||||
import java.util.List;
|
||||
import java.util.stream.Collectors;
|
||||
|
||||
import org.springframework.ai.mcp.annotation.McpArg;
|
||||
import org.springframework.ai.mcp.annotation.McpPrompt;
|
||||
import org.springframework.ai.mcp.annotation.McpResource;
|
||||
import org.springframework.ai.mcp.annotation.McpTool;
|
||||
import org.springframework.ai.mcp.annotation.McpToolParam;
|
||||
import org.springframework.stereotype.Service;
|
||||
|
||||
import com.ankurm.mcpserver.domain.Order;
|
||||
import com.ankurm.mcpserver.domain.OrderRepository;
|
||||
|
||||
/**
|
||||
* The existing service this article exposes over MCP. Nothing here imports an MCP class except
|
||||
* the three annotations -- {@link OrderRepository} and {@link Order} are ordinary Spring beans
|
||||
* and domain types that would exist whether or not an AI agent ever called them.
|
||||
*/
|
||||
@Service
|
||||
public class OrderTools {
|
||||
|
||||
private final OrderRepository repository;
|
||||
|
||||
public OrderTools(OrderRepository repository) {
|
||||
this.repository = repository;
|
||||
}
|
||||
|
||||
@McpTool(name = "lookup_order", description = "Look up a single order by its ID and return its customer, status, items, and total.")
|
||||
public Order lookupOrder(
|
||||
@McpToolParam(description = "The order ID, e.g. ORD-1001", required = true) String orderId) {
|
||||
return repository.findById(orderId)
|
||||
.orElseThrow(() -> new IllegalArgumentException("No order with ID " + orderId));
|
||||
}
|
||||
|
||||
@McpResource(uri = "orders://catalog", name = "order-catalog",
|
||||
description = "Every order ID currently in the system, one per line -- read this first if you don't already have an order ID to look up.",
|
||||
mimeType = "text/plain")
|
||||
public String orderCatalog() {
|
||||
return repository.findAll().stream().map(Order::id).collect(Collectors.joining("\n"));
|
||||
}
|
||||
|
||||
@McpPrompt(name = "summarize_order", description = "A ready-made prompt asking a model to write a one-paragraph customer-support summary of one order.")
|
||||
public String summarizeOrderPrompt(
|
||||
@McpArg(name = "orderId", description = "The order ID to summarize, e.g. ORD-1001", required = true) String orderId) {
|
||||
return "Call the lookup_order tool for order " + orderId
|
||||
+ ", then write a single short paragraph a customer support agent could paste into a reply: "
|
||||
+ "state the order status in plain language, list the items, and mention the total. "
|
||||
+ "Do not invent any detail the tool did not return.";
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,15 @@
|
||||
spring:
|
||||
application:
|
||||
name: mcp-server
|
||||
ai:
|
||||
mcp:
|
||||
server:
|
||||
name: order-lookup-server
|
||||
version: 1.0.0
|
||||
# The jar's own spring-configuration-metadata.json lists "streamable" as this
|
||||
# property's default -- but that is only the @ConfigurationProperties field default,
|
||||
# and the autoconfiguration class that actually wires the /mcp endpoint is gated by
|
||||
# @ConditionalOnProperty, which only ever looks at the Environment, never at a field
|
||||
# default. Leave this property unset and McpServerStreamableHttpWebMvcAutoConfiguration
|
||||
# never matches, full stop -- see the article for the real condition-evaluation log line.
|
||||
protocol: streamable
|
||||
@@ -0,0 +1,93 @@
|
||||
package com.ankurm.mcpserver;
|
||||
|
||||
import java.util.Map;
|
||||
|
||||
import io.modelcontextprotocol.client.McpClient;
|
||||
import io.modelcontextprotocol.client.McpSyncClient;
|
||||
import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
|
||||
import io.modelcontextprotocol.spec.McpSchema;
|
||||
import org.junit.jupiter.api.AfterEach;
|
||||
import org.junit.jupiter.api.BeforeEach;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
import org.springframework.boot.test.context.SpringBootTest;
|
||||
import org.springframework.boot.test.web.server.LocalServerPort;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
|
||||
/**
|
||||
* Drives the real, running MCP server over its real Streamable HTTP transport, using the
|
||||
* official MCP Java SDK client (the same client library MCP Inspector and Claude Desktop are
|
||||
* themselves built on) -- not a mock, not an in-process shortcut. This class asserts on the
|
||||
* parsed, typed results; {@link OrderMcpTranscriptTest} separately captures the literal wire
|
||||
* bytes for the article, over a deliberately simpler raw HTTP path (see its class comment for
|
||||
* why the two are kept apart).
|
||||
*/
|
||||
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
|
||||
class OrderMcpServerTest {
|
||||
|
||||
@LocalServerPort
|
||||
private int port;
|
||||
|
||||
private McpSyncClient client;
|
||||
|
||||
@BeforeEach
|
||||
void connect() {
|
||||
HttpClientStreamableHttpTransport transport = HttpClientStreamableHttpTransport
|
||||
.builder("http://localhost:" + port)
|
||||
.endpoint("/mcp")
|
||||
.build();
|
||||
this.client = McpClient.sync(transport).build();
|
||||
this.client.initialize();
|
||||
}
|
||||
|
||||
@AfterEach
|
||||
void disconnect() {
|
||||
this.client.closeGracefully();
|
||||
}
|
||||
|
||||
@Test
|
||||
void listsTheRegisteredTool() {
|
||||
McpSchema.ListToolsResult tools = this.client.listTools();
|
||||
assertThat(tools.tools()).extracting(McpSchema.Tool::name).containsExactly("lookup_order");
|
||||
}
|
||||
|
||||
@Test
|
||||
void callsLookupOrderTool() {
|
||||
McpSchema.CallToolResult result = this.client
|
||||
.callTool(new McpSchema.CallToolRequest("lookup_order", Map.of("orderId", "ORD-1001")));
|
||||
|
||||
assertThat(result.isError()).isNotEqualTo(Boolean.TRUE);
|
||||
String text = ((McpSchema.TextContent) result.content().get(0)).text();
|
||||
assertThat(text).contains("Priya Nair").contains("SHIPPED").contains("4899.00");
|
||||
}
|
||||
|
||||
@Test
|
||||
void callingLookupOrderWithAnUnknownIdReturnsAToolErrorNotAProtocolError() {
|
||||
McpSchema.CallToolResult result = this.client
|
||||
.callTool(new McpSchema.CallToolRequest("lookup_order", Map.of("orderId", "ORD-9999")));
|
||||
|
||||
assertThat(result.isError()).isEqualTo(Boolean.TRUE);
|
||||
String text = ((McpSchema.TextContent) result.content().get(0)).text();
|
||||
assertThat(text).contains("No order with ID ORD-9999");
|
||||
}
|
||||
|
||||
@Test
|
||||
void readsTheOrderCatalogResource() {
|
||||
McpSchema.ReadResourceResult result = this.client
|
||||
.readResource(new McpSchema.ReadResourceRequest("orders://catalog"));
|
||||
|
||||
String text = ((McpSchema.TextResourceContents) result.contents().get(0)).text();
|
||||
assertThat(text).contains("ORD-1001").contains("ORD-1002").contains("ORD-1003").contains("ORD-1004");
|
||||
}
|
||||
|
||||
@Test
|
||||
void getsTheSummarizeOrderPrompt() {
|
||||
McpSchema.GetPromptResult result = this.client
|
||||
.getPrompt(new McpSchema.GetPromptRequest("summarize_order", Map.of("orderId", "ORD-1002")));
|
||||
|
||||
String text = ((McpSchema.TextContent) result.messages().get(0).content()).text();
|
||||
assertThat(text).contains("ORD-1002").contains("lookup_order");
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,123 @@
|
||||
package com.ankurm.mcpserver;
|
||||
|
||||
import java.net.URI;
|
||||
import java.net.http.HttpClient;
|
||||
import java.net.http.HttpRequest;
|
||||
import java.net.http.HttpResponse;
|
||||
import java.time.Duration;
|
||||
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
import org.springframework.boot.test.context.SpringBootTest;
|
||||
import org.springframework.boot.test.web.server.LocalServerPort;
|
||||
|
||||
import com.ankurm.mcpserver.support.Transcript;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
|
||||
/**
|
||||
* Captures the literal JSON-RPC bytes for the article by talking to the real, running server
|
||||
* with a plain {@code java.net.http.HttpClient} -- deliberately not the MCP SDK client that
|
||||
* {@link OrderMcpServerTest} uses for assertions. An earlier version of this test tried to
|
||||
* capture the SDK client's traffic with a servlet filter and failed intermittently: the
|
||||
* Streamable HTTP transport writes each response during an async servlet dispatch, and can
|
||||
* multiplex more than one JSON-RPC message onto the same long-lived HTTP exchange, so a filter
|
||||
* keyed by "one request equals one response equals one method" is fighting the protocol rather
|
||||
* than observing it. One request per {@code HttpClient.send()} call, read synchronously, sidesteps
|
||||
* that entirely -- what is captured here is exactly, deterministically, what the socket carried.
|
||||
*/
|
||||
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
|
||||
class OrderMcpTranscriptTest {
|
||||
|
||||
@LocalServerPort
|
||||
private int port;
|
||||
|
||||
private final HttpClient httpClient = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(5)).build();
|
||||
|
||||
@Test
|
||||
void capturesRealJsonRpcTranscripts() throws Exception {
|
||||
String base = "http://localhost:" + this.port + "/mcp";
|
||||
|
||||
String initRequest = """
|
||||
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"transcript-capture","version":"1.0"}}}""";
|
||||
HttpResponse<String> initResponse = post(base, initRequest, null);
|
||||
assertThat(initResponse.statusCode()).isEqualTo(200);
|
||||
String sessionId = initResponse.headers().firstValue("Mcp-Session-Id").orElseThrow();
|
||||
|
||||
try (Transcript out = new Transcript("01-initialize-and-list-tools.txt",
|
||||
"POST /mcp -- initialize, then tools/list")) {
|
||||
out.line("Request (initialize):").blank().line(initRequest).blank();
|
||||
out.line("Response (%s):", initResponse.statusCode()).blank().line(initResponse.body()).blank();
|
||||
|
||||
String initializedNotification = """
|
||||
{"jsonrpc":"2.0","method":"notifications/initialized"}""";
|
||||
post(base, initializedNotification, sessionId);
|
||||
|
||||
String listRequest = """
|
||||
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}""";
|
||||
HttpResponse<String> listResponse = post(base, listRequest, sessionId);
|
||||
assertThat(listResponse.body()).contains("lookup_order");
|
||||
|
||||
out.line("Request (tools/list):").blank().line(listRequest).blank();
|
||||
out.line("Response (%s):", listResponse.statusCode()).blank().line(listResponse.body());
|
||||
}
|
||||
|
||||
String callRequest = """
|
||||
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"lookup_order","arguments":{"orderId":"ORD-1001"}}}""";
|
||||
HttpResponse<String> callResponse = post(base, callRequest, sessionId);
|
||||
assertThat(callResponse.body()).contains("Priya Nair").contains("SHIPPED");
|
||||
|
||||
try (Transcript out = new Transcript("02-call-tool-lookup-order.txt",
|
||||
"POST /mcp -- tools/call lookup_order, a real order")) {
|
||||
out.line("Request:").blank().line(callRequest).blank();
|
||||
out.line("Response (%s):", callResponse.statusCode()).blank().line(callResponse.body());
|
||||
}
|
||||
|
||||
String readRequest = """
|
||||
{"jsonrpc":"2.0","id":4,"method":"resources/read","params":{"uri":"orders://catalog"}}""";
|
||||
HttpResponse<String> readResponse = post(base, readRequest, sessionId);
|
||||
assertThat(readResponse.body()).contains("ORD-1001").contains("ORD-1004");
|
||||
|
||||
try (Transcript out = new Transcript("03-read-resource-catalog.txt",
|
||||
"POST /mcp -- resources/read orders://catalog")) {
|
||||
out.line("Request:").blank().line(readRequest).blank();
|
||||
out.line("Response (%s):", readResponse.statusCode()).blank().line(readResponse.body());
|
||||
}
|
||||
|
||||
String promptRequest = """
|
||||
{"jsonrpc":"2.0","id":5,"method":"prompts/get","params":{"name":"summarize_order","arguments":{"orderId":"ORD-1002"}}}""";
|
||||
HttpResponse<String> promptResponse = post(base, promptRequest, sessionId);
|
||||
assertThat(promptResponse.body()).contains("ORD-1002").contains("lookup_order");
|
||||
|
||||
try (Transcript out = new Transcript("04-get-prompt-summarize-order.txt",
|
||||
"POST /mcp -- prompts/get summarize_order")) {
|
||||
out.line("Request:").blank().line(promptRequest).blank();
|
||||
out.line("Response (%s):", promptResponse.statusCode()).blank().line(promptResponse.body());
|
||||
}
|
||||
|
||||
String notFoundRequest = """
|
||||
{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"lookup_order","arguments":{"orderId":"ORD-9999"}}}""";
|
||||
HttpResponse<String> notFoundResponse = post(base, notFoundRequest, sessionId);
|
||||
assertThat(notFoundResponse.statusCode()).isEqualTo(200);
|
||||
assertThat(notFoundResponse.body()).contains("\"isError\":true").contains("No order with ID ORD-9999");
|
||||
|
||||
try (Transcript out = new Transcript("05-call-tool-lookup-order-not-found.txt",
|
||||
"POST /mcp -- tools/call lookup_order, an order ID that does not exist")) {
|
||||
out.line("Request:").blank().line(notFoundRequest).blank();
|
||||
out.line("Response (%s), note isError:true inside a 200 -- HTTP itself never fails for a tool error:",
|
||||
notFoundResponse.statusCode()).blank().line(notFoundResponse.body());
|
||||
}
|
||||
}
|
||||
|
||||
private HttpResponse<String> post(String url, String jsonBody, String sessionId) throws Exception {
|
||||
HttpRequest.Builder builder = HttpRequest.newBuilder(URI.create(url))
|
||||
.header("Content-Type", "application/json")
|
||||
.header("Accept", "application/json, text/event-stream")
|
||||
.POST(HttpRequest.BodyPublishers.ofString(jsonBody));
|
||||
if (sessionId != null) {
|
||||
builder.header("Mcp-Session-Id", sessionId);
|
||||
}
|
||||
return this.httpClient.send(builder.build(), HttpResponse.BodyHandlers.ofString());
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,47 @@
|
||||
package com.ankurm.mcpserver.support;
|
||||
|
||||
import java.io.IOException;
|
||||
import java.io.PrintWriter;
|
||||
import java.io.StringWriter;
|
||||
import java.nio.file.Files;
|
||||
import java.nio.file.Path;
|
||||
|
||||
/**
|
||||
* Writes a numbered transcript under {@code output/} (repository root, not {@code docs/}) and
|
||||
* echoes it to the console. Every console block quoted in the article comes out of one of these
|
||||
* files verbatim.
|
||||
*/
|
||||
public final class Transcript implements AutoCloseable {
|
||||
|
||||
private final Path path;
|
||||
private final StringWriter buffer = new StringWriter();
|
||||
private final PrintWriter out = new PrintWriter(buffer);
|
||||
|
||||
public Transcript(String fileName, String title) {
|
||||
this.path = Path.of("output", fileName);
|
||||
out.println("# " + title);
|
||||
out.println();
|
||||
}
|
||||
|
||||
public Transcript line(String format, Object... args) {
|
||||
out.println(args.length == 0 ? format : String.format(format, args));
|
||||
return this;
|
||||
}
|
||||
|
||||
public Transcript blank() {
|
||||
out.println();
|
||||
return this;
|
||||
}
|
||||
|
||||
@Override
|
||||
public void close() {
|
||||
out.flush();
|
||||
try {
|
||||
Files.createDirectories(path.getParent());
|
||||
Files.writeString(path, buffer.toString());
|
||||
} catch (IOException e) {
|
||||
throw new IllegalStateException("could not write " + path, e);
|
||||
}
|
||||
System.out.print(buffer);
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user