Restructure javadoc documentation to eliminate duplicate overviews

jonathanhefner · claude · jonathanhefner · commit f3e1bb54172c · 2025-12-16T08:57:21.000-06:00
- Merge Features and Architecture sections from `sdk-overview.md` into `overview.md` - Create `getting-started.md` with Dependency and BOM setup instructions - Delete `sdk-overview.md` (content redistributed) - Update links to point to `getting-started.html` 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
diff --git a/mcp-core/src/main/javadoc/io/modelcontextprotocol/doc-files/getting-started.md b/mcp-core/src/main/javadoc/io/modelcontextprotocol/doc-files/getting-started.md
@@ -0,0 +1,114 @@
+# Getting Started
+
+Add the following dependencies to your project:
+
+## Maven
+
+The core MCP functionality:
+
+```xml
+<dependency>
+    <groupId>io.modelcontextprotocol.sdk</groupId>
+    <artifactId>mcp</artifactId>
+</dependency>
+```
+
+The core `mcp` module already includes default `STDIO`, `SSE` and `Streamable-HTTP` transport implementations and doesn't require external web frameworks.
+
+If you're using the Spring Framework and want to use Spring-specific transport implementations, add one of the following optional dependencies:
+
+```xml
+<!-- Optional: Spring WebFlux-based SSE and Streamable-HTTP client and server transports -->
+<dependency>
+    <groupId>io.modelcontextprotocol.sdk</groupId>
+    <artifactId>mcp-spring-webflux</artifactId>
+</dependency>
+
+<!-- Optional: Spring WebMVC-based SSE and Streamable-HTTP server transports -->
+<dependency>
+    <groupId>io.modelcontextprotocol.sdk</groupId>
+    <artifactId>mcp-spring-webmvc</artifactId>
+</dependency>
+```
+
+## Gradle
+
+The core MCP functionality:
+
+```groovy
+dependencies {
+  implementation platform("io.modelcontextprotocol.sdk:mcp")
+  //...
+}
+```
+
+The core `mcp` module already includes default `STDIO`, `SSE` and `Streamable-HTTP` transport implementations and doesn't require external web frameworks.
+
+If you're using the Spring Framework and want to use Spring-specific transport implementations, add one of the following optional dependencies:
+
+```groovy
+// Optional: Spring WebFlux-based SSE and Streamable-HTTP client and server transports
+dependencies {
+  implementation platform("io.modelcontextprotocol.sdk:mcp-spring-webflux")
+}
+
+// Optional: Spring WebMVC-based SSE and Streamable-HTTP server transports
+dependencies {
+  implementation platform("io.modelcontextprotocol.sdk:mcp-spring-webmvc")
+}
+```
+
+---
+
+- `io.modelcontextprotocol.sdk:mcp-spring-webflux` - WebFlux-based Client and Server, `Streamable-HTTP` and `SSE` transport implementations.
+  The WebFlux implementation can be used in reactive applications while the WebClient-based MCP Client can be used in both reactive and imperative applications.
+  It is a highly scalable option and suitable and recommended for high-throughput scenarios.
+- `io.modelcontextprotocol.sdk:mcp-spring-webmvc` - WebMVC-based Server, `Streamable-HTTP` and `SSE` transport implementation for servlet-based applications.
+
+## Bill of Materials (BOM)
+
+The Bill of Materials (BOM) declares the recommended versions of all the dependencies used by a given release.
+Using the BOM from your application's build script avoids the need for you to specify and maintain the dependency versions yourself.
+Instead, the version of the BOM you're using determines the utilized dependency versions.
+It also ensures that you're using supported and tested versions of the dependencies by default, unless you choose to override them.
+
+Add the BOM to your project:
+
+### Maven
+
+```xml
+<dependencyManagement>
+    <dependencies>
+        <dependency>
+            <groupId>io.modelcontextprotocol.sdk</groupId>
+            <artifactId>mcp-bom</artifactId>
+            <version>0.12.1</version>
+            <type>pom</type>
+            <scope>import</scope>
+        </dependency>
+    </dependencies>
+</dependencyManagement>
+```
+
+### Gradle
+
+```groovy
+dependencies {
+  implementation platform("io.modelcontextprotocol.sdk:mcp-bom:0.12.1")
+  //...
+}
+```
+
+Gradle users can also use the MCP BOM by leveraging Gradle (5.0+) native support for declaring dependency constraints using a Maven BOM.
+This is implemented by adding a 'platform' dependency handler method to the dependencies section of your Gradle build script.
+As shown in the snippet above, this can then be followed by version-less declarations of the MCP SDK modules you wish to use.
+
+---
+
+Replace the version number with the version of the BOM you want to use.
+
+## Additional Dependencies
+
+The following additional dependencies are available and managed by the BOM:
+
+- `io.modelcontextprotocol.sdk:mcp-test` - Testing utilities and support for MCP-based applications.
diff --git a/mcp-core/src/main/javadoc/io/modelcontextprotocol/doc-files/sdk-overview.md b/mcp-core/src/main/javadoc/io/modelcontextprotocol/doc-files/sdk-overview.md
diff --git a/mcp-core/src/main/javadoc/io/modelcontextprotocol/doc-files/server.md b/mcp-core/src/main/javadoc/io/modelcontextprotocol/doc-files/server.md
@@ -110,7 +110,7 @@ Key features:
 
 ### WebFlux Transport
 
