Expand module documentation with detailed examples, structured sections, and knit snippets

Author: devcrocod

docs/moduledoc.md

@@ -1,21 +1,17 @@
 # MCP Kotlin SDK
 
-Kotlin SDK for the Model Context Protocol (MCP).
-This is a Kotlin Multiplatform library that helps you build MCP clients and servers that speak the same protocol and
-share the same types.
-The SDK focuses on clarity, small building blocks, and first‑class coroutine support.
+Kotlin Multiplatform implementation of the Model Context Protocol (MCP). The SDK focuses on clear, explicit APIs,
+small building blocks, and first-class coroutine support so clients and servers share the same well-typed messages and
+transports.
 
-Use the umbrella `kotlin-sdk` artifact when you want a single dependency that brings the core types plus both client and
-server toolkits. If you only need one side, depend on `kotlin-sdk-client` or `kotlin-sdk-server` directly.
-
-Gradle (Kotlin DSL):
+Use the umbrella `kotlin-sdk` artifact to bring in everything at once, or depend on the focused modules directly:
 
 ```kotlin
 dependencies {
-    // Convenience bundle with everything you need to start
+    // All-in-one bundle
     implementation("io.modelcontextprotocol:kotlin-sdk:<version>")
 
-    // Or pick modules explicitly
+    // Or pick sides explicitly
     implementation("io.modelcontextprotocol:kotlin-sdk-client:<version>")
     implementation("io.modelcontextprotocol:kotlin-sdk-server:<version>")
 }
@@ -25,79 +21,73 @@ dependencies {
 
 ## Module kotlin-sdk-core
 
-Foundational, platform‑agnostic pieces:
+Foundation shared by both sides:
 
-- Protocol data model and JSON serialization (kotlinx.serialization)
-- Request/response and notification types used by both sides of MCP
-- Coroutine‑friendly protocol engine and utilities
-- Transport abstractions shared by client and server
+- Protocol data model for MCP requests, results, notifications, capabilities, and content types.
+- `McpJson` (kotlinx.serialization) with MCP-friendly defaults plus helpers for converting native values to JSON.
+- Transport abstractions (`Transport`, `AbstractTransport`, `WebSocketMcpTransport`) and streaming `ReadBuffer`.
+- `Protocol` base class that handles JSON-RPC framing, correlation, progress tokens, and capability assertions.
 
-You typically do not use `core` directly in application code; it is pulled in by the client/server modules. Use it
-explicitly if you only need the protocol types or plan to implement a custom transport.
+Use `core` when you need the raw types or want to author a custom transport. Public APIs are explicit to keep the shared
+surface stable across platforms.
 
 ---
 
 ## Module kotlin-sdk-client
 
-High‑level client API for connecting to an MCP server and invoking its tools, prompts, and resources. Ships with several
-transports:
+High-level client for connecting to MCP servers and invoking their features:
 
-- WebSocketClientTransport – low latency, full‑duplex
-- SSEClientTransport – Server‑Sent Events over HTTP
-- StdioClientTransport – CLI‑friendly stdio bridge
-- StreamableHttpClientTransport – simple HTTP streaming
+- `Client` runtime (or `mcpClient` helper) performs the MCP handshake and exposes `serverCapabilities`,
+  `serverVersion`, and `serverInstructions`.
+- Typed operations for tools, prompts, resources, completion, logging, roots, sampling, and elicitation with capability
+  enforcement.
+- Transports: `StdioClientTransport`, `SSEClientTransport`, `WebSocketClientTransport`, and `StreamableHttpClientTransport`,
+  plus Ktor client extensions for quick wiring.
 
-A minimal client:
+Minimal WebSocket client:
 
 ```kotlin
