Improve docs

Author: tzolov

docs/docs/dependency-management.mdx

@@ -120,7 +120,97 @@ client.initialize()
   </Tab>
 </Tabs>
 
-## Client Features
+## Client Transport
+
+The transport layer handles the communication between MCP clients and servers, providing different implementations for various use cases. The client transport manages message serialization, connection establishment, and protocol-specific communication patterns.
+
+<Tabs>
+    <Tab title="STDIO">
+        Creates transport for in-process based communication
+        ```java
+        ServerParameters params = ServerParameters.builder("npx")
+            .args("-y", "@modelcontextprotocol/server-everything", "dir")
+            .build();
+        McpTransport transport = new StdioClientTransport(params);
+        ```
+    </Tab>
+    <Tab title="SSE (HttpClient)">
+        Creates a framework agnostic (pure Java API) SSE client transport. Included in the core mcp module.
+        ```java
+        McpTransport transport = new HttpClientSseClientTransport("http://your-mcp-server");
+        ```
+    </Tab>
+    <Tab title="SSE (WebFlux)">
+        Creates WebFlux-based SSE client transport. Requires the mcp-webflux-sse-transport dependency.
+        ```java
+        WebClient.Builder webClientBuilder = WebClient.builder()
+            .baseUrl("http://your-mcp-server");
+        McpTransport transport = new WebFluxSseClientTransport(webClientBuilder);
+        ```
+    </Tab>
+</Tabs>
+
+## Client Capabilities
+
+The client can be configured with various capabilities:
+
+```java
+var capabilities = ClientCapabilities.builder()
+    .roots(true)      // Enable filesystem roots support with list changes notifications
+    .sampling()       // Enable LLM sampling support
+    .build();
+```
+
+### Roots Support
+
+Roots define the boundaries of where servers can operate within the filesystem:
+
+```java
+// Add a root dynamically
+client.addRoot(new Root("file:///path", "description"));
+
+// Remove a root
+client.removeRoot("file:///path");
+
+// Notify server of roots changes
+client.rootsListChangedNotification();
+```
+
+The roots capability allows servers to:
+
+- Request the list of accessible filesystem roots
+- Receive notifications when the root list changes
+- Understand which directories and files they have access to
+
+
+### Sampling Support
+
+Sampling enables servers to request LLM interactions ("completions" or "generations") through the client:
+
+```java
+// Configure sampling handler
+Function<CreateMessageRequest, CreateMessageResult> samplingHandler = request -> {
+    // Sampling implementation that interfaces with LLM
+    return new CreateMessageResult(response);
+};
+
+// Create client with sampling support
+var client = McpClient.sync(transport)
+    .capabilities(ClientCapabilities.builder()
+        .sampling()
+        .build())
+    .sampling(samplingHandler)
+    .build();
+```
+
+This capability allows:
+- Servers to leverage AI capabilities without requiring API keys
+- Clients to maintain control over model access and permissions
+- Support for both text and image-based interactions
+- Optional inclusion of MCP server context in prompts
+
+
+## Using MCP Clients
 
 ### Tool Execution
 
@@ -134,7 +224,7 @@ var tools = client.listTools();
 tools.forEach(tool -> System.out.println(tool.getName()));
 
 // Execute a tool
-var result = client.executeTool("calculator", Map.of(
+var result = client.callTool("calculator", Map.of(
     "operation", "add",
     "a", 1,
     "b", 2
@@ -151,7 +241,7 @@ client.listTools()
     .subscribe();
 
 // Execute a tool
-client.executeTool("calculator", Map.of(
+client.callTool("calculator", Map.of(
         "operation", "add",
         "a", 1,
         "b", 2