-WebFlux-based SSE and Streamable-HTTP server transport. Requires the `mcp-spring-webflux` dependency (see [Dependencies](sdk-overview.html#dependencies)).
+WebFlux-based SSE and Streamable-HTTP server transport. Requires the `mcp-spring-webflux` dependency (see [Getting Started](getting-started.html)).
 
 #### Streamable-HTTP (WebFlux)
 
diff --git a/src/main/javadoc/overview.md b/src/main/javadoc/overview.md
@@ -13,21 +13,65 @@ The source code is available at [github.com/modelcontextprotocol/java-sdk](https
 - **mcp-spring-webflux** - Spring WebFlux transport
 - **mcp-spring-webmvc** - Spring WebMVC transport
 
-## Getting Started
+## Features
 
-Add the MCP SDK to your project:
+- MCP Client and MCP Server implementations supporting:
+  - Protocol [version compatibility negotiation](https://modelcontextprotocol.io/specification/latest/basic/lifecycle#initialization)
+  - [Tool](https://modelcontextprotocol.io/specification/latest/server/tools/) discovery, execution, list change notifications
+  - [Resource](https://modelcontextprotocol.io/specification/latest/server/resources/) management with URI templates
+  - [Prompt](https://modelcontextprotocol.io/specification/latest/server/prompts/) handling and management
+  - [Completion](https://modelcontextprotocol.io/specification/latest/server/utilities/completion/) argument autocompletion suggestions for prompts and resource URIs
+  - [Progress](https://modelcontextprotocol.io/specification/latest/basic/utilities/progress/) progress tracking for long-running operations
+  - [Ping](https://modelcontextprotocol.io/specification/latest/basic/utilities/ping/) lightweight health check mechanism
+    - [Server Keepalive](https://modelcontextprotocol.io/specification/latest/basic/utilities/ping#implementation-considerations/) to maintain active server connections
+  - [Logging](https://modelcontextprotocol.io/specification/latest/server/utilities/logging/) for sending structured log messages to clients
+  - [Roots](https://modelcontextprotocol.io/specification/latest/client/roots/) list management and notifications
+  - [Sampling](https://modelcontextprotocol.io/specification/latest/client/sampling/) support for AI model interactions
+  - [Elicitation](https://modelcontextprotocol.io/specification/latest/client/elicitation/) for servers to request additional information from users through the client
+- Multiple transport implementations:
+  - Default transports (included in core `mcp` module, no external web frameworks required):
+    - Stdio-based transport for process-based communication
+    - Java HttpClient-based `SSE` and `Streamable-HTTP` client transport
+    - Servlet-based `SSE` and `Streamable-HTTP` server transport
+  - Optional Spring-based transports (convenience if using Spring Framework):
+    - WebFlux `SSE` and `Streamable-HTTP` client and server transports
+    - WebMVC `SSE` and `Streamable-HTTP` transport for servlet-based HTTP streaming
+- Supports Synchronous and Asynchronous programming paradigms
 
-```xml
-<dependency>
-    <groupId>io.modelcontextprotocol.sdk</groupId>
-    <artifactId>mcp</artifactId>
-    <version>${mcp.version}</version>
-</dependency>
-```
+> **Tip:** The core `io.modelcontextprotocol.sdk:mcp` module provides default `STDIO`, `SSE` and `Streamable-HTTP` client and server transport implementations without requiring external web frameworks.
+>
+> Spring-specific transports are available as optional dependencies for convenience when using the [Spring AI](https://docs.spring.io/spring-ai/reference/1.1-SNAPSHOT/api/mcp/mcp-overview.html) Framework.
+
+## Architecture
+
+The SDK follows a layered architecture with clear separation of concerns:
+
+- **Client/Server Layer (McpClient/McpServer)**: Both use McpSession for sync/async operations,
+  with McpClient handling client-side protocol operations and McpServer managing server-side protocol operations.
+- **Session Layer (McpSession)**: Manages communication patterns and state using DefaultMcpSession implementation.
+- **Transport Layer (McpTransport)**: Handles JSON-RPC message serialization/deserialization via:
+  - StdioTransport (stdin/stdout) in the core module
+  - HTTP `Streamable-HTTP` and `SSE` transports in dedicated transport modules (Java HttpClient, Spring WebFlux, Spring WebMVC)
+
+The [MCP Client](io/modelcontextprotocol/doc-files/client.html) is a key component in the Model Context Protocol (MCP) architecture, responsible for establishing and managing connections with MCP servers.
+It implements the client-side of the protocol.
+
+<img src="io/modelcontextprotocol/doc-files/images/java-mcp-client-architecture.jpg" alt="Java MCP Client Architecture" style="max-height: 80vh;">
+
+The [MCP Server](io/modelcontextprotocol/doc-files/server.html) is a foundational component in the Model Context Protocol (MCP) architecture that provides tools, resources, and capabilities to clients.
+It implements the server-side of the protocol.
+
+<img src="io/modelcontextprotocol/doc-files/images/java-mcp-server-architecture.jpg" alt="Java MCP Server Architecture" style="max-height: 80vh;">
+
+Key Interactions:
+
+- **Client/Server Initialization**: Transport setup, protocol compatibility check, capability negotiation, and implementation details exchange.
+- **Message Flow**: JSON-RPC message handling with validation, type-safe response processing, and error handling.
+- **Resource Management**: Resource discovery, URI template-based access, subscription system, and content retrieval.
 
 ## SDK Documentation
 
-- [Java SDK Overview](io/modelcontextprotocol/doc-files/sdk-overview.html) - Features, architecture, and dependencies
+- [Getting Started](io/modelcontextprotocol/doc-files/getting-started.html) - Dependencies and setup
 - [MCP Client](io/modelcontextprotocol/doc-files/client.html) - Client implementation and transport options
 - [MCP Server](io/modelcontextprotocol/doc-files/server.html) - Server implementation and transport providers
 
