WIP: Add remaining javadocs, tiny corrections here and there

chemicL · chemicL · commit 92be635ad1b0 · 2025-07-30T12:17:43.000+02:00
Signed-off-by: Dariusz Jędrzejczyk &lt;dariusz.jedrzejczyk@broadcom.com&gt;
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxStreamableMcpAsyncServerTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxStreamableMcpAsyncServerTests.java
@@ -17,9 +17,11 @@
 import reactor.netty.http.server.HttpServer;
 
 /**
- * Tests for {@link McpAsyncServer} using {@link WebFluxSseServerTransportProvider}.
+ * Tests for {@link McpAsyncServer} using
+ * {@link WebFluxStreamableServerTransportProvider}.
  *
  * @author Christian Tzolov
+ * @author Dariusz Jędrzejczyk
  */
 @Timeout(15) // Giving extra time beyond the client timeout
 class WebFluxStreamableMcpAsyncServerTests extends AbstractMcpAsyncServerTests {
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxStreamableMcpSyncServerTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxStreamableMcpSyncServerTests.java
@@ -16,9 +16,11 @@
 import reactor.netty.http.server.HttpServer;
 
 /**
- * Tests for {@link McpAsyncServer} using {@link WebFluxSseServerTransportProvider}.
+ * Tests for {@link McpAsyncServer} using
+ * {@link WebFluxStreamableServerTransportProvider}.
  *
  * @author Christian Tzolov
+ * @author Dariusz Jędrzejczyk
  */
 @Timeout(15) // Giving extra time beyond the client timeout
 class WebFluxStreamableMcpSyncServerTests extends AbstractMcpSyncServerTests {
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
@@ -18,7 +18,6 @@
 import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
 import io.modelcontextprotocol.spec.McpSchema.Tool;
 import io.modelcontextprotocol.spec.McpServerTransportProvider;
-import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
@@ -28,7 +28,7 @@
 
 /**
  * Test suite for the {@link McpSyncServer} that can be used with different
- * {@link McpTransportProvider} implementations.
+ * {@link McpServerTransportProvider} implementations.
  *
  * @author Christian Tzolov
  */
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpStatelessServerHandler.java b/mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpStatelessServerHandler.java
@@ -8,7 +8,7 @@
 
 import java.util.Map;
 
-public class DefaultMcpStatelessServerHandler implements McpStatelessServerHandler {
+class DefaultMcpStatelessServerHandler implements McpStatelessServerHandler {
 
 	private static final Logger logger = LoggerFactory.getLogger(DefaultMcpStatelessServerHandler.class);
 
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpTransportContext.java b/mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpTransportContext.java
@@ -3,10 +3,19 @@
 import java.util.Map;
 import java.util.concurrent.ConcurrentHashMap;
 
+/**
+ * Default implementation for {@link McpTransportContext} which uses a Thread-safe map.
+ * Objects of this kind are mutable.
+ *
+ * @author Dariusz Jędrzejczyk
+ */
 public class DefaultMcpTransportContext implements McpTransportContext {
 
 	private final Map<String, Object> storage;
 
+	/**
+	 * Create an empty instance.
+	 */
 	public DefaultMcpTransportContext() {
 		this.storage = new ConcurrentHashMap<>();
 	}
@@ -25,6 +34,10 @@ public void put(String key, Object value) {
 		this.storage.put(key, value);
 	}
 
+	/**
+	 * Allows copying the contents.
+	 * @return new instance with the copy of the underlying map
+	 */
 	public McpTransportContext copy() {
 		return new DefaultMcpTransportContext(new ConcurrentHashMap<>(this.storage));
 	}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServerExchange.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServerExchange.java
@@ -75,9 +75,9 @@ public McpAsyncServerExchange(McpSession session, McpSchema.ClientCapabilities c
 	 * @param session The server session representing a 1-1 interaction.
 	 * @param clientCapabilities The client capabilities that define the supported
 	 * features and functionality.
+	 * @param clientInfo The client implementation information.
 	 * @param transportContext context associated with the client as extracted from the
 	 * transport
-	 * @param clientInfo The client implementation information.
 	 */
 	public McpAsyncServerExchange(String sessionId, McpLoggableSession session,
 			McpSchema.ClientCapabilities clientCapabilities, McpSchema.Implementation clientInfo,
@@ -105,10 +105,20 @@ public McpSchema.Implementation getClientInfo() {
 		return this.clientInfo;
 	}
 
+	/**
+	 * Provides the {@link McpTransportContext} associated with the transport layer. For
+	 * HTTP transports it can contain the metadata associated with the HTTP request that
+	 * triggered the processing.
+	 * @return the transport context object
+	 */
 	public McpTransportContext transportContext() {
 		return this.transportContext;
 	}
 
+	/**
+	 * Provides the Session ID.
+	 * @return session ID string
+	 */
 	public String sessionId() {
 		return this.sessionId;
 	}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java
@@ -183,10 +183,26 @@ static AsyncSpecification<?> async(McpStreamableServerTransportProvider transpor
 		return new StreamableServerAsyncSpecification(transportProvider);
 	}
 
+	/**
+	 * Starts building an asynchronous MCP server that provides non-blocking operations.
+	 * Asynchronous servers can handle multiple requests concurrently on a single Thread
+	 * using a functional paradigm with non-blocking server transports, making them more
+	 * scalable for high-concurrency scenarios but more complex to implement.
+	 * @param transport The transport layer implementation for MCP communication.
+	 * @return A new instance of {@link AsyncSpecification} for configuring the server.
+	 */
 	static StatelessAsyncSpecification async(McpStatelessServerTransport transport) {
 		return new StatelessAsyncSpecification(transport);
 	}
 
+	/**
+	 * Starts building a synchronous MCP server that provides blocking operations.
+	 * Synchronous servers block the current Thread's execution upon each request before
+	 * giving the control back to the caller, making them simpler to implement but
+	 * potentially less scalable for concurrent operations.
+	 * @param transport The transport layer implementation for MCP communication.
+	 * @return A new instance of {@link SyncSpecification} for configuring the server.
+	 */
 	static StatelessSyncSpecification sync(McpStatelessServerTransport transport) {
 		return new StatelessSyncSpecification(transport);
 	}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
@@ -32,6 +32,11 @@
 import java.util.function.BiFunction;
 
 /**
+ * A stateless MCP server implementation for use with Streamable HTTP transport types. It
+ * allows simple horizontal scalability since it does not maintain a session and does not
+ * require initialization. Each instance of the server can be reached with no prior
+ * knowledge and can serve the clients with the capabilities it supports.
+ *
  * @author Dariusz Jędrzejczyk
  */
 public class McpStatelessAsyncServer {
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessNotificationHandler.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessNotificationHandler.java
@@ -2,8 +2,19 @@
 
 import reactor.core.publisher.Mono;
 
+/**
+ * Handler for MCP notifications in a stateless server.
+ *
+ * @author Dariusz Jędrzejczyk
+ */
 public interface McpStatelessNotificationHandler {
 
+	/**
+	 * Handle to notification and complete once done.
+	 * @param transportContext {@link McpTransportContext} associated with the transport
+	 * @param params the payload of the MCP notification
+	 * @return Mono which completes once the processing is done
+	 */
 	Mono<Void> handle(McpTransportContext transportContext, Object params);
 
 }
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessRequestHandler.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessRequestHandler.java
@@ -2,8 +2,20 @@
 
 import reactor.core.publisher.Mono;
 
+/**
+ * Handler for MCP requests in a stateless server.
+ *
+ * @param <R> type of the MCP response
+ * @author Dariusz Jędrzejczyk
+ */
 public interface McpStatelessRequestHandler<R> {
 
+	/**
+	 * Handle the request and complete with a result.
+	 * @param transportContext {@link McpTransportContext} associated with the transport
+	 * @param params the payload of the MCP request
+	 * @return Mono which completes with the response object
+	 */
 	Mono<R> handle(McpTransportContext transportContext, Object params);
 
 }
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerHandler.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerHandler.java
@@ -3,11 +3,31 @@
 import io.modelcontextprotocol.spec.McpSchema;
 import reactor.core.publisher.Mono;
 
+/**
+ * Handler for MCP requests and notifications in a Stateless Streamable HTTP Server
+ * context.
+ *
+ * @author Dariusz Jędrzejczyk
+ */
 public interface McpStatelessServerHandler {
 
+	/**
+	 * Handle the request using user-provided feature implementations.
+	 * @param transportContext {@link McpTransportContext} carrying transport layer
+	 * metadata
+	 * @param request the request JSON object
+	 * @return Mono containing the JSON response
+	 */
 	Mono<McpSchema.JSONRPCResponse> handleRequest(McpTransportContext transportContext,
 			McpSchema.JSONRPCRequest request);
 
+	/**
+	 * Handle the notification.
+	 * @param transportContext {@link McpTransportContext} carrying transport layer
+	 * metadata
+	 * @param notification the notification JSON object
+	 * @return Mono that completes once handling is finished
+	 */
 	Mono<Void> handleNotification(McpTransportContext transportContext, McpSchema.JSONRPCNotification notification);
 
 }
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessSyncServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessSyncServer.java
@@ -12,6 +12,11 @@
 import java.util.List;
 
 /**
+ * A stateless MCP server implementation for use with Streamable HTTP transport types. It
+ * allows simple horizontal scalability since it does not maintain a session and does not
+ * require initialization. Each instance of the server can be reached with no prior
+ * knowledge and can serve the clients with the capabilities it supports.
+ *
  * @author Dariusz Jędrzejczyk
  */
 public class McpStatelessSyncServer {
@@ -22,10 +27,6 @@ public class McpStatelessSyncServer {
 
 	private final boolean immediateExecution;
 
-	McpStatelessSyncServer(McpStatelessAsyncServer asyncServer) {
-		this(asyncServer, false);
-	}
-
 	McpStatelessSyncServer(McpStatelessAsyncServer asyncServer, boolean immediateExecution) {
 		this.asyncServer = asyncServer;
 		this.immediateExecution = immediateExecution;
@@ -65,7 +66,6 @@ public void close() {
 	/**
 	 * Add a new tool specification at runtime.
 	 * @param toolSpecification The tool specification to add
-	 * @return Mono that completes when clients have been notified of the change
 	 */
 	public void addTool(McpStatelessServerFeatures.SyncToolSpecification toolSpecification) {
 		this.asyncServer
@@ -77,7 +77,6 @@ public void addTool(McpStatelessServerFeatures.SyncToolSpecification toolSpecifi
 	/**
 	 * Remove a tool handler at runtime.
 	 * @param toolName The name of the tool handler to remove
-	 * @return Mono that completes when clients have been notified of the change
 	 */
 	public void removeTool(String toolName) {
 		this.asyncServer.removeTool(toolName).block();
@@ -86,7 +85,6 @@ public void removeTool(String toolName) {
 	/**
 	 * Add a new resource handler at runtime.
 	 * @param resourceSpecification The resource handler to add
-	 * @return Mono that completes when clients have been notified of the change
 	 */
 	public void addResource(McpStatelessServerFeatures.SyncResourceSpecification resourceSpecification) {
 		this.asyncServer
@@ -98,7 +96,6 @@ public void addResource(McpStatelessServerFeatures.SyncResourceSpecification res
 	/**
 	 * Remove a resource handler at runtime.
 	 * @param resourceUri The URI of the resource handler to remove
-	 * @return Mono that completes when clients have been notified of the change
 	 */
 	public void removeResource(String resourceUri) {
 		this.asyncServer.removeResource(resourceUri).block();
@@ -107,7 +104,6 @@ public void removeResource(String resourceUri) {
 	/**
 	 * Add a new prompt handler at runtime.
 	 * @param promptSpecification The prompt handler to add
-	 * @return Mono that completes when clients have been notified of the change
 	 */
 	public void addPrompt(McpStatelessServerFeatures.SyncPromptSpecification promptSpecification) {
 		this.asyncServer
@@ -119,7 +115,6 @@ public void addPrompt(McpStatelessServerFeatures.SyncPromptSpecification promptS
 	/**
 	 * Remove a prompt handler at runtime.
 	 * @param promptName The name of the prompt handler to remove
-	 * @return Mono that completes when clients have been notified of the change
 	 */
 	public void removePrompt(String promptName) {
 		this.asyncServer.removePrompt(promptName).block();
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpSyncServerExchange.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpSyncServerExchange.java
@@ -27,6 +27,10 @@ public McpSyncServerExchange(McpAsyncServerExchange exchange) {
 		this.exchange = exchange;
 	}
 
+	/**
+	 * Provides the Session ID
+	 * @return session ID
+	 */
 	public String sessionId() {
 		return this.exchange.sessionId();
 	}
@@ -47,6 +51,12 @@ public McpSchema.Implementation getClientInfo() {
 		return this.exchange.getClientInfo();
 	}
 
+	/**
+	 * Provides the {@link McpTransportContext} associated with the transport layer. For
+	 * HTTP transports it can contain the metadata associated with the HTTP request that
+	 * triggered the processing.
+	 * @return the transport context object
+	 */
 	public McpTransportContext transportContext() {
 		return this.exchange.transportContext();
 	}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpTransportContext.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpTransportContext.java
@@ -1,15 +1,46 @@
 package io.modelcontextprotocol.server;
 
+import java.util.Collections;
+
+/**
+ * Context associated with the transport layer. It allows to add transport-level metadata
+ * for use further down the line. Specifically, it can be beneficial to extract HTTP
+ * request metadata for use in MCP feature implementations.
+ *
+ * @author Dariusz Jędrzejczyk
+ */
 public interface McpTransportContext {
 
+	/**
+	 * Key for use in Reactor Context to transport the context to user land.
+	 */
 	String KEY = "MCP_TRANSPORT_CONTEXT";
 
-	McpTransportContext EMPTY = new DefaultMcpTransportContext();
+	/**
+	 * An empty, unmodifiable context.
+	 */
+	@SuppressWarnings("unchecked")
+	McpTransportContext EMPTY = new DefaultMcpTransportContext(Collections.EMPTY_MAP);
 
+	/**
+	 * Extract a value from the context.
+	 * @param key the key under the data is expected
+	 * @return the associated value or {@code null} if missing.
+	 */
 	Object get(String key);
 
+	/**
+	 * Inserts a value for a given key.
+	 * @param key a String representing the key
+	 * @param value the value to store
+	 */
 	void put(String key, Object value);
 
+	/**
+	 * Copies the contents of the context to allow further modifications without affecting
+	 * the initial object.
+	 * @return a new instance with the underlying storage copied.
+	 */
 	McpTransportContext copy();
 
 }
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpTransportContextExtractor.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpTransportContextExtractor.java
@@ -1,7 +1,24 @@
 package io.modelcontextprotocol.server;
 
+/**
+ * The contract for extracting metadata from a generic transport request of type
+ * {@link T}.
+ *
+ * @param <T> transport-specific representation of the request which allows extracting
+ * metadata for use in the MCP features implementations.
+ * @author Dariusz Jędrzejczyk
+ */
 public interface McpTransportContextExtractor<T> {
 
+	/**
+	 * Given an empty context, provides the means to fill it with transport-specific
+	 * metadata extracted from the request.
+	 * @param request the generic representation for the request in the context of a
+	 * specific transport implementation
+	 * @param transportContext the mutable context which can be filled in with metadata
+	 * @return the context filled in with metadata. It can be the same instance as
+	 * provided or a new one.
+	 */
 	McpTransportContext extract(T request, McpTransportContext transportContext);
 
 }
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultMcpStreamableServerSessionFactory.java b/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultMcpStreamableServerSessionFactory.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpLoggableSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpLoggableSession.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProvider.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProvider.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransport.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransport.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransportProvider.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransportProvider.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/MissingMcpTransportSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/MissingMcpTransportSession.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java

Original file line number	Diff line number	Diff line change
`@@ -28,7 +28,7 @@`
`28`	`28`
`29`	`29`	`/**`
`30`	`30`	`* Test suite for the {@link McpSyncServer} that can be used with different`
`31`		`- * {@link McpTransportProvider} implementations.`
	`31`	`+ * {@link McpServerTransportProvider} implementations.`
`32`	`32`	`*`
`33`	`33`	`* @author Christian Tzolov`
`34`	`34`	`*/`