adc4150f1f#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>
94 lines
3.6 KiB
Markdown
94 lines
3.6 KiB
Markdown
# MCP Kotlin SDK
|
|
|
|
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 to bring in everything at once, or depend on the focused modules directly:
|
|
|
|
```kotlin
|
|
dependencies {
|
|
// All-in-one bundle
|
|
implementation("io.modelcontextprotocol:kotlin-sdk:<version>")
|
|
|
|
// Or pick sides explicitly
|
|
implementation("io.modelcontextprotocol:kotlin-sdk-client:<version>")
|
|
implementation("io.modelcontextprotocol:kotlin-sdk-server:<version>")
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Module kotlin-sdk-core
|
|
|
|
Foundation shared by both sides:
|
|
|
|
- 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.
|
|
|
|
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 for connecting to MCP servers and invoking their features:
|
|
|
|
- `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.
|
|
|
|
Minimal WebSocket client:
|
|
|
|
```kotlin
|
|
val client = mcpClient(
|
|
clientInfo = Implementation("sample-client", "1.0.0"),
|
|
clientOptions = ClientOptions(ClientCapabilities(tools = ClientCapabilities.Tools())),
|
|
transport = WebSocketClientTransport("ws://localhost:8080/mcp")
|
|
)
|
|
|
|
val tools = client.listTools()
|
|
val result = client.callTool("echo", mapOf("text" to "Hello, MCP!"))
|
|
println(result.content)
|
|
```
|
|
|
|
---
|
|
|
|
## Module kotlin-sdk-server
|
|
|
|
Server toolkit for exposing MCP tools, prompts, and resources:
|
|
|
|
- `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.
|
|
|
|
Minimal Ktor SSE server:
|
|
|
|
```kotlin
|
|
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 ->
|
|
val text = request.params.arguments?.get("text")?.jsonPrimitive?.content ?: ""
|
|
CallToolResult(content = listOf(TextContent("You said: $text")))
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Pick the module that matches your role, or use the umbrella artifact to get both sides with the shared core.
|