-val client = Client(
-    clientInfo = Implementation(name = "sample-client", version = "1.0.0")
+val client = mcpClient(
+    clientInfo = Implementation("sample-client", "1.0.0"),
+    clientOptions = ClientOptions(ClientCapabilities(tools = ClientCapabilities.Tools())),
+    transport = WebSocketClientTransport("ws://localhost:8080/mcp")
 )
 
-client.connect(WebSocketClientTransport("ws://localhost:8080/mcp"))
-
 val tools = client.listTools()
-val result = client.callTool(
-    name = "echo",
-    arguments = mapOf("text" to "Hello, MCP!")
-)
+val result = client.callTool("echo", mapOf("text" to "Hello, MCP!"))
+println(result.content)
 ```
 
 ---
 
 ## Module kotlin-sdk-server
 
-Lightweight server toolkit for hosting MCP tools, prompts, and resources. It provides a small, composable API and
-ready‑to‑use transports:
+Server toolkit for exposing MCP tools, prompts, and resources:
 
-- StdioServerTransport – integrates well with CLIs and editors
-- SSE/WebSocket helpers for Ktor – easy HTTP deployment
+- `Server` runtime coordinates sessions, initialization flow, and capability enforcement with registries for tools,
+  prompts, resources, and templates.
+- Transports: `StdioServerTransport` for CLI/editor bridges; Ktor extensions (`mcp` for SSE + POST back-channel and
+  `mcpWebSocket` for WebSocket) for HTTP hosting.
+- Built-in notifications for list changes and resource subscriptions when capabilities enable them.
 
-Register tools and run over stdio:
+Minimal Ktor SSE server:
 
 ```kotlin
-
-val server = Server(
-    serverInfo = Implementation(name = "sample-server", version = "1.0.0"),
-    options = ServerOptions(ServerCapabilities())
-)
-
-server.addTool(
-    name = "echo",
-    description = "Echoes the provided text"
-) { request ->
-    // Build and return a CallToolResult from request.arguments
-    // (see CallToolResult and related types in kotlin-sdk-core)
-    /* ... */
+fun Application.module() {
+    mcp {
+        Server(
+            serverInfo = Implementation("sample-server", "1.0.0"),
+            options = ServerOptions(ServerCapabilities(
+                tools = ServerCapabilities.Tools(listChanged = true),
+                resources = ServerCapabilities.Resources(listChanged = true, subscribe = true),
+            )),
+        ) {
+            addTool(name = "echo", description = "Echo text back") { request ->
+                CallToolResult(content = listOf(TextContent("You said: ${request.params.arguments["text"]}")))
+            }
+        }
+    }
 }
-
-// Bridge the protocol over stdio
-val transport = StdioServerTransport(
-    inputStream = kotlinx.io.files.Path("/dev/stdin").source(),
-    outputStream = kotlinx.io.files.Path("/dev/stdout").sink()
-)
-// Start transport and wire it with the server using provided helpers in the SDK.
 ```
 
-For HTTP deployments, use the Ktor extensions included in the module to expose an MCP WebSocket or SSE endpoint with a
-few lines of code.
+Pick the module that matches your role, or use the umbrella artifact to get both sides with the shared core.

kotlin-sdk-client/Module.md

@@ -1,10 +1,74 @@
-# Module kotlin-sdk-client
+# kotlin-sdk-client
 
-The Model Context Protocol (MCP) Kotlin SDK client module provides a multiplatform implementation for connecting to and
-interacting with MCP servers.
+`kotlin-sdk-client` is the multiplatform MCP client for Kotlin. It handles the MCP handshake, enforces capabilities, and
+gives you typed APIs to call tools, prompts, resources, completions, and logging endpoints on MCP servers. It reuses
+protocol types from `kotlin-sdk-core` and ships with transports for CLI and Ktor-based networking.
 
-## Features
+## What the module provides
 
-- Cross-platform support for JVM, WASM, JS, and Native
-- Built-in support for multiple transport protocols (stdio, SSE, WebSocket)
-- Type-safe API for resource management and server interactions
+- **Client runtime**: The `Client` class (or `mcpClient` helper) wraps initialization, capability checks, and
+  request/notification plumbing. After connecting, it exposes `serverCapabilities`, `serverVersion`, and
+  `serverInstructions`.
+- **Typed operations**: Convenience functions like `listTools`, `callTool`, `listResources`, `readResource`,
+  `listPrompts`, `complete`, `setLoggingLevel`, and subscription helpers for resources.
+- **Capability enforcement**: Methods fail fast if the server does not advertise the needed capability; optional
+  strictness mirrors the protocol options used by the server SDK.
+- **Transports**: Ready-to-use implementations for STDIO (CLI interoperability), Ktor SSE (`SSEClientTransport` with
+  POST back-channel), Ktor WebSocket, and Streamable HTTP for environments that prefer request/response streaming.
+- **Ktor client integration**: Extension helpers wire MCP over Ktor client engines with minimal setup for SSE,
+  Streamable HTTP, or WebSocket.
+
+## Typical client setup
+
+1. Declare client capabilities with `ClientOptions` (e.g., tools, prompts, resources, logging, roots, sampling,
+   elicitation).
+2. Create a transport suitable for your environment.
+3. Connect using `mcpClient` or instantiate `Client` and call `connect(transport)`.
+4. Use typed APIs to interact with the server; results and errors use the shared MCP types.
+
+### Minimal STDIO client
+
+```kotlin
+val client = mcpClient(
+    clientInfo = Implementation(name = "demo-client", version = "1.0.0"),
+    clientOptions = ClientOptions(
+        capabilities = ClientCapabilities(
+            tools = ClientCapabilities.Tools(),
+            resources = ClientCapabilities.Resources(subscribe = true),
+        )
+    ),
+    transport = StdioClientTransport(System.`in`.source(), System.out.sink())
+)
+
+val tools = client.listTools()
+val result = client.callTool("hello", mapOf("name" to "Kotlin"))
+println(result.content)
+```
+
+### Ktor-based transports
+
+- **SSE** (streaming GET + POST back-channel): create `SSEClientTransport(baseUrl, httpClient)`; sessions are keyed by
+  `sessionId` managed by the SDK.
+- **WebSocket**: use `WebSocketClientTransport(url, httpClient)` to get bidirectional messaging in one connection.
+- **Streamable HTTP**: `StreamableHttpClientTransport` enables MCP over streaming HTTP where WebSockets are unavailable.
+
+## Feature usage highlights
+
+- **Tools**: `callTool` accepts raw maps or `CallToolRequest`; metadata keys are validated per MCP rules.
+- **Prompts & completion**: `getPrompt`, `listPrompts`, and `complete` wrap common prompt flows.
+- **Resources**: `listResources`, `listResourceTemplates`, `readResource`, and `subscribeResource` cover discovery,
+  templating, and updates (when the server allows subscriptions).
+- **Roots**: If enabled, register local roots with `addRoot`/`addRoots`; the client responds to `RootsList` requests
+  from the server.
+- **Notifications**: Built-in handlers cover initialization, cancellation, progress, and roots list changes; you can
+  register more handlers via the underlying `Protocol` API.
+
+## Diagnostics and lifecycle
+
+- Capability assertions prevent calling endpoints the server does not expose; errors surface with clear messages.
+- Logging uses `KotlinLogging`; enable DEBUG to inspect transport and handshake behavior.
+- `close()` tears down the transport and cancels in-flight requests.
+
+Use this module whenever you need an MCP-aware Kotlin client—whether embedding in a CLI over STDIO or talking to remote
+servers via Ktor SSE/WebSocket/streamable HTTP transports. Public APIs are explicit so downstream users can rely on
+stable, well-typed surface areas across platforms.

kotlin-sdk-core/Module.md

@@ -1,5 +1,47 @@
-# Module kotlin-sdk-core
+# kotlin-sdk-core
 
-The MCP Kotlin SDK Core module provides fundamental functionality for interacting with Model Context Protocol (MCP).
-This module serves as the foundation for building MCP-enabled applications in Kotlin.
+`kotlin-sdk-core` is the foundation of the MCP Kotlin SDK. It contains protocol message types, JSON handling, and
+transport abstractions used by both client and server modules. No platform-specific code lives here; everything is
+designed for Kotlin Multiplatform with explicit API mode enabled.
 
+## What the module provides
+
+- **Protocol model**: Complete MCP data classes for requests, results, notifications, capabilities, tools, prompts,
+  resources, logging, completion, sampling, elicitation, and roots. DSL helpers (`*.dsl.kt`) let you build messages
+  fluently without repeating boilerplate.
+- **JSON utilities**: A shared `McpJson` configuration (kotlinx.serialization) with MCP-friendly settings (ignore
+  unknown keys, no class discriminator). Helpers for converting maps to `JsonElement`, `EmptyJsonObject`, and
+  encoding/decoding JSON-RPC envelopes.
+- **Transport abstractions**: `Transport` and `AbstractTransport` define the message pipeline, callbacks, and error
+  handling. `WebSocketMcpTransport` adds a shared WebSocket implementation for both client and server sides, and
+  `ReadBuffer` handles streaming JSON-RPC framing.
+- **Protocol engine**: The `Protocol` base class manages request/response correlation, notifications, progress tokens,
+  and capability assertions. Higher-level modules extend it to become `Client` and `Server`.
+- **Errors and safety**: Common exception types (`McpException`, parsing errors) plus capability enforcement hooks
+  ensure callers cannot use endpoints the peer does not advertise.
+
+## Typical usage
+
+- Import MCP types to define capabilities and message payloads for your own transports or custom integrations.
+- Extend `Protocol` if you need a bespoke peer role while reusing correlation logic and JSON-RPC helpers.
+- Use the DSL builders to construct well-typed requests (tools, prompts, resources, logging, completion) instead of
+  crafting raw JSON.
+
+### Example: building a tool call request
+
+```kotlin
+val request = CallToolRequest {
+    name = "summarize"
+    arguments = mapOf("text" to "Hello MCP")
+}
+```
+
+### Example: parsing a JSON-RPC message
+
+```kotlin
+val message: JSONRPCMessage = McpJson.decodeFromString(jsonString)
+```
+
+Use this module when you need the raw building blocks of MCP—types, JSON config, and transport base classes—whether to
+embed in another runtime, author new transports, or contribute higher-level features in the client/server modules. The
+APIs are explicit to keep the shared surface stable for downstream users.