modelcontextprotocol/java-sdk
Watch
1
0
Fork
You've already forked java-sdk
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

refactor: Improve MCP documentation and transport interfaces

Browse source 
- Add ClientMcpTransport and ServerMcpTransport marker interfaces
- Update client/server implementations to use appropriate transport interfaces
- Reorganize documentation structure and improve content clarity
- Move documentation images to mcp-docs/antora directory
- Update README files with links to online documentation

Resolves #44
This commit is contained in:
Christian Tzolov 2025-01-03 15:48:30 +01:00
commit c469f790b3
23 changed files with 407 additions and 750 deletions
Download patch file Download diff file Expand all files Collapse all files

3
mcp/src/main/java/org/springframework/ai/mcp/client/McpAsyncClient.java
View file

@ -30,6 +30,7 @@ import org.slf4j.LoggerFactory;
import reactor.core.publisher.Mono;
import reactor.core.scheduler.Schedulers;
import org.springframework.ai.mcp.spec.ClientMcpTransport;
import org.springframework.ai.mcp.spec.DefaultMcpSession;
import org.springframework.ai.mcp.spec.DefaultMcpSession.NotificationHandler;
import org.springframework.ai.mcp.spec.DefaultMcpSession.RequestHandler;
@ -129,7 +130,7 @@ public class McpAsyncClient {
* @param loggingConsumers the logging consumers.
* @param samplingHandler the sampling handler.
*/
public McpAsyncClient(McpTransport transport, Duration requestTimeout, Implementation clientInfo,
public McpAsyncClient(ClientMcpTransport transport, Duration requestTimeout, Implementation clientInfo,
ClientCapabilities clientCapabilities, Map<String, Root> roots,
List<Consumer<List<McpSchema.Tool>>> toolsChangeConsumers,
List<Consumer<List<McpSchema.Resource>>> resourcesChangeConsumers,

7
mcp/src/main/java/org/springframework/ai/mcp/client/McpClient.java
View file

@ -24,6 +24,7 @@ import java.util.Map;
import java.util.function.Consumer;
import java.util.function.Function;
import org.springframework.ai.mcp.spec.ClientMcpTransport;
import org.springframework.ai.mcp.spec.McpSchema;
import org.springframework.ai.mcp.spec.McpSchema.ClientCapabilities;
import org.springframework.ai.mcp.spec.McpSchema.CreateMessageRequest;
@ -115,7 +116,7 @@ public interface McpClient {
* @return A new builder instance for configuring the client
* @throws IllegalArgumentException if transport is null
*/
public static Builder using(McpTransport transport) {
public static Builder using(ClientMcpTransport transport) {
return new Builder(transport);
}
@ -138,7 +139,7 @@ public interface McpClient {
*/
public static class Builder {
private final McpTransport transport;
private final ClientMcpTransport transport;
private Duration requestTimeout = Duration.ofSeconds(20); // Default timeout
@ -158,7 +159,7 @@ public interface McpClient {
private Function<CreateMessageRequest, CreateMessageResult> samplingHandler;
private Builder(McpTransport transport) {
private Builder(ClientMcpTransport transport) {
Assert.notNull(transport, "Transport must not be null");
this.transport = transport;
}

4
mcp/src/main/java/org/springframework/ai/mcp/client/transport/SseClientTransport.java
View file

@ -32,10 +32,10 @@ import reactor.core.scheduler.Schedulers;
import reactor.util.retry.Retry;
import reactor.util.retry.Retry.RetrySignal;
import org.springframework.ai.mcp.spec.ClientMcpTransport;
import org.springframework.ai.mcp.spec.McpError;
import org.springframework.ai.mcp.spec.McpSchema;
import org.springframework.ai.mcp.spec.McpSchema.JSONRPCMessage;
import org.springframework.ai.mcp.spec.McpTransport;
import org.springframework.ai.mcp.util.Assert;
import org.springframework.core.ParameterizedTypeReference;
import org.springframework.http.MediaType;
@ -71,7 +71,7 @@ import org.springframework.web.reactive.function.client.WebClient;
* "https://spec.modelcontextprotocol.io/specification/basic/transports/#http-with-sse">MCP
* HTTP with SSE Transport Specification</a>
*/
public class SseClientTransport implements McpTransport {
public class SseClientTransport implements ClientMcpTransport {
private final static Logger logger = LoggerFactory.getLogger(SseClientTransport.class);

4
mcp/src/main/java/org/springframework/ai/mcp/client/transport/StdioClientTransport.java
View file

@ -38,10 +38,10 @@ import reactor.core.publisher.Sinks;
import reactor.core.scheduler.Scheduler;
import reactor.core.scheduler.Schedulers;
import org.springframework.ai.mcp.spec.ClientMcpTransport;
import org.springframework.ai.mcp.spec.McpSchema;
import org.springframework.ai.mcp.spec.McpSchema.JSONRPCMessage;
import org.springframework.ai.mcp.util.Assert;
import org.springframework.ai.mcp.spec.McpTransport;
/**
* Implementation of the MCP Stdio transport that communicates with a server process using
@ -51,7 +51,7 @@ import org.springframework.ai.mcp.spec.McpTransport;
* @author Christian Tzolov
* @author Dariusz Jędrzejczyk
*/
public class StdioClientTransport implements McpTransport {
public class StdioClientTransport implements ClientMcpTransport {
private static final Logger logger = LoggerFactory.getLogger(StdioClientTransport.class);

6
mcp/src/main/java/org/springframework/ai/mcp/server/McpAsyncServer.java
View file

@ -44,7 +44,7 @@ import org.springframework.ai.mcp.spec.McpSchema.ListRootsResult;
import org.springframework.ai.mcp.spec.McpSchema.LoggingLevel;
import org.springframework.ai.mcp.spec.McpSchema.LoggingMessageNotification;
import org.springframework.ai.mcp.spec.McpSchema.Tool;
import org.springframework.ai.mcp.spec.McpTransport;
import org.springframework.ai.mcp.spec.ServerMcpTransport;
import org.springframework.ai.mcp.util.Utils;
/**
@ -63,7 +63,7 @@ public class McpAsyncServer {
*/
private final DefaultMcpSession mcpSession;
private final McpTransport transport;
private final ServerMcpTransport transport;
private final McpSchema.ServerCapabilities serverCapabilities;
@ -98,7 +98,7 @@ public class McpAsyncServer {
* @param rootsChangeConsumers The list of consumers that will be notified when the
* roots list changes
*/
public McpAsyncServer(McpTransport mcpTransport, McpSchema.Implementation serverInfo,
public McpAsyncServer(ServerMcpTransport mcpTransport, McpSchema.Implementation serverInfo,
McpSchema.ServerCapabilities serverCapabilities, List<ToolRegistration> tools,
Map<String, ResourceRegistration> resources, List<McpSchema.ResourceTemplate> resourceTemplates,
Map<String, PromptRegistration> prompts, List<Consumer<List<McpSchema.Root>>> rootsChangeConsumers) {

7
mcp/src/main/java/org/springframework/ai/mcp/server/McpServer.java
View file

@ -28,6 +28,7 @@ import org.springframework.ai.mcp.spec.McpSchema.CallToolResult;
import org.springframework.ai.mcp.spec.McpSchema.ResourceTemplate;
import org.springframework.ai.mcp.spec.McpSchema.Tool;
import org.springframework.ai.mcp.spec.McpTransport;
import org.springframework.ai.mcp.spec.ServerMcpTransport;
import org.springframework.ai.mcp.util.Assert;
/**
@ -198,7 +199,7 @@ public interface McpServer {
* @param transport The transport layer implementation for MCP communication
* @return A new builder instance
*/
public static Builder using(McpTransport transport) {
public static Builder using(ServerMcpTransport transport) {
return new Builder(transport);
}
@ -210,7 +211,7 @@ public interface McpServer {
private final static McpSchema.Implementation DEFAULT_SERVER_INFO = new McpSchema.Implementation("mcp-server",
"1.0.0");
private final McpTransport transport;
private final ServerMcpTransport transport;
private McpSchema.Implementation serverInfo = DEFAULT_SERVER_INFO;
@ -247,7 +248,7 @@ public interface McpServer {
private List<Consumer<List<McpSchema.Root>>> rootsChangeConsumers = new ArrayList<>();
private Builder(McpTransport transport) {
private Builder(ServerMcpTransport transport) {
Assert.notNull(transport, "Transport must not be null");
this.transport = transport;
}

4
mcp/src/main/java/org/springframework/ai/mcp/server/transport/SseServerTransport.java
View file

@ -17,7 +17,7 @@ import reactor.core.publisher.Sinks;
import org.springframework.ai.mcp.spec.McpError;
import org.springframework.ai.mcp.spec.McpSchema;
import org.springframework.ai.mcp.spec.McpTransport;
import org.springframework.ai.mcp.spec.ServerMcpTransport;
import org.springframework.ai.mcp.util.Assert;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
@ -33,7 +33,7 @@ import org.springframework.web.reactive.function.server.ServerResponse;
*
* @author Christian Tzolov
*/
public class SseServerTransport implements McpTransport {
public class SseServerTransport implements ServerMcpTransport {
private final static Logger logger = LoggerFactory.getLogger(SseServerTransport.class);

4
mcp/src/main/java/org/springframework/ai/mcp/server/transport/StdioServerTransport.java
View file

@ -38,7 +38,7 @@ import reactor.core.scheduler.Schedulers;
import org.springframework.ai.mcp.spec.McpSchema;
import org.springframework.ai.mcp.spec.McpSchema.JSONRPCMessage;
import org.springframework.ai.mcp.spec.McpTransport;
import org.springframework.ai.mcp.spec.ServerMcpTransport;
import org.springframework.ai.mcp.util.Assert;
/**
@ -48,7 +48,7 @@ import org.springframework.ai.mcp.util.Assert;
*
* @author Christian Tzolov
*/
public class StdioServerTransport implements McpTransport {
public class StdioServerTransport implements ServerMcpTransport {
private static final Logger logger = LoggerFactory.getLogger(StdioServerTransport.class);

25
mcp/src/main/java/org/springframework/ai/mcp/spec/ClientMcpTransport.java Normal file
View file

@ -0,0 +1,25 @@
/*
* Copyright 2024 - 2024 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.ai.mcp.spec;
/**
* Marker interface for the client-side MCP transport.
*
* @author Christian Tzolov
*/
public interface ClientMcpTransport extends McpTransport {
}

25
mcp/src/main/java/org/springframework/ai/mcp/spec/ServerMcpTransport.java Normal file
View file

@ -0,0 +1,25 @@
/*
* Copyright 2024 - 2024 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.ai.mcp.spec;
/**
* Marker interface for the server-side MCP transport.
*
* @author Christian Tzolov
*/
public interface ServerMcpTransport extends McpTransport {
}

5
mcp/src/test/java/org/springframework/ai/mcp/MockMcpTransport.java
View file

@ -26,14 +26,13 @@ import reactor.core.publisher.Mono;
import reactor.core.publisher.Sinks;
import reactor.core.scheduler.Schedulers;
import org.springframework.ai.mcp.spec.ClientMcpTransport;
import org.springframework.ai.mcp.spec.McpSchema;
import org.springframework.ai.mcp.spec.McpTransport;
import org.springframework.ai.mcp.spec.McpSchema.JSONRPCMessage;
import org.springframework.ai.mcp.spec.McpSchema.JSONRPCNotification;
import org.springframework.ai.mcp.spec.McpSchema.JSONRPCRequest;
@SuppressWarnings("unused")
public class MockMcpTransport implements McpTransport {
public class MockMcpTransport implements ClientMcpTransport {
private final AtomicInteger inboundMessageCount = new AtomicInteger(0);

5
mcp/src/test/java/org/springframework/ai/mcp/client/AbstractMcpAsyncClientTests.java
View file

@ -27,6 +27,7 @@ import org.junit.jupiter.api.Disabled;
import org.junit.jupiter.api.Test;
import reactor.test.StepVerifier;
import org.springframework.ai.mcp.spec.ClientMcpTransport;
import org.springframework.ai.mcp.spec.McpSchema;
import org.springframework.ai.mcp.spec.McpSchema.CallToolRequest;
import org.springframework.ai.mcp.spec.McpSchema.ClientCapabilities;
@ -56,13 +57,13 @@ public abstract class AbstractMcpAsyncClientTests {
private McpAsyncClient mcpAsyncClient;
protected McpTransport mcpTransport;
protected ClientMcpTransport mcpTransport;
private static final Duration TIMEOUT = Duration.ofSeconds(20);
private static final String ECHO_TEST_MESSAGE = "Hello MCP Spring AI!";
abstract protected McpTransport createMcpTransport();
abstract protected ClientMcpTransport createMcpTransport();
protected void onStart() {
}

6
mcp/src/test/java/org/springframework/ai/mcp/client/AbstractMcpSyncClientTests.java
View file

@ -24,6 +24,7 @@ import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.ai.mcp.spec.ClientMcpTransport;
import org.springframework.ai.mcp.spec.McpSchema;
import org.springframework.ai.mcp.spec.McpSchema.CallToolRequest;
import org.springframework.ai.mcp.spec.McpSchema.CallToolResult;
@ -38,7 +39,6 @@ import org.springframework.ai.mcp.spec.McpSchema.SubscribeRequest;
import org.springframework.ai.mcp.spec.McpSchema.TextContent;
import org.springframework.ai.mcp.spec.McpSchema.Tool;
import org.springframework.ai.mcp.spec.McpSchema.UnsubscribeRequest;
import org.springframework.ai.mcp.spec.McpTransport;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatCode;
@ -58,9 +58,9 @@ public abstract class AbstractMcpSyncClientTests {
private static final String TEST_MESSAGE = "Hello MCP Spring AI!";
protected McpTransport mcpTransport;
protected ClientMcpTransport mcpTransport;
abstract protected McpTransport createMcpTransport();
abstract protected ClientMcpTransport createMcpTransport();
abstract protected void onStart();

4
mcp/src/test/java/org/springframework/ai/mcp/client/McpAsyncClientTests.java
View file

@ -20,7 +20,7 @@ import org.junit.jupiter.api.Timeout;
import org.springframework.ai.mcp.client.transport.ServerParameters;
import org.springframework.ai.mcp.client.transport.StdioClientTransport;
import org.springframework.ai.mcp.spec.McpTransport;
import org.springframework.ai.mcp.spec.ClientMcpTransport;
/**
* Tests for the {@link McpAsyncClient} with {@link StdioClientTransport}.
@ -32,7 +32,7 @@ import org.springframework.ai.mcp.spec.McpTransport;
class McpAsyncClientTests extends AbstractMcpAsyncClientTests {
@Override
protected McpTransport createMcpTransport() {
protected ClientMcpTransport createMcpTransport() {
ServerParameters stdioParams = ServerParameters.builder("npx")
.args("-y", "@modelcontextprotocol/server-everything", "dir")
.build();

4
mcp/src/test/java/org/springframework/ai/mcp/client/McpSyncClientTests.java
View file

@ -23,7 +23,7 @@ import org.junit.jupiter.api.Timeout;
import org.springframework.ai.mcp.client.transport.ServerParameters;
import org.springframework.ai.mcp.client.transport.StdioClientTransport;
import org.springframework.ai.mcp.spec.McpTransport;
import org.springframework.ai.mcp.spec.ClientMcpTransport;
import static org.assertj.core.api.Assertions.assertThat;
@ -37,7 +37,7 @@ import static org.assertj.core.api.Assertions.assertThat;
class McpSyncClientTests extends AbstractMcpSyncClientTests {
@Override
protected McpTransport createMcpTransport() {
protected ClientMcpTransport createMcpTransport() {
ServerParameters stdioParams = ServerParameters.builder("npx")
.args("-y", "@modelcontextprotocol/server-everything", "dir")
.build();

4
mcp/src/test/java/org/springframework/ai/mcp/client/SseMcpAsyncClientTests.java
View file

@ -21,7 +21,7 @@ import org.testcontainers.containers.GenericContainer;
import org.testcontainers.containers.wait.strategy.Wait;
import org.springframework.ai.mcp.client.transport.SseClientTransport;
import org.springframework.ai.mcp.spec.McpTransport;
import org.springframework.ai.mcp.spec.ClientMcpTransport;
import org.springframework.web.reactive.function.client.WebClient;
/**
@ -42,7 +42,7 @@ class SseMcpAsyncClientTests extends AbstractMcpAsyncClientTests {
.waitingFor(Wait.forHttp("/").forStatusCode(404));
@Override
protected McpTransport createMcpTransport() {
protected ClientMcpTransport createMcpTransport() {
return new SseClientTransport(WebClient.builder().baseUrl(host));
}

4
mcp/src/test/java/org/springframework/ai/mcp/client/SseMcpSyncClientTests.java
View file

@ -21,7 +21,7 @@ import org.testcontainers.containers.GenericContainer;
import org.testcontainers.containers.wait.strategy.Wait;
import org.springframework.ai.mcp.client.transport.SseClientTransport;
import org.springframework.ai.mcp.spec.McpTransport;
import org.springframework.ai.mcp.spec.ClientMcpTransport;
import org.springframework.web.reactive.function.client.WebClient;
/**
@ -42,7 +42,7 @@ class SseMcpSyncClientTests extends AbstractMcpSyncClientTests {
.waitingFor(Wait.forHttp("/").forStatusCode(404));
@Override
protected McpTransport createMcpTransport() {
protected ClientMcpTransport createMcpTransport() {
return new SseClientTransport(WebClient.builder().baseUrl(host));
}

3
mcp/src/test/java/org/springframework/ai/mcp/server/AbstractMcpAsyncServerTests.java
View file

@ -39,6 +39,7 @@ import org.springframework.ai.mcp.spec.McpSchema.Resource;
import org.springframework.ai.mcp.spec.McpSchema.ServerCapabilities;
import org.springframework.ai.mcp.spec.McpSchema.Tool;
import org.springframework.ai.mcp.spec.McpTransport;
import org.springframework.ai.mcp.spec.ServerMcpTransport;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatCode;
@ -58,7 +59,7 @@ public abstract class AbstractMcpAsyncServerTests {
private static final String TEST_PROMPT_NAME = "test-prompt";
abstract protected McpTransport createMcpTransport();
abstract protected ServerMcpTransport createMcpTransport();
protected void onStart() {
}

5
mcp/src/test/java/org/springframework/ai/mcp/server/AbstractMcpSyncServerTests.java
View file

@ -23,11 +23,11 @@ import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.ai.mcp.spec.McpSchema;
import org.springframework.ai.mcp.server.McpServer.PromptRegistration;
import org.springframework.ai.mcp.server.McpServer.ResourceRegistration;
import org.springframework.ai.mcp.server.McpServer.ToolRegistration;
import org.springframework.ai.mcp.spec.McpError;
import org.springframework.ai.mcp.spec.McpSchema;
import org.springframework.ai.mcp.spec.McpSchema.CallToolResult;
import org.springframework.ai.mcp.spec.McpSchema.GetPromptResult;
import org.springframework.ai.mcp.spec.McpSchema.Prompt;
@ -37,6 +37,7 @@ import org.springframework.ai.mcp.spec.McpSchema.Resource;
import org.springframework.ai.mcp.spec.McpSchema.ServerCapabilities;
import org.springframework.ai.mcp.spec.McpSchema.Tool;
import org.springframework.ai.mcp.spec.McpTransport;
import org.springframework.ai.mcp.spec.ServerMcpTransport;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatCode;
@ -56,7 +57,7 @@ public abstract class AbstractMcpSyncServerTests {
private static final String TEST_PROMPT_NAME = "test-prompt";
abstract protected McpTransport createMcpTransport();
abstract protected ServerMcpTransport createMcpTransport();
protected void onStart() {
}

4
mcp/src/test/java/org/springframework/ai/mcp/server/SseMcpAsyncServerTests.java
View file

@ -22,7 +22,7 @@ import reactor.netty.DisposableServer;
import reactor.netty.http.server.HttpServer;
import org.springframework.ai.mcp.server.transport.SseServerTransport;
import org.springframework.ai.mcp.spec.McpTransport;
import org.springframework.ai.mcp.spec.ServerMcpTransport;
import org.springframework.http.server.reactive.HttpHandler;
import org.springframework.http.server.reactive.ReactorHttpHandlerAdapter;
import org.springframework.web.reactive.function.server.RouterFunctions;
@ -42,7 +42,7 @@ class SseMcpAsyncServerTests extends AbstractMcpAsyncServerTests {
private DisposableServer httpServer;
@Override
protected McpTransport createMcpTransport() {
protected ServerMcpTransport createMcpTransport() {
var transport = new SseServerTransport(new ObjectMapper(), MESSAGE_ENDPOINT);
HttpHandler httpHandler = RouterFunctions.toHttpHandler(transport.getRouterFunction());

Some files were not shown because too many files have changed in this diff Show more