feat(docs): public api kdocs (#658)

- enable rule for checking undocumented public api 
- add kdoc skill

## How Has This Been Tested?
./gradlew detekt

## 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: Konstantin Pavlov <1517853+kpavlov@users.noreply.github.com>

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/internal/utils.kt

@@ -2,4 +2,5 @@ package io.modelcontextprotocol.kotlin.sdk.internal
 
 import kotlinx.coroutines.CoroutineDispatcher
 
+/** Platform-specific [CoroutineDispatcher] for I/O-bound operations. */
 public expect val IODispatcher: CoroutineDispatcher

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/shared/Protocol.kt

@@ -42,6 +42,7 @@ import kotlin.time.Duration.Companion.seconds
 
 private val logger = KotlinLogging.logger { }
 
+/** Default implementation name used in MCP handshake. */
 public const val IMPLEMENTATION_NAME: String = "mcp-ktor"
 
 /**
@@ -51,6 +52,8 @@ public typealias ProgressCallback = (Progress) -> Unit
 
 /**
  * Additional initialization options.
+ *
+ * @property timeout default timeout for outgoing requests
  */
 public open class ProtocolOptions(
     /**
@@ -97,9 +100,13 @@ public class RequestOptions(
     public val onProgress: ProgressCallback? = null,
     public val timeout: Duration = DEFAULT_REQUEST_TIMEOUT,
 ) : TransportSendOptions(relatedRequestId, resumptionToken, onResumptionToken) {
+    /** Destructuring component for [onProgress]. */
     public operator fun component4(): ProgressCallback? = onProgress
+
+    /** Destructuring component for [timeout]. */
     public operator fun component5(): Duration = timeout
 
+    /** Creates a copy of this [RequestOptions] with the specified fields replaced. */
     public fun copy(
         relatedRequestId: RequestId? = this.relatedRequestId,
         resumptionToken: String? = this.resumptionToken,
@@ -139,6 +146,12 @@ internal val COMPLETED = CompletableDeferred(Unit).also { it.complete(Unit) }
 /**
  * Implements MCP protocol framing on top of a pluggable transport, including
  * features like request/response linking, notifications, and progress.
+ *
+ * @property transport the active transport, or `null` if not connected
+ * @property requestHandlers registered request handlers keyed by method name
+ * @property notificationHandlers registered notification handlers keyed by method name
+ * @property responseHandlers pending response handlers keyed by request ID
+ * @property progressHandlers registered progress callbacks keyed by progress token
  */
 public abstract class Protocol(@PublishedApi internal val options: ProtocolOptions?) {
     public var transport: Transport? = null

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/shared/TransportSendOptions.kt

@@ -17,10 +17,16 @@ public open class TransportSendOptions(
     public val resumptionToken: String? = null,
     public val onResumptionToken: ((String) -> Unit)? = null,
 ) {
+    /** Destructuring component for [relatedRequestId]. */
     public operator fun component1(): RequestId? = relatedRequestId
+
+    /** Destructuring component for [resumptionToken]. */
     public operator fun component2(): String? = resumptionToken
+
+    /** Destructuring component for [onResumptionToken]. */
     public operator fun component3(): ((String) -> Unit)? = onResumptionToken
 
+    /** Creates a copy of this [TransportSendOptions] with the specified fields replaced. */
     public open fun copy(
         relatedRequestId: RequestId? = this.relatedRequestId,
         resumptionToken: String? = this.resumptionToken,

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/shared/WebSocketMcpTransport.kt

@@ -17,6 +17,7 @@ import kotlinx.coroutines.launch
 import kotlin.concurrent.atomics.AtomicBoolean
 import kotlin.concurrent.atomics.ExperimentalAtomicApi
 
+/** WebSocket subprotocol identifier for MCP connections. */
 public const val MCP_SUBPROTOCOL: String = "mcp"
 
 private val logger = KotlinLogging.logger {}

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/PingRequest.kt

@@ -4,6 +4,11 @@ import kotlinx.serialization.EncodeDefault
 import kotlinx.serialization.ExperimentalSerializationApi
 import kotlinx.serialization.Serializable
 
+/**
+ * Represents a ping request used to check if the connection is alive.
+ *
+ * @property meta optional request metadata
+ */
 @Serializable
 public data class PingRequest(override val params: BaseRequestParams? = null) :
     ClientRequest,

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/capabilities.kt

@@ -54,6 +54,10 @@ public data class ClientCapabilities(
     public val experimental: JsonObject? = null,
 ) {
 
+    /**
+     * @property sampling convenience value to enable the sampling capability
+     * @property elicitation convenience value to enable the elicitation capability
+     */
     public companion object {
         public val sampling: JsonObject = EmptyJsonObject
         public val elicitation: JsonObject = EmptyJsonObject
@@ -100,6 +104,10 @@ public data class ServerCapabilities(
     val experimental: JsonObject? = null,
 ) {
 
+    /**
+     * @property Logging convenience value to enable the logging capability
+     * @property Completions convenience value to enable the completions capability
+     */
     public companion object {
         public val Logging: JsonObject = EmptyJsonObject
         public val Completions: JsonObject = EmptyJsonObject

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/common.kt

@@ -8,10 +8,13 @@ import kotlinx.serialization.json.JsonObject
 // Protocol Version Constants
 // ============================================================================
 
+/** The latest supported MCP protocol version string. */
 public const val LATEST_PROTOCOL_VERSION: String = "2025-11-25"
 
+/** The default protocol version used when negotiation is not performed. */
 public const val DEFAULT_NEGOTIATED_PROTOCOL_VERSION: String = "2025-06-18"
 
+/** All MCP protocol versions supported by this SDK. */
 public val SUPPORTED_PROTOCOL_VERSIONS: List<String> = listOf(
     LATEST_PROTOCOL_VERSION,
     "2025-06-18",
@@ -25,6 +28,8 @@ public val SUPPORTED_PROTOCOL_VERSIONS: List<String> = listOf(
 
 /**
  * Represents an entity that includes additional metadata in its responses.
+ *
+ * @property meta optional metadata attached to this entity
  */
 @Serializable
 public sealed interface WithMeta {
@@ -123,13 +128,19 @@ public enum class Role {
  *
  * References are used to point to other entities (prompts, resources, etc.)
  * without including their full definitions.
+ *
+ * @property type discriminator identifying the reference subtype
  */
 @Serializable(with = ReferencePolymorphicSerializer::class)
 public sealed interface Reference {
     public val type: ReferenceType
 }
 
-/** Discriminator for [Reference] subtypes used in completion and other operations. */
+/**
+ * Discriminator for [Reference] subtypes used in completion and other operations.
+ *
+ * @property value serialized string representation of this reference type
+ */
 @Serializable
 public enum class ReferenceType(public val value: String) {
     @SerialName("ref/prompt")

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/completion.kt

@@ -12,6 +12,7 @@ import kotlinx.serialization.json.JsonObject
  * A request from the client to the server to ask for completion options.
  *
  * @property params The request parameters containing the argument to complete and its context.
+ * @property meta optional request metadata
  */
 @Serializable
 public data class CompleteRequest(override val params: CompleteRequestParams) : ClientRequest {

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/content.kt

@@ -8,7 +8,11 @@ import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 import kotlinx.serialization.json.JsonObject
 
-/** Discriminator values for the polymorphic [ContentBlock] hierarchy. */
+/**
+ * Discriminator values for the polymorphic [ContentBlock] hierarchy.
+ *
+ * @property value serialized string representation of this content type
+ */
 @Serializable
 public enum class ContentTypes(public val value: String) {
     @SerialName("text")
@@ -27,11 +31,19 @@ public enum class ContentTypes(public val value: String) {
     EMBEDDED_RESOURCE("resource"),
 }
 
+/**
+ * Base interface for all content blocks in the protocol.
+ *
+ * @property type discriminator identifying the content block subtype
+ */
 @Serializable(with = ContentBlockPolymorphicSerializer::class)
 public sealed interface ContentBlock : WithMeta {
     public val type: ContentTypes
 }
 
+/**
+ * Content block that carries media data such as text, images, or audio.
+ */
 @Serializable(with = MediaContentPolymorphicSerializer::class)
 public sealed interface MediaContent : ContentBlock
 

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/elicitation.kt

@@ -46,6 +46,8 @@ public data class ElicitRequest(override val params: ElicitRequestParams) : Serv
  * Represents the parameters for an `elicitation/create` request.
  *
  * Implementations: [ElicitRequestFormParams], [ElicitRequestURLParams].
+ *
+ * @property message The message to present to the user describing what information is being requested.
  */
 @Serializable(with = ElicitRequestParamsSerializer::class)
 public sealed interface ElicitRequestParams : RequestParams {
@@ -111,6 +113,7 @@ public fun ElicitRequestParams(
  *   later via `tasks/result`.
  * @property requestedSchema A restricted subset of JSON Schema. Only top-level properties
  *   are allowed, without nesting.
+ * @property mode The elicitation mode discriminator, always `"form"`.
  * @property meta Optional metadata. May include a progressToken for out-of-band progress notifications.
  */
 @Serializable
@@ -138,6 +141,7 @@ public data class ElicitRequestFormParams(
  * @property task If specified, the caller is requesting task-augmented execution. The request
  *   will return a [CreateTaskResult] immediately, and the actual result can be retrieved
  *   later via `tasks/result`.
+ * @property mode The elicitation mode discriminator, always `"url"`.
  * @property meta Optional metadata. May include a progressToken for out-of-band progress notifications.
  */
 @Serializable

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/jsonRpc.kt

@@ -14,6 +14,7 @@ import kotlin.jvm.JvmOverloads
 import kotlin.uuid.ExperimentalUuidApi
 import kotlin.uuid.Uuid
 
+/** JSON-RPC protocol version used by MCP (`"2.0"`). */
 public const val JSONRPC_VERSION: String = "2.0"
 
 /**
@@ -40,12 +41,20 @@ public fun RequestId(value: Long): RequestId = RequestId.NumberId(value)
 @Serializable(with = RequestIdPolymorphicSerializer::class)
 public sealed interface RequestId {
 
-    /** A string-based request identifier. */
+    /**
+     * A string-based request identifier.
+     *
+     * @property value the string representation of this request ID
+     */
     @JvmInline
     @Serializable
     public value class StringId(public val value: String) : RequestId
 
-    /** A numeric request identifier. */
+    /**
+     * A numeric request identifier.
+     *
+     * @property value the numeric representation of this request ID
+     */
     @JvmInline
     @Serializable
     public value class NumberId(public val value: Long) : RequestId
@@ -95,12 +104,17 @@ internal fun JSONRPCNotification.fromJSON(): Notification =
  * Base interface for all JSON-RPC 2.0 messages.
  *
  * All messages in the MCP protocol follow the JSON-RPC 2.0 specification.
+ *
+ * @property jsonrpc the JSON-RPC protocol version, always `"2.0"`
  */
 @Serializable(with = JSONRPCMessagePolymorphicSerializer::class)
 public sealed interface JSONRPCMessage {
     public val jsonrpc: String
 }
 
+/**
+ * Represents an empty JSON-RPC message used as a placeholder or no-op response.
+ */
 @Serializable
 public data object JSONRPCEmptyMessage : JSONRPCMessage {
     override val jsonrpc: String = JSONRPC_VERSION

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/jsonUtils.kt

@@ -11,8 +11,10 @@ import kotlinx.serialization.json.add
 import kotlinx.serialization.json.buildJsonArray
 import kotlinx.serialization.json.buildJsonObject
 
+/** Reusable empty [JsonObject] instance. */
 public val EmptyJsonObject: JsonObject = JsonObject(emptyMap())
 
+/** Pre-configured [Json] instance for MCP serialization. */
 @OptIn(ExperimentalSerializationApi::class)
 public val McpJson: Json by lazy {
     Json {

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/methods.kt

@@ -4,6 +4,8 @@ import kotlinx.serialization.Serializable
 
 /**
  * Represents a method in the protocol, which can be predefined or custom.
+ *
+ * @property value the string representation of this method name
  */
 @Serializable(with = MethodSerializer::class)
 public sealed interface Method {

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt

@@ -11,6 +11,9 @@ import kotlinx.serialization.json.JsonObject
 
 /**
  * Represents a notification in the protocol.
+ *
+ * @property method the notification method identifier
+ * @property params optional notification parameters
  */
 @Serializable(with = NotificationPolymorphicSerializer::class)
 public sealed interface Notification {
@@ -73,6 +76,7 @@ public class Progress(
  * @property method The custom method name. By convention, custom methods often contain
  * organization-specific prefixes (e.g., "mycompany/custom_event").
  * @property params Raw JSON parameters for the custom notification, if present.
+ * @property meta optional metadata for this notification
  */
 @Serializable
 public data class CustomNotification(override val method: Method, override val params: BaseNotificationParams? = null) :

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/request.kt

@@ -11,6 +11,12 @@ import kotlinx.serialization.json.long
 import kotlinx.serialization.json.longOrNull
 import kotlin.jvm.JvmInline
 
+/**
+ * Metadata attached to a request's `_meta` field.
+ *
+ * @property json the raw JSON object containing the metadata
+ * @property progressToken optional progress token for tracking request progress
+ */
 @JvmInline
 @Serializable
 public value class RequestMeta(public val json: JsonObject) {
@@ -43,6 +49,9 @@ public value class RequestMeta(public val json: JsonObject) {
     public operator fun get(key: String): JsonElement? = json[key]
 }
 
+/**
+ * Base interface for parameters attached to a [Request].
+ */
 @Serializable
 public sealed interface RequestParams {
     /**
@@ -55,11 +64,17 @@ public sealed interface RequestParams {
     public val meta: RequestMeta?
 }
 
+/**
+ * Default [RequestParams] implementation carrying only optional metadata.
+ */
 @Serializable
 public data class BaseRequestParams(@SerialName("_meta") override val meta: RequestMeta? = null) : RequestParams
 
 /**
  * Represents a request in the protocol.
+ *
+ * @property method the request method identifier
+ * @property params optional request parameters
  */
 @OptIn(ExperimentalSerializationApi::class)
 @Serializable(with = RequestPolymorphicSerializer::class)
@@ -112,9 +127,15 @@ public sealed interface PaginatedRequest : Request {
 @Serializable(with = RequestResultPolymorphicSerializer::class)
 public sealed interface RequestResult : WithMeta
 
+/**
+ * Represents a result returned by the server in response to a [ClientRequest].
+ */
 @Serializable(with = ClientResultPolymorphicSerializer::class)
 public sealed interface ClientResult : RequestResult
 
+/**
+ * Represents a result returned by the client in response to a [ServerRequest].
+ */
 @Serializable(with = ServerResultPolymorphicSerializer::class)
 public sealed interface ServerResult : RequestResult
 
@@ -129,7 +150,9 @@ public data class EmptyResult(@SerialName("_meta") override val meta: JsonObject
     ServerResult
 
 /**
- * Represents a request supporting pagination.
+ * Represents a paginated result.
+ *
+ * @property nextCursor opaque token for retrieving the next page of results, or `null` if no more results
  */
 @Serializable
 public sealed interface PaginatedResult : RequestResult {

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt

@@ -8,6 +8,9 @@ import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 import kotlinx.serialization.json.JsonObject
 
+/**
+ * Common interface for resource-like types that share URI, name, and description fields.
+ */
 @Serializable
 public sealed interface ResourceLike : WithMeta
 

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/roots.kt

@@ -53,6 +53,7 @@ public data class Root(
  * `listChanged = true` to receive these requests.
  *
  * @property params Optional request parameters containing metadata.
+ * @property meta optional request metadata
  */
 @Serializable
 public data class ListRootsRequest(override val params: BaseRequestParams? = null) : ServerRequest {

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/sampling.kt

@@ -243,10 +243,19 @@ public data class CreateMessageResult(
     override val meta: JsonObject? = null,
 ) : ClientResult
 
-/** The reason why the LLM stopped generating tokens. */
+/**
+ * The reason why the LLM stopped generating tokens.
+ *
+ * @property value the string representation of this stop reason
+ */
 @JvmInline
 @Serializable
 public value class StopReason(public val value: String) {
+    /**
+     * @property EndTurn generation ended naturally
+     * @property StopSequence a stop sequence was encountered
+     * @property MaxTokens the maximum token limit was reached
+     */
     public companion object {
         public val EndTurn: StopReason = StopReason("endTurn")
         public val StopSequence: StopReason = StopReason("stopSequence")

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/schema.kt

@@ -24,6 +24,7 @@ public sealed interface PrimitiveSchemaDefinition
  * @property minLength Minimum string length.
  * @property maxLength Maximum string length.
  * @property format Optional format constraint (e.g., email, URI, date).
+ * @property type JSON Schema type discriminator, always `"string"`.
  * @property default Optional default value.
  */
 @Serializable
@@ -72,6 +73,7 @@ public sealed interface NumberSchemaDefinition : PrimitiveSchemaDefinition
  * @property description Optional description for the field.
  * @property minimum Minimum allowed value.
  * @property maximum Maximum allowed value.
+ * @property type JSON Schema type discriminator, always `"integer"`.
  * @property default Optional default value.
  */
 @Serializable
@@ -93,6 +95,7 @@ public data class IntegerSchema(
  * @property description Optional description for the field.
  * @property minimum Minimum allowed value.
  * @property maximum Maximum allowed value.
+ * @property type JSON Schema type discriminator, always `"number"`.
  * @property default Optional default value.
  */
 @Serializable
@@ -112,6 +115,7 @@ public data class DoubleSchema(
  *
  * @property title Optional display title for the field.
  * @property description Optional description for the field.
+ * @property type JSON Schema type discriminator, always `"boolean"`.
  * @property default Optional default value.
  */
 @Serializable
@@ -157,6 +161,7 @@ public sealed interface SingleSelectEnumSchema : EnumSchemaDefinition
  * @property title Optional display title for the field.
  * @property description Optional description for the field.
  * @property enumValues Array of enum values to choose from.
+ * @property type JSON Schema type discriminator, always `"string"`.
  * @property default Optional default value.
  */
 @Serializable
@@ -177,6 +182,7 @@ public data class UntitledSingleSelectEnumSchema(
  * @property title Optional display title for the field.
  * @property description Optional description for the field.
  * @property oneOf Array of enum options with values and display labels.
+ * @property type JSON Schema type discriminator, always `"string"`.
  * @property default Optional default value.
  */
 @Serializable
@@ -199,6 +205,7 @@ public data class TitledSingleSelectEnumSchema(
  * @property description Optional description for the field.
  * @property enumValues Array of enum values to choose from.
  * @property enumNames Display names for enum values. Non-standard according to JSON Schema 2020-12.
+ * @property type JSON Schema type discriminator, always `"string"`.
  * @property default Optional default value.
  */
 @Deprecated("Use TitledSingleSelectEnumSchema instead")
@@ -231,6 +238,7 @@ public sealed interface MultiSelectEnumSchema : EnumSchemaDefinition
  * @property minItems Minimum number of items to select.
  * @property maxItems Maximum number of items to select.
  * @property items Schema for the array items.
+ * @property type JSON Schema type discriminator, always `"array"`.
  * @property default Optional default value.
  */
 @Serializable
@@ -248,6 +256,7 @@ public data class UntitledMultiSelectEnumSchema(
     /**
      * Schema for the array items with plain enum values.
      *
+     * @property type JSON Schema type discriminator, always `"string"`.
      * @property enumValues Array of enum values to choose from.
      */
     @Serializable
@@ -268,6 +277,7 @@ public data class UntitledMultiSelectEnumSchema(
  * @property minItems Minimum number of items to select.
  * @property maxItems Maximum number of items to select.
  * @property items Schema for array items with enum options and display labels.
+ * @property type JSON Schema type discriminator, always `"array"`.
  * @property default Optional default value.
  */
 @Serializable

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/tasks.kt

@@ -17,6 +17,14 @@ public const val RELATED_TASK_META_KEY: String = "io.modelcontextprotocol/relate
 
 /**
  * Common fields shared by all types representing the task state.
+ *
+ * @property taskId the task identifier
+ * @property status current task state
+ * @property statusMessage optional human-readable message describing the current task state
+ * @property createdAt ISO 8601 timestamp when the task was created
+ * @property lastUpdatedAt ISO 8601 timestamp when the task was last updated
+ * @property ttl actual retention duration from creation in milliseconds, or `null` for unlimited
+ * @property pollInterval suggested polling interval in milliseconds
  */
 public sealed interface TaskFields {
     public val taskId: String
@@ -228,6 +236,7 @@ public data class GetTaskPayloadRequestParams(
  * The structure matches the result type of the original request.
  * For example, a tools/call task would return the [CallToolResult] structure.
  *
+ * @property json the raw JSON object containing the result payload
  * @property meta Optional metadata for this response.
  */
 @JvmInline