kotlin-sdk/kotlin-sdk-core/Module.md

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

val request = CallToolRequest {
    name = "summarize"
    arguments = mapOf("text" to "Hello MCP")
}

Example: parsing a JSON-RPC message

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.