#162 ## Motivation and Context - update readme - add more snippets - add knit ## How Has This Been Tested? knit on CI ## Breaking Changes None ## Types of changes - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [x] Documentation update ## Checklist - [x] I have read the [MCP Documentation](https://modelcontextprotocol.io) - [x] My code follows the repository's style guidelines - [x] New and existing tests pass locally - [ ] I have added appropriate error handling - [x] I have added or updated documentation as needed --------- Co-authored-by: devcrocod <devcrocod@gmail.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
This commit is contained in:
Konstantin Pavlov
GitHub
parent
7eb2a93c46
commit
adc4150f1f
1 changed files with 1093 additions and 195 deletions
|
|
@ -1,10 +1,78 @@
|
|||
# Module 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., sampling, roots, elicitation, experimental).
|
||||
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`.asSource().buffered(),
|
||||
System.out.asSink().buffered()
|
||||
)
|
||||
)
|
||||
|
||||
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(httpClient, url)` (or
|
||||
`HttpClient.mcpSseTransport(url)`); sessions are keyed by `sessionId` managed by the SDK.
|
||||
- **WebSocket**: use `WebSocketClientTransport(httpClient, url)` (or `HttpClient.mcpWebSocketTransport(url)`) to get
|
||||
bidirectional messaging in one connection.
|
||||
- **Streamable HTTP**: `StreamableHttpClientTransport(httpClient, url)` enables MCP over streaming HTTP
|
||||
(or `HttpClient.mcpStreamableHttpTransport(url)`).
|
||||
|
||||
## 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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue