#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:
parent
7eb2a93c46
commit
adc4150f1f
12 changed files with 1093 additions and 195 deletions
12
.github/workflows/apidocs.yaml
vendored
12
.github/workflows/apidocs.yaml
vendored
|
|
@ -7,6 +7,10 @@ on:
|
||||||
# Allow running this workflow manually from the Actions tab
|
# Allow running this workflow manually from the Actions tab
|
||||||
workflow_dispatch:
|
workflow_dispatch:
|
||||||
|
|
||||||
|
env:
|
||||||
|
JAVA_VERSION: 21
|
||||||
|
JAVA_DISTRIBUTION: temurin
|
||||||
|
|
||||||
jobs:
|
jobs:
|
||||||
deploy:
|
deploy:
|
||||||
|
|
||||||
|
|
@ -25,11 +29,11 @@ jobs:
|
||||||
submodules: true # Fetch Hugo themes (true OR recursive)
|
submodules: true # Fetch Hugo themes (true OR recursive)
|
||||||
fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod
|
fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod
|
||||||
|
|
||||||
- name: Set up JDK 21
|
- name: Set up JDK ${{ env.JAVA_VERSION }}
|
||||||
uses: actions/setup-java@v5
|
uses: actions/setup-java@v5
|
||||||
with:
|
with:
|
||||||
java-version: '21'
|
java-version: ${{ env.JAVA_VERSION }}
|
||||||
distribution: 'temurin'
|
distribution: ${{ env.JAVA_DISTRIBUTION }}
|
||||||
cache: gradle
|
cache: gradle
|
||||||
|
|
||||||
- name: Setup Gradle
|
- name: Setup Gradle
|
||||||
|
|
@ -37,7 +41,7 @@ jobs:
|
||||||
|
|
||||||
- name: Generate Dokka Site
|
- name: Generate Dokka Site
|
||||||
run: |-
|
run: |-
|
||||||
./gradlew clean dokkaGenerate
|
./gradlew clean knit docs:classes docs:knitCheck dokkaGenerate
|
||||||
|
|
||||||
- name: Upload artifact
|
- name: Upload artifact
|
||||||
uses: actions/upload-pages-artifact@v4
|
uses: actions/upload-pages-artifact@v4
|
||||||
|
|
|
||||||
34
.github/workflows/build.yml
vendored
34
.github/workflows/build.yml
vendored
|
|
@ -120,6 +120,40 @@ jobs:
|
||||||
path: local-maven-repository.zip
|
path: local-maven-repository.zip
|
||||||
retention-days: 1
|
retention-days: 1
|
||||||
|
|
||||||
|
knit:
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
name: Knit
|
||||||
|
timeout-minutes: 10
|
||||||
|
permissions:
|
||||||
|
contents: read
|
||||||
|
|
||||||
|
steps:
|
||||||
|
- uses: actions/checkout@v6
|
||||||
|
|
||||||
|
- name: Set up JDK ${{ env.JAVA_VERSION }}
|
||||||
|
uses: actions/setup-java@v5
|
||||||
|
with:
|
||||||
|
java-version: ${{ env.JAVA_VERSION }}
|
||||||
|
distribution: ${{ env.JAVA_DISTRIBUTION }}
|
||||||
|
|
||||||
|
- name: Setup Gradle
|
||||||
|
uses: gradle/actions/setup-gradle@v5
|
||||||
|
with:
|
||||||
|
validate-wrappers: true
|
||||||
|
add-job-summary: 'always'
|
||||||
|
cache-read-only: ${{ github.ref != 'refs/heads/main' }}
|
||||||
|
cache-encryption-key: ${{ secrets.GRADLE_ENCRYPTION_KEY }}
|
||||||
|
gradle-home-cache-includes: |
|
||||||
|
caches
|
||||||
|
notifications
|
||||||
|
sdks
|
||||||
|
../.konan/**
|
||||||
|
|
||||||
|
- name: Run Knit
|
||||||
|
run: |-
|
||||||
|
./gradlew knit docs:classes docs:knitCheck -x :conformance-test:test --max-workers 3 --continue --rerun-tasks --configure-on-demand --parallel
|
||||||
|
|
||||||
|
|
||||||
samples:
|
samples:
|
||||||
needs: [ build ]
|
needs: [ build ]
|
||||||
runs-on: ubuntu-latest
|
runs-on: ubuntu-latest
|
||||||
|
|
|
||||||
824
README.md
824
README.md
|
|
@ -1,6 +1,5 @@
|
||||||
# MCP Kotlin SDK
|
# MCP Kotlin SDK
|
||||||
|
|
||||||
|
|
||||||
[](https://central.sonatype.com/artifact/io.modelcontextprotocol/kotlin-sdk)
|
[](https://central.sonatype.com/artifact/io.modelcontextprotocol/kotlin-sdk)
|
||||||
[](https://github.com/modelcontextprotocol/kotlin-sdk/actions/workflows/build.yml)
|
[](https://github.com/modelcontextprotocol/kotlin-sdk/actions/workflows/build.yml)
|
||||||
[](https://github.com/modelcontextprotocol/kotlin-sdk/actions/workflows/conformance.yml)
|
[](https://github.com/modelcontextprotocol/kotlin-sdk/actions/workflows/conformance.yml)
|
||||||
|
|
@ -9,100 +8,306 @@
|
||||||
[](http://java.com)
|
[](http://java.com)
|
||||||
[](LICENSE)
|
[](LICENSE)
|
||||||
|
|
||||||
Kotlin Multiplatform implementation of the [Model Context Protocol](https://modelcontextprotocol.io) (MCP),
|
Kotlin Multiplatform SDK for the [Model Context Protocol](https://modelcontextprotocol.io).
|
||||||
providing both client and server capabilities for integrating with LLM surfaces across various platforms.
|
It enables Kotlin applications targeting JVM, Native, JS, and Wasm to implement MCP clients and servers using a
|
||||||
|
standardized protocol interface.
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
<!--- TOC -->
|
||||||
|
|
||||||
|
* [Overview](#overview)
|
||||||
|
* [Installation](#installation)
|
||||||
|
* [Artifacts](#artifacts)
|
||||||
|
* [Gradle setup (JVM)](#gradle-setup-jvm)
|
||||||
|
* [Multiplatform](#multiplatform)
|
||||||
|
* [Ktor dependencies](#ktor-dependencies)
|
||||||
|
* [Quickstart](#quickstart)
|
||||||
|
* [Creating a Client](#creating-a-client)
|
||||||
|
* [Creating a Server](#creating-a-server)
|
||||||
|
* [Core Concepts](#core-concepts)
|
||||||
|
* [MCP Primitives](#mcp-primitives)
|
||||||
|
* [Capabilities](#capabilities)
|
||||||
|
* [Server Capabilities](#server-capabilities)
|
||||||
|
* [Client Capabilities](#client-capabilities)
|
||||||
|
* [Server Features](#server-features)
|
||||||
|
* [Prompts](#prompts)
|
||||||
|
* [Resources](#resources)
|
||||||
|
* [Tools](#tools)
|
||||||
|
* [Completion](#completion)
|
||||||
|
* [Logging](#logging)
|
||||||
|
* [Pagination](#pagination)
|
||||||
|
* [Client Features](#client-features)
|
||||||
|
* [Roots](#roots)
|
||||||
|
* [Sampling](#sampling)
|
||||||
|
* [Transports](#transports)
|
||||||
|
* [STDIO Transport](#stdio-transport)
|
||||||
|
* [Streamable HTTP Transport](#streamable-http-transport)
|
||||||
|
* [SSE Transport](#sse-transport)
|
||||||
|
* [WebSocket Transport](#websocket-transport)
|
||||||
|
* [Connecting your server](#connecting-your-server)
|
||||||
|
* [Examples](#examples)
|
||||||
|
* [Documentation](#documentation)
|
||||||
|
* [Contributing](#contributing)
|
||||||
|
* [License](#license)
|
||||||
|
|
||||||
|
<!--- END -->
|
||||||
|
|
||||||
## Overview
|
## Overview
|
||||||
|
|
||||||
The Model Context Protocol allows applications to provide context for LLMs in a standardized way,
|
The Model Context Protocol allows applications to provide context for LLMs in a standardized way,
|
||||||
separating the concerns of providing context from the actual LLM interaction.
|
separating the concerns of providing context from the actual LLM interaction.
|
||||||
This SDK implements the MCP specification for Kotlin,
|
This Kotlin SDK implements the MCP specification, making it easy to:
|
||||||
enabling you to build applications that can communicate using MCP on the JVM, WebAssembly and iOS.
|
|
||||||
|
|
||||||
- Build MCP clients that can connect to any MCP server
|
- Build MCP **clients** that can connect to any MCP server
|
||||||
- Create MCP servers that expose resources, prompts and tools
|
- Create MCP **servers** that expose resources, prompts, and tools
|
||||||
- Use standard transports like stdio, SSE, and WebSocket
|
- Target **JVM, Native, JS, and Wasm** from a single codebase
|
||||||
- Handle all MCP protocol messages and lifecycle events
|
- Use standard transports like **stdio**, **SSE**, **Streamable HTTP**, and **WebSocket**
|
||||||
|
- Handle MCP protocol messages and lifecycle events with coroutine-friendly APIs
|
||||||
## Samples
|
|
||||||
|
|
||||||
- [kotlin-mcp-server](./samples/kotlin-mcp-server): demonstrates a multiplatform (JVM, Wasm) MCP server setup with various features and transports.
|
|
||||||
- [weather-stdio-server](./samples/weather-stdio-server): shows how to build a Kotlin MCP server providing weather forecast and alerts using STDIO transport.
|
|
||||||
- [kotlin-mcp-client](./samples/kotlin-mcp-client): demonstrates building an interactive Kotlin MCP client that connects to an MCP server via STDIO and integrates with Anthropic’s API.
|
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
|
|
||||||
Add the new repository to your build file:
|
### Artifacts
|
||||||
|
|
||||||
|
- `io.modelcontextprotocol:kotlin-sdk` – umbrella SDK (client + server APIs)
|
||||||
|
- `io.modelcontextprotocol:kotlin-sdk-client` – client-only APIs
|
||||||
|
- `io.modelcontextprotocol:kotlin-sdk-server` – server-only APIs
|
||||||
|
|
||||||
|
### Gradle setup (JVM)
|
||||||
|
|
||||||
|
Add the Maven Central repository and the SDK dependency:
|
||||||
|
|
||||||
```kotlin
|
```kotlin
|
||||||
repositories {
|
repositories {
|
||||||
mavenCentral()
|
mavenCentral()
|
||||||
}
|
}
|
||||||
```
|
|
||||||
|
|
||||||
Add the dependency:
|
|
||||||
|
|
||||||
```kotlin
|
|
||||||
dependencies {
|
dependencies {
|
||||||
// See the badge above for the latest version
|
// See the badge above for the latest version
|
||||||
implementation("io.modelcontextprotocol:kotlin-sdk:$mcpVersion")
|
implementation("io.modelcontextprotocol:kotlin-sdk:$mcpVersion")
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
MCP SDK uses [Ktor](https://ktor.io/), but does not come with a specific engine dependency.
|
|
||||||
You should add [Ktor client](https://ktor.io/docs/client-dependencies.html#engine-dependency)
|
Use _kotlin-sdk-client_ or _kotlin-sdk-server_ if you only need one side of the API:
|
||||||
and/or [Ktor server](https://ktor.io/docs/client-dependencies.html#engine-dependency) dependency
|
|
||||||
to your project yourself, e.g.:
|
|
||||||
```kotlin
|
```kotlin
|
||||||
dependencies {
|
dependencies {
|
||||||
// for client:
|
implementation("io.modelcontextprotocol:kotlin-sdk-client:$mcpVersion")
|
||||||
implementation("io.ktor:ktor-client-cio:$ktorVersion")
|
implementation("io.modelcontextprotocol:kotlin-sdk-server:$mcpVersion")
|
||||||
// for server:
|
|
||||||
implementation("io.ktor:ktor-server-netty:$ktorVersion")
|
|
||||||
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
## Quick Start
|
### Multiplatform
|
||||||
|
|
||||||
|
In a Kotlin Multiplatform project you can add the SDK to commonMain:
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
commonMain {
|
||||||
|
dependencies {
|
||||||
|
// Works as a common dependency as well as the platform one
|
||||||
|
implementation("io.modelcontextprotocol:kotlin-sdk:$mcpVersion")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Ktor dependencies
|
||||||
|
|
||||||
|
The Kotlin MCP SDK uses [Ktor](https://ktor.io/), but it does not add Ktor engine dependencies transitively.
|
||||||
|
You need to declare
|
||||||
|
Ktor [client](https://ktor.io/docs/client-dependencies.html#engine-dependency)/[server](https://ktor.io/docs/server-dependencies.html)
|
||||||
|
dependencies yourself (or reuse the ones already used in your project),
|
||||||
|
for example:
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
dependencies {
|
||||||
|
// MCP client with Ktor
|
||||||
|
implementation("io.ktor:ktor-client-cio:$ktorVersion")
|
||||||
|
implementation("io.modelcontextprotocol:kotlin-sdk-client:$mcpVersion")
|
||||||
|
|
||||||
|
// MCP server with Ktor
|
||||||
|
implementation("io.ktor:ktor-server-netty:$ktorVersion")
|
||||||
|
implementation("io.modelcontextprotocol:kotlin-sdk-server:$mcpVersion")
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Quickstart
|
||||||
|
|
||||||
|
Let's create a simple MCP client and server to demonstrate the basic usage of the Kotlin SDK.
|
||||||
|
|
||||||
|
<!--- CLEAR -->
|
||||||
|
|
||||||
### Creating a Client
|
### Creating a Client
|
||||||
|
|
||||||
```kotlin
|
Create an MCP client that connects to a server via Streamable HTTP transport and lists available tools:
|
||||||
import io.modelcontextprotocol.kotlin.sdk.client.Client
|
|
||||||
import io.modelcontextprotocol.kotlin.sdk.client.StdioClientTransport
|
|
||||||
import io.modelcontextprotocol.kotlin.sdk.Implementation
|
|
||||||
|
|
||||||
val client = Client(
|
```kotlin
|
||||||
|
import io.ktor.client.HttpClient
|
||||||
|
import io.ktor.client.plugins.sse.SSE
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.client.Client
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.client.StreamableHttpClientTransport
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.Implementation
|
||||||
|
import kotlinx.coroutines.runBlocking
|
||||||
|
|
||||||
|
fun main(args: Array<String>) = runBlocking {
|
||||||
|
val url = args.firstOrNull() ?: "http://localhost:3000/mcp"
|
||||||
|
|
||||||
|
val httpClient = HttpClient { install(SSE) }
|
||||||
|
|
||||||
|
val client = Client(
|
||||||
clientInfo = Implementation(
|
clientInfo = Implementation(
|
||||||
name = "example-client",
|
name = "example-client",
|
||||||
version = "1.0.0"
|
version = "1.0.0"
|
||||||
)
|
)
|
||||||
)
|
)
|
||||||
|
|
||||||
val transport = StdioClientTransport(
|
val transport = StreamableHttpClientTransport(
|
||||||
inputStream = processInputStream,
|
client = httpClient,
|
||||||
outputStream = processOutputStream
|
url = url
|
||||||
)
|
)
|
||||||
|
|
||||||
// Connect to server
|
// Connect to server
|
||||||
client.connect(transport)
|
client.connect(transport)
|
||||||
|
|
||||||
// List available resources
|
// List available tools
|
||||||
val resources = client.listResources()
|
val tools = client.listTools().tools
|
||||||
|
|
||||||
// Read a specific resource
|
println(tools)
|
||||||
val resourceContent = client.readResource(
|
}
|
||||||
ReadResourceRequest(uri = "file:///example.txt")
|
|
||||||
)
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
<!--- KNIT example-quickstart-client-01.kt -->
|
||||||
|
|
||||||
### Creating a Server
|
### Creating a Server
|
||||||
|
|
||||||
|
Create an MCP server that exposes a simple tool and runs on an embedded Ktor server with SSE transport:
|
||||||
|
|
||||||
```kotlin
|
```kotlin
|
||||||
|
import io.ktor.server.cio.CIO
|
||||||
|
import io.ktor.server.engine.embeddedServer
|
||||||
import io.modelcontextprotocol.kotlin.sdk.server.Server
|
import io.modelcontextprotocol.kotlin.sdk.server.Server
|
||||||
import io.modelcontextprotocol.kotlin.sdk.server.ServerOptions
|
import io.modelcontextprotocol.kotlin.sdk.server.ServerOptions
|
||||||
import io.modelcontextprotocol.kotlin.sdk.server.StdioServerTransport
|
import io.modelcontextprotocol.kotlin.sdk.server.mcp
|
||||||
import io.modelcontextprotocol.kotlin.sdk.ServerCapabilities
|
import io.modelcontextprotocol.kotlin.sdk.types.CallToolResult
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.Implementation
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.ServerCapabilities
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.TextContent
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.ToolSchema
|
||||||
|
import kotlinx.serialization.json.buildJsonObject
|
||||||
|
import kotlinx.serialization.json.put
|
||||||
|
|
||||||
|
|
||||||
|
fun main(args: Array<String>) {
|
||||||
|
val port = args.firstOrNull()?.toIntOrNull() ?: 3000
|
||||||
|
val mcpServer = Server(
|
||||||
|
serverInfo = Implementation(
|
||||||
|
name = "example-server",
|
||||||
|
version = "1.0.0"
|
||||||
|
),
|
||||||
|
options = ServerOptions(
|
||||||
|
capabilities = ServerCapabilities(
|
||||||
|
tools = ServerCapabilities.Tools(listChanged = true),
|
||||||
|
),
|
||||||
|
)
|
||||||
|
)
|
||||||
|
|
||||||
|
mcpServer.addTool(
|
||||||
|
name = "example-tool",
|
||||||
|
description = "An example tool",
|
||||||
|
inputSchema = ToolSchema(
|
||||||
|
properties = buildJsonObject {
|
||||||
|
put("input", buildJsonObject { put("type", "string") })
|
||||||
|
}
|
||||||
|
)
|
||||||
|
) { request ->
|
||||||
|
CallToolResult(content = listOf(TextContent("Hello, world!")))
|
||||||
|
}
|
||||||
|
|
||||||
|
embeddedServer(CIO, host = "127.0.0.1", port = port) {
|
||||||
|
mcp {
|
||||||
|
mcpServer
|
||||||
|
}
|
||||||
|
}.start(wait = true)
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
<!--- KNIT example-quickstart-server-01.kt -->
|
||||||
|
|
||||||
|
You can run the server and then connect to it using the client or test with the MCP Inspector:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx -y @modelcontextprotocol/inspector
|
||||||
|
```
|
||||||
|
|
||||||
|
In the inspector UI, connect to `http://localhost:3000`.
|
||||||
|
|
||||||
|
## Core Concepts
|
||||||
|
|
||||||
|
### MCP Primitives
|
||||||
|
|
||||||
|
The MCP protocol defines core primitives that enable communication between servers and clients:
|
||||||
|
|
||||||
|
| Primitive | Server Role | Client Role | Description |
|
||||||
|
|---------------|---------------------------------------------------|----------------------------------------|---------------------------------------------------|
|
||||||
|
| **Prompts** | Provides prompt templates with optional arguments | Requests and uses prompts | Interactive templates for LLM interactions |
|
||||||
|
| **Resources** | Exposes data sources (files, API responses, etc.) | Reads and subscribes to resources | Contextual data for augmenting LLM context |
|
||||||
|
| **Tools** | Defines executable functions | Calls tools to perform actions | Functions the LLM can invoke to take actions |
|
||||||
|
| **Sampling** | Requests LLM completions from client | Executes LLM calls and returns results | Server-initiated LLM requests (reverse direction) |
|
||||||
|
|
||||||
|
### Capabilities
|
||||||
|
|
||||||
|
Capabilities define what features a server or client supports. They are declared during initialization and determine
|
||||||
|
what operations are available.
|
||||||
|
|
||||||
|
#### Server Capabilities
|
||||||
|
|
||||||
|
Servers declare their capabilities to inform clients what features they provide:
|
||||||
|
|
||||||
|
| Capability | Feature Flags | Description |
|
||||||
|
|----------------|-------------------------------|------------------------------------------------------------|
|
||||||
|
| `prompts` | `listChanged` | Prompt template management and notifications |
|
||||||
|
| `resources` | `subscribe`<br/>`listChanged` | Resource exposure, subscriptions, and update notifications |
|
||||||
|
| `tools` | `listChanged` | Tool discovery, execution, and list change notifications |
|
||||||
|
| `logging` | - | Server logging to client console |
|
||||||
|
| `completions` | - | Argument autocompletion suggestions |
|
||||||
|
| `experimental` | Custom properties | Non-standard experimental features |
|
||||||
|
|
||||||
|
#### Client Capabilities
|
||||||
|
|
||||||
|
Clients declare their capabilities to inform servers what features they support:
|
||||||
|
|
||||||
|
| Capability | Feature Flags | Description |
|
||||||
|
|----------------|-------------------|-------------------------------------------------------------|
|
||||||
|
| `sampling` | - | Client can sample from an LLM (execute model requests) |
|
||||||
|
| `roots` | `listChanged` | Client exposes root directories and can notify of changes |
|
||||||
|
| `elicitation` | - | Client can display schema/form dialogs for structured input |
|
||||||
|
| `experimental` | Custom properties | Non-standard experimental features |
|
||||||
|
|
||||||
|
### Server Features
|
||||||
|
|
||||||
|
The `Server` API lets you wire prompts, resources, and tools with only a few lines of Kotlin. Each feature is registered
|
||||||
|
up front and then resolved lazily when a client asks for it, so your handlers stay small and suspendable.
|
||||||
|
|
||||||
|
#### Prompts
|
||||||
|
|
||||||
|
Prompts are user-controlled templates that clients discover via `prompts/list` and fetch with `prompts/get` when a user
|
||||||
|
chooses one (think slash commands or saved flows). They’re best for repeatable, structured starters rather than ad-hoc
|
||||||
|
model calls.
|
||||||
|
|
||||||
|
<!--- INCLUDE
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.server.Server
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.server.ServerOptions
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.GetPromptResult
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.Implementation
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.PromptArgument
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.PromptMessage
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.Role
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.ServerCapabilities
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.TextContent
|
||||||
|
|
||||||
|
fun main() {
|
||||||
|
-->
|
||||||
|
|
||||||
|
```kotlin
|
||||||
val server = Server(
|
val server = Server(
|
||||||
serverInfo = Implementation(
|
serverInfo = Implementation(
|
||||||
name = "example-server",
|
name = "example-server",
|
||||||
|
|
@ -110,97 +315,498 @@ val server = Server(
|
||||||
),
|
),
|
||||||
options = ServerOptions(
|
options = ServerOptions(
|
||||||
capabilities = ServerCapabilities(
|
capabilities = ServerCapabilities(
|
||||||
resources = ServerCapabilities.Resources(
|
prompts = ServerCapabilities.Prompts(listChanged = true),
|
||||||
subscribe = true,
|
),
|
||||||
listChanged = true
|
|
||||||
)
|
)
|
||||||
)
|
)
|
||||||
)
|
|
||||||
){
|
server.addPrompt(
|
||||||
"This server provides example resources and demonstrates MCP capabilities."
|
name = "code-review",
|
||||||
}
|
description = "Ask the model to review a diff",
|
||||||
|
arguments = listOf(
|
||||||
|
PromptArgument(name = "diff", description = "Unified diff", required = true),
|
||||||
|
),
|
||||||
|
) { request ->
|
||||||
|
GetPromptResult(
|
||||||
|
description = "Quick code review helper",
|
||||||
|
messages = listOf(
|
||||||
|
PromptMessage(
|
||||||
|
role = Role.User,
|
||||||
|
content = TextContent(text = "Review this change:\n${request.arguments?.get("diff")}"),
|
||||||
|
),
|
||||||
|
),
|
||||||
|
)
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
<!--- SUFFIX
|
||||||
|
}
|
||||||
|
-->
|
||||||
|
|
||||||
|
<!--- KNIT example-server-prompts-01.kt -->
|
||||||
|
|
||||||
|
Use prompts for anything that deserves a template: bug triage questions, onboarding checklists, or saved searches. Set
|
||||||
|
`listChanged = true` only if your prompt catalog can change at runtime and your server will emit
|
||||||
|
`notifications/prompts/list_changed` when it does.
|
||||||
|
|
||||||
|
#### Resources
|
||||||
|
|
||||||
|
Resources are application-driven context that clients discover via `resources/list` or `resources/templates/list`, then
|
||||||
|
fetch with `resources/read`. Register each one with a stable URI and return a `ReadResourceResult` when asked—contents
|
||||||
|
can be text or binary blobs.
|
||||||
|
|
||||||
|
<!--- INCLUDE
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.server.Server
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.server.ServerOptions
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.Implementation
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.ReadResourceResult
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.ServerCapabilities
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.TextResourceContents
|
||||||
|
|
||||||
|
fun main() {
|
||||||
|
-->
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
val server = Server(
|
||||||
|
serverInfo = Implementation(
|
||||||
|
name = "example-server",
|
||||||
|
version = "1.0.0"
|
||||||
|
),
|
||||||
|
options = ServerOptions(
|
||||||
|
capabilities = ServerCapabilities(
|
||||||
|
resources = ServerCapabilities.Resources(subscribe = true, listChanged = true),
|
||||||
|
),
|
||||||
|
)
|
||||||
|
)
|
||||||
|
|
||||||
// Add a resource
|
|
||||||
server.addResource(
|
server.addResource(
|
||||||
uri = "file:///example.txt",
|
uri = "note://release/latest",
|
||||||
name = "Example Resource",
|
name = "Release notes",
|
||||||
description = "An example text file",
|
description = "Last deployment summary",
|
||||||
mimeType = "text/plain"
|
mimeType = "text/markdown",
|
||||||
) { request ->
|
) { request ->
|
||||||
ReadResourceResult(
|
ReadResourceResult(
|
||||||
contents = listOf(
|
contents = listOf(
|
||||||
TextResourceContents(
|
TextResourceContents(
|
||||||
text = "This is the content of the example resource.",
|
text = "Ship 42 reached production successfully.",
|
||||||
uri = request.uri,
|
uri = request.uri,
|
||||||
mimeType = "text/plain"
|
mimeType = "text/markdown",
|
||||||
)
|
),
|
||||||
)
|
),
|
||||||
)
|
)
|
||||||
}
|
}
|
||||||
|
|
||||||
// Start server with stdio transport
|
|
||||||
val transport = StdioServerTransport()
|
|
||||||
server.connect(transport)
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Using SSE Transport
|
<!--- SUFFIX
|
||||||
|
}
|
||||||
|
-->
|
||||||
|
|
||||||
|
<!--- KNIT example-server-resources-01.kt -->
|
||||||
|
|
||||||
|
Resources can be static text, generated JSON, or blobs—anything the client can surface to the user or inject into the
|
||||||
|
model context. Set `subscribe = true` if you emit `notifications/resources/updated` for changes to specific URIs, and
|
||||||
|
`listChanged = true` if you’ll send `notifications/resources/list_changed` when the catalog itself changes.
|
||||||
|
|
||||||
|
#### Tools
|
||||||
|
|
||||||
|
Tools are model-controlled capabilities the client exposes to the model. Clients discover them via `tools/list`, invoke
|
||||||
|
them with `tools/call`, and your handlers receive JSON arguments, can emit streaming logs or progress, and return a
|
||||||
|
`CallToolResult`. Keep a human in the loop for sensitive operations.
|
||||||
|
|
||||||
|
<!--- INCLUDE
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.server.Server
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.server.ServerOptions
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.CallToolResult
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.Implementation
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.ServerCapabilities
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.TextContent
|
||||||
|
import kotlinx.serialization.json.jsonPrimitive
|
||||||
|
|
||||||
|
fun main() {
|
||||||
|
-->
|
||||||
|
|
||||||
Directly in Ktor's `Application`:
|
|
||||||
```kotlin
|
```kotlin
|
||||||
import io.ktor.server.application.*
|
val server = Server(
|
||||||
import io.modelcontextprotocol.kotlin.sdk.server.mcp
|
|
||||||
|
|
||||||
fun Application.module() {
|
|
||||||
mcp {
|
|
||||||
Server(
|
|
||||||
serverInfo = Implementation(
|
serverInfo = Implementation(
|
||||||
name = "example-sse-server",
|
name = "example-server",
|
||||||
version = "1.0.0"
|
version = "1.0.0"
|
||||||
),
|
),
|
||||||
options = ServerOptions(
|
options = ServerOptions(
|
||||||
capabilities = ServerCapabilities(
|
capabilities = ServerCapabilities(
|
||||||
prompts = ServerCapabilities.Prompts(listChanged = null),
|
tools = ServerCapabilities.Tools(listChanged = true),
|
||||||
resources = ServerCapabilities.Resources(subscribe = null, listChanged = null)
|
|
||||||
)
|
|
||||||
),
|
),
|
||||||
) {
|
)
|
||||||
"This SSE server provides prompts and resources via Server-Sent Events."
|
)
|
||||||
}
|
|
||||||
}
|
server.addTool(
|
||||||
|
name = "echo",
|
||||||
|
description = "Return whatever the user sent back to them",
|
||||||
|
) { request ->
|
||||||
|
val text = request.arguments?.get("text")?.jsonPrimitive?.content ?: "(empty)"
|
||||||
|
CallToolResult(content = listOf(TextContent(text = "Echo: $text")))
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
Inside a custom Ktor's `Route`:
|
<!--- SUFFIX
|
||||||
|
}
|
||||||
|
-->
|
||||||
|
|
||||||
|
<!--- KNIT example-server-tools-01.kt -->
|
||||||
|
|
||||||
|
Register as many tools as you need—long-running jobs can report progress via the request context, and tools can also
|
||||||
|
trigger sampling (see below) when they need the client’s LLM. Set `listChanged = true` only if your tool catalog can
|
||||||
|
change at runtime and your server will emit `notifications/tools/list_changed` when it does.
|
||||||
|
|
||||||
|
#### Completion
|
||||||
|
|
||||||
|
Completion provides argument suggestions for prompts or resource templates. Declare the `completions` capability and
|
||||||
|
handle `completion/complete` requests to return up to 100 ranked values (include `total`/`hasMore` if you paginate).
|
||||||
|
|
||||||
|
<!--- INCLUDE
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.server.Server
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.server.ServerOptions
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.server.StdioServerTransport
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.CompleteRequest
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.CompleteResult
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.Implementation
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.Method
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.ServerCapabilities
|
||||||
|
import kotlinx.io.asSink
|
||||||
|
import kotlinx.io.asSource
|
||||||
|
import kotlinx.io.buffered
|
||||||
|
|
||||||
|
suspend fun main() {
|
||||||
|
-->
|
||||||
|
|
||||||
```kotlin
|
```kotlin
|
||||||
import io.ktor.server.application.*
|
val server = Server(
|
||||||
import io.ktor.server.sse.SSE
|
|
||||||
import io.modelcontextprotocol.kotlin.sdk.server.mcp
|
|
||||||
|
|
||||||
fun Application.module() {
|
|
||||||
install(SSE)
|
|
||||||
|
|
||||||
routing {
|
|
||||||
route("myRoute") {
|
|
||||||
mcp {
|
|
||||||
Server(
|
|
||||||
serverInfo = Implementation(
|
serverInfo = Implementation(
|
||||||
name = "example-sse-server",
|
name = "example-server",
|
||||||
version = "1.0.0"
|
version = "1.0.0"
|
||||||
),
|
),
|
||||||
options = ServerOptions(
|
options = ServerOptions(
|
||||||
capabilities = ServerCapabilities(
|
capabilities = ServerCapabilities(
|
||||||
prompts = ServerCapabilities.Prompts(listChanged = null),
|
completions = ServerCapabilities.Completions,
|
||||||
resources = ServerCapabilities.Resources(subscribe = null, listChanged = null)
|
|
||||||
)
|
|
||||||
),
|
),
|
||||||
) {
|
)
|
||||||
"Connect via SSE to interact with this MCP server."
|
)
|
||||||
}
|
|
||||||
}
|
val session = server.createSession(
|
||||||
}
|
StdioServerTransport(
|
||||||
}
|
inputStream = System.`in`.asSource().buffered(),
|
||||||
|
outputStream = System.out.asSink().buffered()
|
||||||
|
)
|
||||||
|
)
|
||||||
|
|
||||||
|
session.setRequestHandler<CompleteRequest>(Method.Defined.CompletionComplete) { request, _ ->
|
||||||
|
val options = listOf("kotlin", "compose", "coroutine")
|
||||||
|
val matches = options.filter { it.startsWith(request.argument.value.lowercase()) }
|
||||||
|
|
||||||
|
CompleteResult(
|
||||||
|
completion = CompleteResult.Completion(
|
||||||
|
values = matches.take(3),
|
||||||
|
total = matches.size,
|
||||||
|
hasMore = matches.size > 3,
|
||||||
|
),
|
||||||
|
)
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
<!--- SUFFIX
|
||||||
|
}
|
||||||
|
-->
|
||||||
|
|
||||||
|
<!--- KNIT example-server-util-completions-01.kt -->
|
||||||
|
|
||||||
|
Use `context.arguments` to refine suggestions for dependent fields (e.g., framework list filtered by chosen language).
|
||||||
|
|
||||||
|
#### Logging
|
||||||
|
|
||||||
|
Logging lets the server stream structured log notifications to the client using RFC 5424 levels (`debug` → `emergency`).
|
||||||
|
Declare the `logging` capability; clients can raise the minimum level with `logging/setLevel`, and the server emits
|
||||||
|
`notifications/message` with severity, optional logger name, and JSON data.
|
||||||
|
|
||||||
|
<!--- INCLUDE
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.server.Server
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.server.ServerOptions
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.server.StdioServerTransport
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.Implementation
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.LoggingLevel
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.LoggingMessageNotification
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.LoggingMessageNotificationParams
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.ServerCapabilities
|
||||||
|
import kotlinx.io.asSink
|
||||||
|
import kotlinx.io.asSource
|
||||||
|
import kotlinx.io.buffered
|
||||||
|
import kotlinx.serialization.json.buildJsonObject
|
||||||
|
import kotlinx.serialization.json.put
|
||||||
|
|
||||||
|
suspend fun main() {
|
||||||
|
-->
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
val server = Server(
|
||||||
|
serverInfo = Implementation("example-server", "1.0.0"),
|
||||||
|
options = ServerOptions(
|
||||||
|
capabilities = ServerCapabilities(
|
||||||
|
logging = ServerCapabilities.Logging,
|
||||||
|
),
|
||||||
|
)
|
||||||
|
)
|
||||||
|
|
||||||
|
val session = server.createSession(
|
||||||
|
StdioServerTransport(
|
||||||
|
inputStream = System.`in`.asSource().buffered(),
|
||||||
|
outputStream = System.out.asSink().buffered()
|
||||||
|
)
|
||||||
|
)
|
||||||
|
|
||||||
|
session.sendLoggingMessage(
|
||||||
|
LoggingMessageNotification(
|
||||||
|
LoggingMessageNotificationParams(
|
||||||
|
level = LoggingLevel.Info,
|
||||||
|
logger = "startup",
|
||||||
|
data = buildJsonObject { put("message", "Server started") },
|
||||||
|
),
|
||||||
|
),
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
<!--- SUFFIX
|
||||||
|
}
|
||||||
|
-->
|
||||||
|
|
||||||
|
<!--- KNIT example-server-util-logging-01.kt -->
|
||||||
|
|
||||||
|
Keep logs free of sensitive data, and expect clients to surface them in their own UI.
|
||||||
|
|
||||||
|
#### Pagination
|
||||||
|
|
||||||
|
List operations return paginated results with an opaque `nextCursor`, clients echo that cursor to fetch the next page.
|
||||||
|
Supported list calls: `resources/list`, `resources/templates/list`, `prompts/list`, and `tools/list`.
|
||||||
|
Treat cursors as opaque—don’t parse or persist them across sessions.
|
||||||
|
|
||||||
|
<!--- INCLUDE
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.server.Server
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.server.ServerOptions
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.server.StdioServerTransport
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.Implementation
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.ListResourcesRequest
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.ListResourcesResult
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.Method
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.Resource
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.ServerCapabilities
|
||||||
|
import kotlinx.io.asSink
|
||||||
|
import kotlinx.io.asSource
|
||||||
|
import kotlinx.io.buffered
|
||||||
|
|
||||||
|
suspend fun main() {
|
||||||
|
-->
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
val server = Server(
|
||||||
|
serverInfo = Implementation("example-server", "1.0.0"),
|
||||||
|
options = ServerOptions(
|
||||||
|
capabilities = ServerCapabilities(
|
||||||
|
resources = ServerCapabilities.Resources(),
|
||||||
|
),
|
||||||
|
)
|
||||||
|
)
|
||||||
|
|
||||||
|
val session = server.createSession(
|
||||||
|
StdioServerTransport(
|
||||||
|
inputStream = System.`in`.asSource().buffered(),
|
||||||
|
outputStream = System.out.asSink().buffered()
|
||||||
|
)
|
||||||
|
)
|
||||||
|
|
||||||
|
val resources = listOf(
|
||||||
|
Resource(uri = "note://1", name = "Note 1", description = "First"),
|
||||||
|
Resource(uri = "note://2", name = "Note 2", description = "Second"),
|
||||||
|
Resource(uri = "note://3", name = "Note 3", description = "Third"),
|
||||||
|
)
|
||||||
|
val pageSize = 2
|
||||||
|
|
||||||
|
session.setRequestHandler<ListResourcesRequest>(Method.Defined.ResourcesList) { request, _ ->
|
||||||
|
val start = request.params?.cursor?.toIntOrNull() ?: 0
|
||||||
|
val page = resources.drop(start).take(pageSize)
|
||||||
|
val next = if (start + page.size < resources.size) (start + page.size).toString() else null
|
||||||
|
|
||||||
|
ListResourcesResult(
|
||||||
|
resources = page,
|
||||||
|
nextCursor = next,
|
||||||
|
)
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
<!--- SUFFIX
|
||||||
|
}
|
||||||
|
-->
|
||||||
|
|
||||||
|
<!--- KNIT example-server-util-pagination-01.kt -->
|
||||||
|
|
||||||
|
Include `nextCursor` only when more items remain an absent cursor ends pagination.
|
||||||
|
|
||||||
|
### Client Features
|
||||||
|
|
||||||
|
Clients advertise their capabilities (roots, sampling, elicitation, etc.) during initialization. After that they can
|
||||||
|
serve requests from the server while still initiating calls such as `listTools` or `callTool`.
|
||||||
|
|
||||||
|
#### Roots
|
||||||
|
|
||||||
|
Roots let the client declare where the server is allowed to operate. Declare the `roots` capability, respond to
|
||||||
|
`roots/list`, and emit `notifications/roots/list_changed` if you set `listChanged = true`. URIs **must** be `file://`
|
||||||
|
paths.
|
||||||
|
|
||||||
|
<!--- INCLUDE
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.client.Client
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.client.ClientOptions
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.ClientCapabilities
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.Implementation
|
||||||
|
|
||||||
|
suspend fun main() {
|
||||||
|
-->
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
val client = Client(
|
||||||
|
clientInfo = Implementation("demo-client", "1.0.0"),
|
||||||
|
options = ClientOptions(
|
||||||
|
capabilities = ClientCapabilities(roots = ClientCapabilities.Roots(listChanged = true)),
|
||||||
|
),
|
||||||
|
)
|
||||||
|
|
||||||
|
client.addRoot(
|
||||||
|
uri = "file:///Users/demo/projects",
|
||||||
|
name = "Projects",
|
||||||
|
)
|
||||||
|
client.sendRootsListChanged()
|
||||||
|
```
|
||||||
|
|
||||||
|
<!--- SUFFIX
|
||||||
|
}
|
||||||
|
-->
|
||||||
|
|
||||||
|
<!--- KNIT example-client-roots-01.kt -->
|
||||||
|
|
||||||
|
Call `addRoot`/`removeRoot` whenever your file system view changes, and use `sendRootsListChanged()` to notify the
|
||||||
|
server. Keep root lists user-controlled and revoke entries that are no longer authorized.
|
||||||
|
|
||||||
|
#### Sampling
|
||||||
|
|
||||||
|
Sampling lets the server ask the client to call its preferred LLM. Declare the `sampling` capability (and
|
||||||
|
`sampling.tools` if you allow tool-enabled sampling), and handle `sampling/createMessage`. Keep a human in the loop for
|
||||||
|
approvals.
|
||||||
|
|
||||||
|
<!--- INCLUDE
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.client.Client
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.client.ClientOptions
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.ClientCapabilities
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.CreateMessageRequest
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.CreateMessageResult
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.Implementation
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.Method
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.Role
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.TextContent
|
||||||
|
import kotlinx.serialization.json.buildJsonObject
|
||||||
|
import kotlinx.serialization.json.putJsonObject
|
||||||
|
|
||||||
|
fun main() {
|
||||||
|
-->
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
val client = Client(
|
||||||
|
clientInfo = Implementation("demo-client", "1.0.0"),
|
||||||
|
options = ClientOptions(
|
||||||
|
capabilities = ClientCapabilities(
|
||||||
|
sampling = buildJsonObject { putJsonObject("tools") { } }, // drop tools if you don't support tool use
|
||||||
|
),
|
||||||
|
),
|
||||||
|
)
|
||||||
|
|
||||||
|
client.setRequestHandler<CreateMessageRequest>(Method.Defined.SamplingCreateMessage) { request, _ ->
|
||||||
|
val content = request.messages.lastOrNull()?.content
|
||||||
|
val prompt = if (content is TextContent) content.text else "your topic"
|
||||||
|
CreateMessageResult(
|
||||||
|
model = "gpt-4o-mini",
|
||||||
|
role = Role.Assistant,
|
||||||
|
content = TextContent(text = "Here is a short note about $prompt"),
|
||||||
|
)
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
<!--- SUFFIX
|
||||||
|
}
|
||||||
|
-->
|
||||||
|
|
||||||
|
<!--- KNIT example-client-sampling-01.kt -->
|
||||||
|
|
||||||
|
Inside the handler you can pick any model/provider, require approvals, or reject the request. If you don’t support tool
|
||||||
|
use, omit `sampling.tools` from capabilities.
|
||||||
|
|
||||||
|
[//]: # (TODO: add elicitation section)
|
||||||
|
|
||||||
|
[//]: # (#### Elicitation)
|
||||||
|
|
||||||
|
## Transports
|
||||||
|
|
||||||
|
All transports share the same API surface, so you can change deployment style without touching business logic. Pick the
|
||||||
|
transport that best matches where the server runs.
|
||||||
|
|
||||||
|
### STDIO Transport
|
||||||
|
|
||||||
|
`StdioClientTransport` and `StdioServerTransport` tunnel MCP messages over stdin/stdout—perfect for editor plugins or
|
||||||
|
CLI tooling that spawns a helper process. No networking setup is required.
|
||||||
|
|
||||||
|
### Streamable HTTP Transport
|
||||||
|
|
||||||
|
`StreamableHttpClientTransport` and the Ktor `streamableHttpApp()` helpers expose MCP over a single HTTP endpoint with
|
||||||
|
optional JSON-only or SSE streaming responses. This is the recommended choice for remote deployments and integrates
|
||||||
|
nicely with proxies or service meshes.
|
||||||
|
|
||||||
|
### SSE Transport
|
||||||
|
|
||||||
|
Server-Sent Events remain available for backwards compatibility with older MCP clients. Use `SseServerTransport` or the
|
||||||
|
SSE Ktor plugin when you need drop-in compatibility, but prefer Streamable HTTP for new projects.
|
||||||
|
|
||||||
|
### WebSocket Transport
|
||||||
|
|
||||||
|
`WebSocketClientTransport` plus the matching server utilities provide full-duplex, low-latency connections—useful when
|
||||||
|
you expect lots of notifications or long-running sessions behind a reverse proxy that already terminates WebSockets.
|
||||||
|
|
||||||
|
## Connecting your server
|
||||||
|
|
||||||
|
1. Start a sample HTTP server on port 3000:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./gradlew :samples:kotlin-mcp-server:run
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Connect with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) or Claude Desktop/Code:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx -y @modelcontextprotocol/inspector --connect http://localhost:3000
|
||||||
|
# or
|
||||||
|
claude mcp add --transport http kotlin-mcp http://localhost:3000
|
||||||
|
```
|
||||||
|
|
||||||
|
3. In the Inspector, confirm prompts, tools, resources, completions, and logs show up. Iterate locally until you’re
|
||||||
|
ready to host the server wherever you prefer.
|
||||||
|
|
||||||
|
## Examples
|
||||||
|
|
||||||
|
| Scenario | Description | Example |
|
||||||
|
|--------------------------|-----------------------------------------------------------------|--------------------------------------------------------------------------|
|
||||||
|
| Streamable HTTP server | Full MCP server with prompts, resources, tools, completions | [samples/kotlin-mcp-server](./samples/kotlin-mcp-server) |
|
||||||
|
| STDIO weather server | Minimal STDIO transport server exposing weather info and alerts | [samples/weather-stdio-server](./samples/weather-stdio-server) |
|
||||||
|
| Interactive STDIO client | MCP client that connects over STDIO and pipes requests to LLMs | [samples/kotlin-mcp-client](./samples/kotlin-mcp-client) |
|
||||||
|
| Streamable HTTP client | MCP client demo in a runnable notebook | [samples/notebooks/McpClient.ipynb](./samples/notebooks/McpClient.ipynb) |
|
||||||
|
|
||||||
|
## Documentation
|
||||||
|
|
||||||
|
- [API Reference](https://modelcontextprotocol.github.io/kotlin-sdk/)
|
||||||
|
- [Model Context Protocol documentation](https://modelcontextprotocol.io)
|
||||||
|
- [MCP specification](https://modelcontextprotocol.io/specification/latest)
|
||||||
|
|
||||||
## Contributing
|
## Contributing
|
||||||
|
|
||||||
Please see the [contribution guide](CONTRIBUTING.md) and the [Code of conduct](CODE_OF_CONDUCT.md) before contributing.
|
Please see the [contribution guide](CONTRIBUTING.md) and the [Code of conduct](CODE_OF_CONDUCT.md) before contributing.
|
||||||
|
|
|
||||||
1
docs/.gitignore
vendored
Normal file
1
docs/.gitignore
vendored
Normal file
|
|
@ -0,0 +1 @@
|
||||||
|
src/
|
||||||
35
docs/build.gradle.kts
Normal file
35
docs/build.gradle.kts
Normal file
|
|
@ -0,0 +1,35 @@
|
||||||
|
plugins {
|
||||||
|
kotlin("jvm")
|
||||||
|
alias(libs.plugins.knit)
|
||||||
|
}
|
||||||
|
|
||||||
|
dependencies {
|
||||||
|
implementation(project(":kotlin-sdk"))
|
||||||
|
implementation(libs.ktor.server.cio)
|
||||||
|
}
|
||||||
|
|
||||||
|
tasks.matching {
|
||||||
|
it.name == "ktlintMainSourceSetCheck" || it.name == "ktlintMainSourceSetFormat"
|
||||||
|
}.configureEach {
|
||||||
|
enabled = false
|
||||||
|
}
|
||||||
|
|
||||||
|
knit {
|
||||||
|
rootDir = project.rootDir
|
||||||
|
files = files(project.rootDir.resolve("README.md"))
|
||||||
|
defaultLineSeparator = "\n"
|
||||||
|
siteRoot = "" // Disable site root validation
|
||||||
|
}
|
||||||
|
|
||||||
|
// Only run knitCheck when explicitly requested, not as part of build/check
|
||||||
|
tasks.named("knitCheck") {
|
||||||
|
onlyIf {
|
||||||
|
gradle.startParameter.taskNames.any {
|
||||||
|
it.contains("knitCheck") || it.contains("knit")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
tasks.clean {
|
||||||
|
delete("src")
|
||||||
|
}
|
||||||
|
|
@ -1,21 +1,17 @@
|
||||||
# MCP Kotlin SDK
|
# MCP Kotlin SDK
|
||||||
|
|
||||||
Kotlin SDK for the Model Context Protocol (MCP).
|
Kotlin Multiplatform implementation of the Model Context Protocol (MCP). The SDK focuses on clear, explicit APIs,
|
||||||
This is a Kotlin Multiplatform library that helps you build MCP clients and servers that speak the same protocol and
|
small building blocks, and first-class coroutine support so clients and servers share the same well-typed messages and
|
||||||
share the same types.
|
transports.
|
||||||
The SDK focuses on clarity, small building blocks, and first‑class coroutine support.
|
|
||||||
|
|
||||||
Use the umbrella `kotlin-sdk` artifact when you want a single dependency that brings the core types plus both client and
|
Use the umbrella `kotlin-sdk` artifact to bring in everything at once, or depend on the focused modules directly:
|
||||||
server toolkits. If you only need one side, depend on `kotlin-sdk-client` or `kotlin-sdk-server` directly.
|
|
||||||
|
|
||||||
Gradle (Kotlin DSL):
|
|
||||||
|
|
||||||
```kotlin
|
```kotlin
|
||||||
dependencies {
|
dependencies {
|
||||||
// Convenience bundle with everything you need to start
|
// All-in-one bundle
|
||||||
implementation("io.modelcontextprotocol:kotlin-sdk:<version>")
|
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-client:<version>")
|
||||||
implementation("io.modelcontextprotocol:kotlin-sdk-server:<version>")
|
implementation("io.modelcontextprotocol:kotlin-sdk-server:<version>")
|
||||||
}
|
}
|
||||||
|
|
@ -25,79 +21,74 @@ dependencies {
|
||||||
|
|
||||||
## Module kotlin-sdk-core
|
## Module kotlin-sdk-core
|
||||||
|
|
||||||
Foundational, platform‑agnostic pieces:
|
Foundation shared by both sides:
|
||||||
|
|
||||||
- Protocol data model and JSON serialization (kotlinx.serialization)
|
- Protocol data model for MCP requests, results, notifications, capabilities, and content types.
|
||||||
- Request/response and notification types used by both sides of MCP
|
- `McpJson` (kotlinx.serialization) with MCP-friendly defaults plus helpers for converting native values to JSON.
|
||||||
- Coroutine‑friendly protocol engine and utilities
|
- Transport abstractions (`Transport`, `AbstractTransport`, `WebSocketMcpTransport`) and streaming `ReadBuffer`.
|
||||||
- Transport abstractions shared by client and server
|
- `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
|
Use `core` when you need the raw types or want to author a custom transport. Public APIs are explicit to keep the shared
|
||||||
explicitly if you only need the protocol types or plan to implement a custom transport.
|
surface stable across platforms.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Module kotlin-sdk-client
|
## Module kotlin-sdk-client
|
||||||
|
|
||||||
High‑level client API for connecting to an MCP server and invoking its tools, prompts, and resources. Ships with several
|
High-level client for connecting to MCP servers and invoking their features:
|
||||||
transports:
|
|
||||||
|
|
||||||
- WebSocketClientTransport – low latency, full‑duplex
|
- `Client` runtime (or `mcpClient` helper) performs the MCP handshake and exposes `serverCapabilities`,
|
||||||
- SSEClientTransport – Server‑Sent Events over HTTP
|
`serverVersion`, and `serverInstructions`.
|
||||||
- StdioClientTransport – CLI‑friendly stdio bridge
|
- Typed operations for tools, prompts, resources, completion, logging, roots, sampling, and elicitation with capability
|
||||||
- StreamableHttpClientTransport – simple HTTP streaming
|
enforcement.
|
||||||
|
- Transports: `StdioClientTransport`, `SseClientTransport`, `WebSocketClientTransport`, and `StreamableHttpClientTransport`,
|
||||||
|
plus Ktor client extensions for quick wiring.
|
||||||
|
|
||||||
A minimal client:
|
Minimal WebSocket client:
|
||||||
|
|
||||||
```kotlin
|
```kotlin
|
||||||
val client = Client(
|
val client = mcpClient(
|
||||||
clientInfo = Implementation(name = "sample-client", version = "1.0.0")
|
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 tools = client.listTools()
|
||||||
val result = client.callTool(
|
val result = client.callTool("echo", mapOf("text" to "Hello, MCP!"))
|
||||||
name = "echo",
|
println(result.content)
|
||||||
arguments = mapOf("text" to "Hello, MCP!")
|
|
||||||
)
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Module kotlin-sdk-server
|
## Module kotlin-sdk-server
|
||||||
|
|
||||||
Lightweight server toolkit for hosting MCP tools, prompts, and resources. It provides a small, composable API and
|
Server toolkit for exposing MCP tools, prompts, and resources:
|
||||||
ready‑to‑use transports:
|
|
||||||
|
|
||||||
- StdioServerTransport – integrates well with CLIs and editors
|
- `Server` runtime coordinates sessions, initialization flow, and capability enforcement with registries for tools,
|
||||||
- SSE/WebSocket helpers for Ktor – easy HTTP deployment
|
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
|
```kotlin
|
||||||
|
fun Application.module() {
|
||||||
val server = Server(
|
mcp {
|
||||||
serverInfo = Implementation(name = "sample-server", version = "1.0.0"),
|
Server(
|
||||||
options = ServerOptions(ServerCapabilities())
|
serverInfo = Implementation("sample-server", "1.0.0"),
|
||||||
)
|
options = ServerOptions(ServerCapabilities(
|
||||||
|
tools = ServerCapabilities.Tools(listChanged = true),
|
||||||
server.addTool(
|
resources = ServerCapabilities.Resources(listChanged = true, subscribe = true),
|
||||||
name = "echo",
|
)),
|
||||||
description = "Echoes the provided text"
|
) {
|
||||||
) { request ->
|
addTool(name = "echo", description = "Echo text back") { request ->
|
||||||
// Build and return a CallToolResult from request.arguments
|
val text = request.params.arguments?.get("text")?.jsonPrimitive?.content ?: ""
|
||||||
// (see CallToolResult and related types in kotlin-sdk-core)
|
CallToolResult(content = listOf(TextContent("You said: $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
|
Pick the module that matches your role, or use the umbrella artifact to get both sides with the shared core.
|
||||||
few lines of code.
|
|
||||||
|
|
|
||||||
|
|
@ -7,6 +7,7 @@ dokka = "2.1.0"
|
||||||
kotlin = "2.2.21"
|
kotlin = "2.2.21"
|
||||||
kover = "0.9.4"
|
kover = "0.9.4"
|
||||||
ktlint = "14.0.1"
|
ktlint = "14.0.1"
|
||||||
|
knit = "0.5.1"
|
||||||
mavenPublish = "0.36.0"
|
mavenPublish = "0.36.0"
|
||||||
netty = "4.2.9.Final"
|
netty = "4.2.9.Final"
|
||||||
openapi-generator = "7.18.0"
|
openapi-generator = "7.18.0"
|
||||||
|
|
@ -23,7 +24,7 @@ mockk = "1.14.7"
|
||||||
mokksy = "0.6.2"
|
mokksy = "0.6.2"
|
||||||
serialization = "1.9.0"
|
serialization = "1.9.0"
|
||||||
slf4j = "2.0.17"
|
slf4j = "2.0.17"
|
||||||
junit="5.14.2"
|
junit = "5.14.2"
|
||||||
|
|
||||||
[libraries]
|
[libraries]
|
||||||
# Plugins
|
# Plugins
|
||||||
|
|
@ -74,4 +75,5 @@ detekt = { id = "dev.detekt", version.ref = "detekt" }
|
||||||
kotlinx-binary-compatibility-validator = { id = "org.jetbrains.kotlinx.binary-compatibility-validator", version.ref = "binaryCompatibilityValidatorPlugin" }
|
kotlinx-binary-compatibility-validator = { id = "org.jetbrains.kotlinx.binary-compatibility-validator", version.ref = "binaryCompatibilityValidatorPlugin" }
|
||||||
kover = { id = "org.jetbrains.kotlinx.kover", version.ref = "kover" }
|
kover = { id = "org.jetbrains.kotlinx.kover", version.ref = "kover" }
|
||||||
ktlint = { id = "org.jlleitschuh.gradle.ktlint", version.ref = "ktlint" }
|
ktlint = { id = "org.jlleitschuh.gradle.ktlint", version.ref = "ktlint" }
|
||||||
|
knit = { id = "org.jetbrains.kotlinx.knit", version.ref = "knit" }
|
||||||
openapi-generator = { id = "org.openapi.generator", version.ref = "openapi-generator" }
|
openapi-generator = { id = "org.openapi.generator", version.ref = "openapi-generator" }
|
||||||
|
|
|
||||||
3
knit.properties
Normal file
3
knit.properties
Normal file
|
|
@ -0,0 +1,3 @@
|
||||||
|
# Knit configuration
|
||||||
|
knit.dir=docs/src/main/kotlin/
|
||||||
|
knit.package=io.modelcontextprotocol.kotlin.sdk.examples
|
||||||
|
|
@ -1,10 +1,78 @@
|
||||||
# Module kotlin-sdk-client
|
# Module kotlin-sdk-client
|
||||||
|
|
||||||
The Model Context Protocol (MCP) Kotlin SDK client module provides a multiplatform implementation for connecting to and
|
`kotlin-sdk-client` is the multiplatform MCP client for Kotlin. It handles the MCP handshake, enforces capabilities, and
|
||||||
interacting with MCP servers.
|
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
|
- **Client runtime**: The `Client` class (or `mcpClient` helper) wraps initialization, capability checks, and
|
||||||
- Built-in support for multiple transport protocols (stdio, SSE, WebSocket)
|
request/notification plumbing. After connecting, it exposes `serverCapabilities`, `serverVersion`, and
|
||||||
- Type-safe API for resource management and server interactions
|
`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.
|
||||||
|
|
|
||||||
|
|
@ -1,5 +1,47 @@
|
||||||
# Module kotlin-sdk-core
|
# Module kotlin-sdk-core
|
||||||
|
|
||||||
The MCP Kotlin SDK Core module provides fundamental functionality for interacting with Model Context Protocol (MCP).
|
`kotlin-sdk-core` is the foundation of the MCP Kotlin SDK. It contains protocol message types, JSON handling, and
|
||||||
This module serves as the foundation for building MCP-enabled applications in Kotlin.
|
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.
|
||||||
|
|
|
||||||
|
|
@ -1,14 +1,125 @@
|
||||||
# Module kotlin-sdk-server
|
# Module kotlin-sdk-server
|
||||||
|
|
||||||
The server module provides core server-side functionality for the Model Context Protocol (MCP) Kotlin SDK.
|
`kotlin-sdk-server` contains the server-side building blocks for Model Context Protocol (MCP) applications written in
|
||||||
This module includes essential parts for writing MCP server applications.
|
Kotlin Multiplatform. It pairs the protocol types from `kotlin-sdk-core` with transport implementations and utilities
|
||||||
|
that make it straightforward to expose tools, prompts, and resources to MCP clients.
|
||||||
|
|
||||||
## Features
|
## What the module provides
|
||||||
|
|
||||||
* Server-side request handling
|
- **Server runtime**: The `Server` class coordinates sessions, initialization flow, and capability enforcement. It
|
||||||
* Model context management
|
tracks active sessions and cleans them up when transports close.
|
||||||
* Protocol implementation
|
- **Feature registries**: Helpers to register and remove tools, prompts, resources, and resource templates. Registry
|
||||||
* Integration utilities
|
listeners emit list-changed notifications when the capability is enabled.
|
||||||
|
- **Transports**: Ready-to-use transports for STDIO (CLI-style hosting), Ktor Server-Sent Events (SSE) with POST
|
||||||
|
back-channel, and Ktor WebSocket. All share the common `Transport` abstraction from the SDK.
|
||||||
|
- **Ktor integration**: Extension functions (`Routing.mcp`, `Routing.mcpWebSocket`, and `Application` variants) that
|
||||||
|
plug MCP into an existing Ktor server with minimal boilerplate.
|
||||||
|
- **Notifications**: Built-in support for resource subscription, resource-updated events, and feature list change
|
||||||
|
notifications when capabilities are set accordingly.
|
||||||
|
|
||||||
For detailed usage instructions and examples, please refer to
|
## Typical server setup
|
||||||
the [documentation](https://github.com/modelcontextprotocol/kotlin-sdk/blob/main/README.md).
|
|
||||||
|
1. Declare capabilities your server supports using `ServerOptions`. Capabilities drive which handlers are installed and
|
||||||
|
whether list-change notifications are emitted.
|
||||||
|
2. Register features: tools, prompts, resources, and resource templates. Handlers run in suspending context and can be
|
||||||
|
removed or replaced at runtime.
|
||||||
|
3. Attach a transport and open a session via `createSession(transport)`. Multiple sessions can be active simultaneously.
|
||||||
|
4. Close the server to tear down transports and unsubscribe sessions.
|
||||||
|
|
||||||
|
### Minimal STDIO server
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
val server = Server(
|
||||||
|
serverInfo = Implementation(name = "demo-server", version = "1.0.0"),
|
||||||
|
options = ServerOptions(
|
||||||
|
capabilities = ServerCapabilities(
|
||||||
|
tools = ServerCapabilities.Tools(listChanged = true)
|
||||||
|
)
|
||||||
|
)
|
||||||
|
) {
|
||||||
|
addTool(
|
||||||
|
name = "hello",
|
||||||
|
description = "Greets the caller by name"
|
||||||
|
) { request ->
|
||||||
|
val name = request.params.arguments?.get("name")?.jsonPrimitive?.content ?: "there"
|
||||||
|
CallToolResult(
|
||||||
|
content = listOf(TextContent("Hello, $name!")),
|
||||||
|
isError = false,
|
||||||
|
)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
val transport = StdioServerTransport(
|
||||||
|
System.`in`.asSource().buffered(),
|
||||||
|
System.out.asSink().buffered()
|
||||||
|
)
|
||||||
|
server.createSession(transport)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Hosting with Ktor (SSE)
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
fun Application.module() {
|
||||||
|
mcp {
|
||||||
|
Server(
|
||||||
|
serverInfo = Implementation("ktor-sse", "1.0.0"),
|
||||||
|
options = ServerOptions(
|
||||||
|
ServerCapabilities(
|
||||||
|
prompts = ServerCapabilities.Prompts(listChanged = true),
|
||||||
|
resources = ServerCapabilities.Resources(listChanged = true, subscribe = true),
|
||||||
|
)
|
||||||
|
)
|
||||||
|
) {
|
||||||
|
addPrompt(
|
||||||
|
name = "welcome",
|
||||||
|
description = "Explain how to use the server"
|
||||||
|
) {
|
||||||
|
GetPromptResult(
|
||||||
|
description = "Welcome to the MCP server",
|
||||||
|
messages = listOf(CreateMessageResult.Message(TextContent("Try listing tools first")))
|
||||||
|
)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The SSE route exposes a streaming GET endpoint and a POST endpoint for client messages. Session affinity is maintained
|
||||||
|
by a `sessionId` query parameter managed by the SDK.
|
||||||
|
|
||||||
|
### Hosting with Ktor (WebSocket)
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
fun Application.module() {
|
||||||
|
mcpWebSocket {
|
||||||
|
Server(
|
||||||
|
serverInfo = Implementation("ktor-ws", "1.0.0"),
|
||||||
|
options = ServerOptions(ServerCapabilities(tools = ServerCapabilities.Tools()))
|
||||||
|
)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
`mcpWebSocket` installs Ktor WebSockets and wires message handling over a single bidirectional connection.
|
||||||
|
|
||||||
|
## Feature registration details
|
||||||
|
|
||||||
|
- **Tools**: `addTool` accepts a `Tool` descriptor or inline parameters plus a suspend handler. `removeTool` and
|
||||||
|
`addTools/removeTools` support dynamic updates.
|
||||||
|
- **Prompts**: `addPrompt` wires a provider that returns `GetPromptResult` and optional arguments metadata.
|
||||||
|
- **Resources**: `addResource` exposes static or generated content via `ReadResourceResult`; `addResources`
|
||||||
|
batch-registers. Templates and roots are also supported for structured discovery.
|
||||||
|
- **Instructions**: Provide static text or a function via `instructionsProvider` to send per-session usage guidance
|
||||||
|
during initialization.
|
||||||
|
|
||||||
|
## Lifecycle and diagnostics
|
||||||
|
|
||||||
|
- Sessions emit callbacks via `onConnect` and `onClose`. Deprecated `onInitialized` exists for backward compatibility;
|
||||||
|
prefer session-level hooks.
|
||||||
|
- The server enforces declared capabilities; attempting to register an unsupported feature throws with a descriptive
|
||||||
|
message.
|
||||||
|
- Logging uses `KotlinLogging`; avoid logging secrets. To inspect traffic, run the server with DEBUG level enabled.
|
||||||
|
|
||||||
|
Use this module whenever you need to expose MCP features from a Kotlin service—whether embedding in a CLI via STDIO,
|
||||||
|
serving from Ktor over SSE/WebSocket, or composing transports for custom environments. Public APIs are explicit to keep
|
||||||
|
server-facing contracts stable for consumers.
|
||||||
|
|
|
||||||
|
|
@ -24,5 +24,6 @@ include(
|
||||||
":kotlin-sdk-server",
|
":kotlin-sdk-server",
|
||||||
":kotlin-sdk",
|
":kotlin-sdk",
|
||||||
":integration-test",
|
":integration-test",
|
||||||
|
":docs",
|
||||||
":conformance-test",
|
":conformance-test",
|
||||||
)
|
)
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue