WIP: Add remaining javadocs, tiny corrections here and there

Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>

Author: chemicL

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 {

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 {

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;

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
  */

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);
 

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));
 	}

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;
 	}

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);
 	}

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 {

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);
 
 }