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>
47 lines
2.5 KiB
Markdown
47 lines
2.5 KiB
Markdown
# Module kotlin-sdk-core
|
|
|
|
`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.
|