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>

Author: devcrocod

.claude/skills/kdoc/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: kdoc
+description: "Add KDoc documentation to Kotlin public API. Use whenever the user asks to document Kotlin code, add KDoc, generate API docs, mentions undocumented public declarations, or wants to improve existing documentation. Also trigger when the user says 'add docs', 'document this class/file/module', 'write KDoc', or asks about missing documentation in Kotlin code."
+---
+
+# KDoc Generator
+
+Add KDoc comments to public Kotlin API declarations.
+
+## What to document
+
+All public declarations (no explicit `private`/`internal`/`protected`):
+- Classes, interfaces, objects, sealed classes/interfaces
+- Functions, extension functions
+- Properties
+- Enum classes and entries
+- Type aliases, annotation classes
+
+Include `@Deprecated` elements.
+
+## Context
+
+Read the implementation, not just the signature, to write accurate descriptions. Understanding what the code actually does prevents superficial or misleading documentation.
+
+## KDoc format
+
+**Class/interface example:**
+
+````kotlin
+/**
+ * Manages active client sessions and their lifecycle.
+ *
+ * Sessions are created on first connection and cleaned up
+ * when the transport closes.
+ *
+ * @property maxSessions upper limit on concurrent sessions
+ * @property timeout idle timeout before a session is evicted
+ */
+````
+
+**Function example:**
+
+````kotlin
+/**
+ * Registers a new tool with the given handler.
+ *
+ * Example:
+ * ```kotlin
+ * server.addTool(
+ *     name = "echo",
+ *     description = "Echoes input back",
+ * ) { request ->
+ *     CallToolResult(content = listOf(TextContent("Echo: ${request.arguments}")))
+ * }
+ * ```
+ *
+ * @param name unique tool identifier
+ * @param description human-readable tool description
+ * @param handler suspend function invoked when the tool is called
+ * @return the registered tool definition
+ */
+````
+
+## Rules
+
+- Summary: concise first sentence starting with a third-person verb ("Creates", "Returns", "Represents"). Expand to 2-3 sentences only when genuinely complex
+- **@property** in class-level KDoc for all public properties (never as individual KDoc on the property); **@param** for function parameters
+- **@return** for non-Unit return types
+- **Example block**: add for DSL builders, complex functions, extension functions with non-obvious usage. Skip for trivial one-liners and simple getters
+- **DSL builders**: always include an Example showing full usage with the receiver scope — this is critical for discoverability
+- KDoc links (`[ClassName]`, `[methodName]`): only where it adds clear navigational value
+- No **@throws** — don't document exceptions
+- No **suspend** notes — coroutine nature is visible from the signature
+- **Existing KDoc**: rewrite if incomplete (missing @param/@return/@property) or low quality

config/detekt/detekt.yml

@@ -22,3 +22,22 @@ empty-blocks:
   EmptyFunctionBlock:
     excludes: *testFolders
 
+comments:
+    UndocumentedPublicClass:
+      active: true
+      excludes: &testAndGeneratedFolders
+        - '**/test/**'
+        - '**/commonTest/**'
+        - '**/jvmTest/**'
+        - '**/jsTest/**'
+        - '**/iosTest/**'
+        - '**/generated-sources/**'
+      ignoreDefaultCompanionObject: true
+    UndocumentedPublicFunction:
+      active: true
+      excludes: *testAndGeneratedFolders
+    UndocumentedPublicProperty:
+      active: true
+      excludes: *testAndGeneratedFolders
+      searchProtectedProperty: false
+      ignoreEnumEntries: true

kotlin-sdk-client/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/StreamableHttpClientTransport.kt

@@ -51,7 +51,9 @@ private const val MCP_PROTOCOL_VERSION_HEADER = "mcp-protocol-version"
 private const val MCP_RESUMPTION_TOKEN_HEADER = "Last-Event-ID"
 
 /**
- * Error class for Streamable HTTP transport errors.
+ * Represents an error from the Streamable HTTP transport.
+ *
+ * @property code HTTP status code associated with the error, or `null` if unavailable
  */
 public class StreamableHttpError(public val code: Int? = null, message: String? = null) :
     Exception("Streamable HTTP error: $message")
@@ -66,6 +68,9 @@ private sealed interface ConnectResult {
  * Client transport for Streamable HTTP: this implements the MCP Streamable HTTP transport specification.
  * It will connect to a server using HTTP POST for sending messages and HTTP GET with Server-Sent Events
  * for receiving messages.
+ *
+ * @property sessionId session identifier assigned by the server after initialization, or `null` before connection
+ * @property protocolVersion MCP protocol version negotiated with the server, or `null` before connection
  */
 @Suppress("TooManyFunctions")
 public class StreamableHttpClientTransport(

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")