refactor: Harden detekt setup, address some issues (#507)

# Detekt setup hardeing; address some issues

- Address some detekt findings: missing KDocs, formatting, use `check*`
& `orEmpty()``
- Remove unnecessary KDoc comments from deprecated classes in `types.kt`
- Add Detekt baseline XML files for all modules
- Enforce stricter Detekt rules by setting `failOnSeverity` from `None`
to `Error`

## Motivation and Context

Detekt is not actually failing the build on violations. This PR is
enabling Detekt to fail on errors. Baseline fines added for historical
issues. Follow-up for #501

## How Has This Been Tested?
Regressions

## Breaking Changes

No breaking changes.

## Types of changes
<!-- What types of changes does your code introduce? Put an `x` in all
the boxes that apply: -->
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] Refactoring
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update

## Checklist
<!-- Go over all the following points, and put an `x` in all the boxes
that apply. -->
- [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
- [ ] I have added or updated documentation as needed
This commit is contained in:
Konstantin Pavlov 2026-02-13 22:17:27 +02:00 • committed by GitHub
commit ed9ad83290
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
8 changed files with 478 additions and 122 deletions

View file

@ -1,16 +1,14 @@
@file:Suppress("FunctionName")
@file:Suppress("FunctionName", "TooManyFunctions")
package io.modelcontextprotocol.kotlin.sdk
import io.modelcontextprotocol.kotlin.sdk.types.ClientCapabilities.Roots
import io.modelcontextprotocol.kotlin.sdk.types.ContentBlock
import io.modelcontextprotocol.kotlin.sdk.types.fromJSON
import io.modelcontextprotocol.kotlin.sdk.types.toJSON
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.JsonElement
import kotlinx.serialization.json.JsonObject
import kotlin.concurrent.atomics.AtomicLong
import kotlin.concurrent.atomics.ExperimentalAtomicApi
import io.modelcontextprotocol.kotlin.sdk.types.ClientCapabilities.Roots as TypesRoots
@Deprecated(
message = "Use `LATEST_PROTOCOL_VERSION` instead",
@ -40,14 +38,6 @@ public val SUPPORTED_PROTOCOL_VERSIONS: List<String> =
)
public const val JSONRPC_VERSION: String = io.modelcontextprotocol.kotlin.sdk.types.JSONRPC_VERSION
@OptIn(ExperimentalAtomicApi::class)
@Deprecated(
message = "Use `REQUEST_MESSAGE_ID` instead",
replaceWith = ReplaceWith("REQUEST_MESSAGE_ID", "io.modelcontextprotocol.kotlin.sdk.types.REQUEST_MESSAGE_ID"),
level = DeprecationLevel.ERROR,
)
private val REQUEST_MESSAGE_ID: AtomicLong = AtomicLong(0L)
/**
* A progress token, used to associate progress notifications with the original request.
* Stores message ID.
@ -81,8 +71,6 @@ public typealias WithMeta = io.modelcontextprotocol.kotlin.sdk.types.WithMeta
/**
* An implementation of [WithMeta] containing custom metadata.
*
* @param _meta The JSON object holding metadata. Defaults to an empty JSON object.
*/
@Deprecated(
message = "This class will be removed. Use `WithMeta` instead",
@ -431,8 +419,6 @@ internal fun JSONRPCRequest.fromJSON(): Request = this.fromJSON()
/**
* A custom request with a specified method.
*
* @param method The method associated with the request.
*/
@Deprecated(
message = "Use `CustomRequest` instead",
@ -489,8 +475,6 @@ public typealias RequestResult = io.modelcontextprotocol.kotlin.sdk.types.Reques
/**
* An empty result for a request containing optional metadata.
*
* @param _meta Additional metadata for the response. Defaults to an empty JSON object.
*/
@Deprecated(
message = "Use `EmptyResult` instead",
@ -708,7 +692,8 @@ public object CancelledNotification {
/**
* This notification can be sent by either side to indicate that it is cancelling a previously issued request.
*
* The request SHOULD still be in-flight, but due to communication latency, it is always possible that this notification MAY arrive after the request has already finished.
* The request SHOULD still be in-flight, but due to communication latency, it is always possible that
* this notification MAY arrive after the request has already finished.
*
* This notification indicates that the result will be unused, so any associated processing SHOULD cease.
*
@ -745,6 +730,15 @@ public typealias Implementation = io.modelcontextprotocol.kotlin.sdk.types.Imple
level = DeprecationLevel.ERROR,
)
public object ClientCapabilities {
/**
* Creates an instance of [Roots], representing the client's capability
* to list roots and optionally listen for changes in the roots list.
*
* @param listChanged Optional flag indicating whether the client supports notifications
* for changes to the roots list. If set to true, the client will notify the server when
* roots are added or removed.
* @return A new instance of [Roots] configured with the provided [listChanged] value.
*/
@Deprecated(
message = "Use `ClientCapabilities.Roots` instead",
replaceWith = ReplaceWith(
@ -753,8 +747,7 @@ public object ClientCapabilities {
),
level = DeprecationLevel.ERROR,
)
public fun Roots(listChanged: Boolean? = null): io.modelcontextprotocol.kotlin.sdk.types.ClientCapabilities.Roots =
io.modelcontextprotocol.kotlin.sdk.types.ClientCapabilities.Roots(listChanged)
public fun Roots(listChanged: Boolean? = null): TypesRoots = TypesRoots(listChanged)
}
/**
@ -769,7 +762,7 @@ public object ClientCapabilities {
)
public fun ClientCapabilities(
sampling: JsonObject? = null,
roots: Roots? = null,
roots: TypesRoots? = null,
elicitation: JsonObject? = null,
experimental: JsonObject? = null,
): io.modelcontextprotocol.kotlin.sdk.types.ClientCapabilities =
@ -918,6 +911,7 @@ public object ServerCapabilities {
replaceWith = ReplaceWith("ServerCapabilities", "io.modelcontextprotocol.kotlin.sdk.types.ServerCapabilities"),
level = DeprecationLevel.ERROR,
)
@Suppress("LongParameterList")
public fun ServerCapabilities(
tools: io.modelcontextprotocol.kotlin.sdk.types.ServerCapabilities.Tools? = null,
resources: io.modelcontextprotocol.kotlin.sdk.types.ServerCapabilities.Resources? = null,
@ -1027,9 +1021,6 @@ public sealed interface ProgressBase {
/**
* Represents a progress notification.
*
* @property progress The current progress value.
* @property total The total progress required, if known.
*/
@Deprecated(
message = "Use `Progress` instead",
@ -1117,8 +1108,6 @@ public typealias ResourceContents = io.modelcontextprotocol.kotlin.sdk.types.Res
/**
* Represents the text contents of a resource.
*
* @property text The text of the item. This must only be set if the item can actually be represented as text (not binary data).
*/
@Deprecated(
message = "Use `TextResourceContents` instead",
@ -1129,8 +1118,6 @@ public typealias TextResourceContents = io.modelcontextprotocol.kotlin.sdk.types
/**
* Represents the binary contents of a resource encoded as a base64 string.
*
* @property blob A base64-encoded string representing the binary data of the item.
*/
@Deprecated(
message = "Use `BlobResourceContents` instead",
@ -1278,7 +1265,8 @@ public fun ResourceListChangedNotification(
io.modelcontextprotocol.kotlin.sdk.types.ResourceListChangedNotification(params)
/**
* Sent from the client to request resources/updated notifications from the server whenever a particular resource changes.
* Sent from the client to request resources/updated notifications from the server
* whenever a particular resource changes.
*/
@Deprecated(
message = "Use `SubscribeRequest` instead",
@ -1288,7 +1276,8 @@ public fun ResourceListChangedNotification(
public typealias SubscribeRequest = io.modelcontextprotocol.kotlin.sdk.types.SubscribeRequest
/**
* Sent from the client to request cancellation of resources/updated notifications from the server. This should follow a previous resources/subscribe request.
* Sent from the client to request cancellation of resources/updated notifications from the server.
* This should follow a previous resources/subscribe request.
*/
@Deprecated(
message = "Use `UnsubscribeRequest` instead",
@ -1322,7 +1311,8 @@ public object ResourceUpdatedNotification {
}
/**
* A notification from the server to the client, informing it that a resource has changed and may need to be read again. This should only be sent if the client previously sent a resources/subscribe request.
* A notification from the server to the client, informing it that a resource has changed and may need to be read again.
* This should only be sent if the client previously sent a resources/subscribe request.
*/
@Deprecated(
message = "Use `ResourceUpdatedNotification` instead",
@ -1397,7 +1387,7 @@ public typealias GetPromptRequest = io.modelcontextprotocol.kotlin.sdk.types.Get
replaceWith = ReplaceWith("ContentBlock"),
level = DeprecationLevel.ERROR,
)
public typealias PromptMessageContent = io.modelcontextprotocol.kotlin.sdk.types.ContentBlock
public typealias PromptMessageContent = ContentBlock
/**
* Represents prompt message content that is either text, image or audio.
@ -1610,6 +1600,7 @@ public object Tool {
replaceWith = ReplaceWith("Tool", "io.modelcontextprotocol.kotlin.sdk.types.Tool"),
level = DeprecationLevel.ERROR,
)
@Suppress("LongParameterList", "FunctionParameterNaming")
public fun Tool(
name: String,
inputSchema: io.modelcontextprotocol.kotlin.sdk.types.ToolSchema,
@ -1698,7 +1689,7 @@ public fun CallToolResult(
replaceWith = ReplaceWith("ToolCallResult"),
level = DeprecationLevel.ERROR,
)
@Suppress("DEPRECATION_ERROR")
@Suppress("DEPRECATION_ERROR", "ConstructorParameterNaming")
public class CompatibilityCallToolResult(
public val content: List<PromptMessageContent>,
public val structuredContent: JsonObject? = null,
@ -2250,10 +2241,6 @@ public fun CreateElicitationResult(
/**
* Represents an error specific to the MCP protocol.
*
* @property code The error code.
* @property message The error message.
* @property data Additional error data as a JSON object.
*/
@Deprecated(
message = "Use `McpException` instead",

View file

@ -160,7 +160,8 @@ public class CompleteRequestBuilder @PublishedApi internal constructor() : Reque
}
val reference = requireNotNull(ref) {
"Missing required field 'ref(Reference)'. Use ref(PromptReference(\"name\")) or ref(ResourceTemplateReference(\"uri\"))"
"Missing required field 'ref(Reference)'. Use ref(PromptReference(\"name\")) " +
"or ref(ResourceTemplateReference(\"uri\"))"
}
val params = CompleteRequestParams(argument = argument, ref = reference, context = ctx, meta = meta)

View file

@ -16,8 +16,22 @@ import kotlin.uuid.Uuid
public const val JSONRPC_VERSION: String = "2.0"
/**
* Creates a `RequestId` instance using the provided string value.
*
* @param value The string representation of the request ID. This value is used
* to uniquely identify a request in the JSON-RPC context.
* @return A `RequestId` instance of type `StringId` with the provided string value.
*/
public fun RequestId(value: String): RequestId = RequestId.StringId(value)
/**
* Creates a `RequestId` instance using the given numeric value.
*
* @param value The numeric value to be used for the `RequestId`. This should uniquely
* identify a request when represented as a `NumberId`.
* @return A `RequestId.NumberId` instance encapsulating the provided numeric value.
*/
public fun RequestId(value: Long): RequestId = RequestId.NumberId(value)
/**

View file

@ -24,6 +24,17 @@ public val McpJson: Json by lazy {
}
}
/**
* Converts a [Map] with [String] keys and nullable [Any] values into a [Map] with
* [String] keys and [JsonElement] values.
*
* Each value in the resulting map is derived from the corresponding value
* in the input map, transformed into a [JsonElement]. If the transformation
* fails for any reason, the value is replaced with a [JsonPrimitive] containing
* the original value's `toString` representation.
*
* @return A new map where the values are converted to [JsonElement] instances.
*/
public fun Map<String, Any?>.toJson(): Map<String, JsonElement> = this.mapValues { (_, value) ->
runCatching { convertToJsonElement(value) }
.getOrElse { JsonPrimitive(value.toString()) }
@ -77,7 +88,5 @@ private fun convertToJsonElement(value: Any?): JsonElement = when (value) {
is UByteArray -> buildJsonArray { value.forEach { add(JsonPrimitive(it)) } }
else -> {
JsonPrimitive(value.toString())
}
else -> JsonPrimitive(value.toString())
}

View file

@ -262,7 +262,8 @@ public data class PromptListChangedNotification(override val params: BaseNotific
// ============================================================================
/**
* An optional notification from the server to the client, informing it that the list of resources it can read from has changed.
* An optional notification from the server to the client,
* informing it that the list of resources it can read from has changed.
*
* Servers may issue this without any previous subscription from the client.
* Sent only if the server's [ServerCapabilities.resources] has `listChanged = true`.

View file

@ -22,6 +22,12 @@ public value class RequestMeta(public val json: JsonObject) {
}
}
/**
* Retrieves the value associated with the specified key from the JSON object.
*
* @param key the key whose corresponding value is to be returned
* @return the JsonElement associated with the specified key, or null if the key does not exist
*/
public operator fun get(key: String): JsonElement? = json[key]
}

View file

@ -1,6 +1,7 @@
package io.modelcontextprotocol.kotlin.sdk.types
import io.kotest.assertions.json.shouldEqualJson
import io.kotest.matchers.shouldBe
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.double
import kotlinx.serialization.json.jsonPrimitive
@ -149,7 +150,9 @@ class RequestTest {
val method = custom.method
val customMethod = assertIs<Method.Custom>(method)
assertEquals("extensions/customAction", customMethod.value)
assertEquals("custom-1", custom.params?.meta?.json?.get("progressToken")?.jsonPrimitive?.content)
custom.params?.meta?.json
?.get("progressToken")
?.jsonPrimitive?.content shouldBe "custom-1"
}
@Test

View file

@ -49,12 +49,16 @@ class PingRequestDslTest {
val requestInt = buildPingRequest {
meta { progressToken(123) }
}
requestInt.params?.meta?.json?.get("progressToken")?.jsonPrimitive?.int shouldBe 123
requestInt.params?.meta?.json
?.get("progressToken")
?.jsonPrimitive?.int shouldBe 123
val requestLong = buildPingRequest {
meta { progressToken(456L) }
}
requestLong.params?.meta?.json?.get("progressToken")?.jsonPrimitive?.int shouldBe 456
requestLong.params?.meta?.json
?.get("progressToken")
?.jsonPrimitive?.int shouldBe 456
}
@Test