Merge branch 'main' into dependabot/gradle/kotlin-2.2.20

kpavlov · web-flow · commit c42e7e5eca5b · 2025-10-10T13:21:45.000+02:00
diff --git a/.github/workflows/apidocs.yaml b/.github/workflows/apidocs.yaml
@@ -33,7 +33,7 @@ jobs:
           cache: gradle
 
       - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@v4
+        uses: gradle/actions/setup-gradle@v5
 
       - name: Generate Dokka Site
         run: |-
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -28,7 +28,7 @@ jobs:
           distribution: 'temurin'
 
       - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@v4
+        uses: gradle/actions/setup-gradle@v5
         with:
           add-job-summary: 'always'
           cache-read-only: true
diff --git a/.github/workflows/gradle-publish.yml b/.github/workflows/gradle-publish.yml
@@ -31,7 +31,7 @@ jobs:
           distribution: 'temurin'
 
       - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@v4
+        uses: gradle/actions/setup-gradle@v5
 
       - name: Clean Build with Gradle
         run: ./gradlew clean build
diff --git a/README.md b/README.md
@@ -112,7 +112,9 @@ val server = Server(
             )
         )
     )
-)
+){ 
+    "This server provides example resources and demonstrates MCP capabilities." 
+}
 
 // Add a resource
 server.addResource(
@@ -156,8 +158,10 @@ fun Application.module() {
                     prompts = ServerCapabilities.Prompts(listChanged = null),
                     resources = ServerCapabilities.Resources(subscribe = null, listChanged = null)
                 )
-            )
-        )
+            ),
+        ) { 
+            "This SSE server provides prompts and resources via Server-Sent Events."
+        }
     }
 }
 ```
@@ -184,8 +188,10 @@ fun Application.module() {
                             prompts = ServerCapabilities.Prompts(listChanged = null),
                             resources = ServerCapabilities.Resources(subscribe = null, listChanged = null)
                         )
-                    )
-                )
+                    ),
+                ) {
+                    "Connect via SSE to interact with this MCP server."
+                }
             }
         }
     }
diff --git a/build.gradle.kts b/build.gradle.kts
@@ -33,10 +33,18 @@ dokka {
     }
 }
 
+ktlint {
+    filter {
+        exclude("**/generated*/**")
+    }
+}
+
 kover {
     reports {
         filters {
             includes.classes("io.modelcontextprotocol.kotlin.sdk.*")
+            excludes.classes("io.modelcontextprotocol.kotlin.sdk.models.*") // temporary
+            excludes.classes("io.modelcontextprotocol.kotlin.sdk.models.infrastructure.*") // generated
         }
         total {
             log {
diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml
@@ -48,6 +48,7 @@ ktor-server-core = { group = "io.ktor", name = "ktor-server-core", version.ref =
 
 # Testing
 awaitility = { group = "org.awaitility", name = "awaitility-kotlin", version.ref = "awaitility" }
+kotest-assertions-core = { group = "io.kotest", name = "kotest-assertions-core", version.ref = "kotest" }
 kotest-assertions-json = { group = "io.kotest", name = "kotest-assertions-json", version.ref = "kotest" }
 kotlinx-coroutines-test = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-test", version.ref = "coroutines" }
 ktor-client-mock = { group = "io.ktor", name = "ktor-client-mock", version.ref = "ktor" }
diff --git a/kotlin-sdk-client/api/kotlin-sdk-client.api b/kotlin-sdk-client/api/kotlin-sdk-client.api
@@ -17,6 +17,7 @@ public class io/modelcontextprotocol/kotlin/sdk/client/Client : io/modelcontextp
 	public final fun getPrompt (Lio/modelcontextprotocol/kotlin/sdk/GetPromptRequest;Lio/modelcontextprotocol/kotlin/sdk/shared/RequestOptions;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public static synthetic fun getPrompt$default (Lio/modelcontextprotocol/kotlin/sdk/client/Client;Lio/modelcontextprotocol/kotlin/sdk/GetPromptRequest;Lio/modelcontextprotocol/kotlin/sdk/shared/RequestOptions;Lkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
 	public final fun getServerCapabilities ()Lio/modelcontextprotocol/kotlin/sdk/ServerCapabilities;
+	public final fun getServerInstructions ()Ljava/lang/String;
 	public final fun getServerVersion ()Lio/modelcontextprotocol/kotlin/sdk/Implementation;
 	public final fun listPrompts (Lio/modelcontextprotocol/kotlin/sdk/ListPromptsRequest;Lio/modelcontextprotocol/kotlin/sdk/shared/RequestOptions;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public static synthetic fun listPrompts$default (Lio/modelcontextprotocol/kotlin/sdk/client/Client;Lio/modelcontextprotocol/kotlin/sdk/ListPromptsRequest;Lio/modelcontextprotocol/kotlin/sdk/shared/RequestOptions;Lkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
diff --git a/kotlin-sdk-client/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/Client.kt b/kotlin-sdk-client/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/Client.kt
@@ -91,6 +91,14 @@ public open class Client(private val clientInfo: Implementation, options: Client
     public var serverCapabilities: ServerCapabilities? = null
         private set
 
+    /**
+     * Optional human-readable instructions or description from the server.
+     *
+     * @return Instructions provided by the server, or `null` if none were given or initialization is not yet complete.
+     */
+    public var serverInstructions: String? = null
+        private set
+
     /**
      * Retrieves the server's reported version information after initialization.
      *
@@ -154,6 +162,7 @@ public open class Client(private val clientInfo: Implementation, options: Client
 
             serverCapabilities = result.capabilities
             serverVersion = result.serverInfo
+            serverInstructions = result.instructions
 
             notification(InitializedNotification())
         } catch (error: Throwable) {
diff --git a/kotlin-sdk-core/.openapi-generator-ignore b/kotlin-sdk-core/.openapi-generator-ignore
@@ -0,0 +1,29 @@
+# OpenAPI Generator Ignore
+# Generated by openapi-generator https://github.com/openapitools/openapi-generator
+
+# Use this file to prevent files from being overwritten by the generator.
+# The patterns follow closely to .gitignore or .dockerignore.
+
+# As an example, the C# client generator defines ApiClient.cs.
+# You can make changes and tell OpenAPI Generator to ignore just this file by uncommenting the following line:
+**/auth/**
+**/infrastructure/**
+!**/Base64ByteArray.kt
+!**/Bytes.kt
+
+
+## Exclude Models which are causing problems
+**/JSONRPCResponse.kt
+**/Result.kt
+**/ListToolsResult.kt
+**/InitializeRequest.kt
+**/InitializeResult.kt
+**/ServerCapabilities.kt
+**/InitializeRequestParams.kt
+**/CreateMessageRequest.kt
+**/CreateMessageRequestParams.kt
+**/ClientCapabilities.kt
+**/Tool.kt
+**/ToolInputSchema.kt
+**/ToolOutputSchema.kt
+
diff --git a/kotlin-sdk-core/api/kotlin-sdk-core.api b/kotlin-sdk-core/api/kotlin-sdk-core.api
@@ -975,16 +975,18 @@ public final class io/modelcontextprotocol/kotlin/sdk/InitializeRequest$Companio
 
 public final class io/modelcontextprotocol/kotlin/sdk/InitializeResult : io/modelcontextprotocol/kotlin/sdk/ServerResult {
 	public static final field Companion Lio/modelcontextprotocol/kotlin/sdk/InitializeResult$Companion;
-	public fun <init> (Ljava/lang/String;Lio/modelcontextprotocol/kotlin/sdk/ServerCapabilities;Lio/modelcontextprotocol/kotlin/sdk/Implementation;Lkotlinx/serialization/json/JsonObject;)V
-	public synthetic fun <init> (Ljava/lang/String;Lio/modelcontextprotocol/kotlin/sdk/ServerCapabilities;Lio/modelcontextprotocol/kotlin/sdk/Implementation;Lkotlinx/serialization/json/JsonObject;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public fun <init> (Ljava/lang/String;Lio/modelcontextprotocol/kotlin/sdk/ServerCapabilities;Lio/modelcontextprotocol/kotlin/sdk/Implementation;Ljava/lang/String;Lkotlinx/serialization/json/JsonObject;)V
+	public synthetic fun <init> (Ljava/lang/String;Lio/modelcontextprotocol/kotlin/sdk/ServerCapabilities;Lio/modelcontextprotocol/kotlin/sdk/Implementation;Ljava/lang/String;Lkotlinx/serialization/json/JsonObject;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public final fun component1 ()Ljava/lang/String;
 	public final fun component2 ()Lio/modelcontextprotocol/kotlin/sdk/ServerCapabilities;
 	public final fun component3 ()Lio/modelcontextprotocol/kotlin/sdk/Implementation;
-	public final fun component4 ()Lkotlinx/serialization/json/JsonObject;
-	public final fun copy (Ljava/lang/String;Lio/modelcontextprotocol/kotlin/sdk/ServerCapabilities;Lio/modelcontextprotocol/kotlin/sdk/Implementation;Lkotlinx/serialization/json/JsonObject;)Lio/modelcontextprotocol/kotlin/sdk/InitializeResult;
-	public static synthetic fun copy$default (Lio/modelcontextprotocol/kotlin/sdk/InitializeResult;Ljava/lang/String;Lio/modelcontextprotocol/kotlin/sdk/ServerCapabilities;Lio/modelcontextprotocol/kotlin/sdk/Implementation;Lkotlinx/serialization/json/JsonObject;ILjava/lang/Object;)Lio/modelcontextprotocol/kotlin/sdk/InitializeResult;
+	public final fun component4 ()Ljava/lang/String;
+	public final fun component5 ()Lkotlinx/serialization/json/JsonObject;
+	public final fun copy (Ljava/lang/String;Lio/modelcontextprotocol/kotlin/sdk/ServerCapabilities;Lio/modelcontextprotocol/kotlin/sdk/Implementation;Ljava/lang/String;Lkotlinx/serialization/json/JsonObject;)Lio/modelcontextprotocol/kotlin/sdk/InitializeResult;
+	public static synthetic fun copy$default (Lio/modelcontextprotocol/kotlin/sdk/InitializeResult;Ljava/lang/String;Lio/modelcontextprotocol/kotlin/sdk/ServerCapabilities;Lio/modelcontextprotocol/kotlin/sdk/Implementation;Ljava/lang/String;Lkotlinx/serialization/json/JsonObject;ILjava/lang/Object;)Lio/modelcontextprotocol/kotlin/sdk/InitializeResult;
 	public fun equals (Ljava/lang/Object;)Z
 	public final fun getCapabilities ()Lio/modelcontextprotocol/kotlin/sdk/ServerCapabilities;
+	public final fun getInstructions ()Ljava/lang/String;
 	public final fun getProtocolVersion ()Ljava/lang/String;
 	public final fun getServerInfo ()Lio/modelcontextprotocol/kotlin/sdk/Implementation;
 	public fun get_meta ()Lkotlinx/serialization/json/JsonObject;
diff --git a/kotlin-sdk-core/build.gradle.kts b/kotlin-sdk-core/build.gradle.kts
@@ -7,21 +7,80 @@ plugins {
     id("mcp.publishing")
     id("mcp.dokka")
     alias(libs.plugins.kotlinx.binary.compatibility.validator)
+    id("org.openapi.generator") version "7.15.0"
+}
+
+/*
+tasks.withType<KotlinCompilationTask<*>>().configureEach {
+    dependsOn(tasks.openApiGenerate)
+}
+
+tasks.named("runKtlintCheckOverCommonMainSourceSet") {
+    dependsOn(tasks.openApiGenerate)
+}
+
+// Also ensure it runs before other relevant tasks
+tasks.withType<DokkaGenerateTask>().configureEach {
+    dependsOn(tasks.openApiGenerate)
+}
+
+tasks.withType<Task>().configureEach {
+    if (name.lowercase().contains("sourcesjar")) {
+        dependsOn(tasks.openApiGenerate)
+    }
+}
+ */
+
+openApiGenerate {
+    val schemaVersion = "2025-03-26" // or "2025-06-18" or "draft"
+    val schemaUrl =
+//        "https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/refs/heads/main/schema/$schemaVersion/schema.json"
+        "https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/refs/tags/$schemaVersion/schema/$schemaVersion/schema.json"
+    generatorName = "kotlin"
+    remoteInputSpec = schemaUrl
+    outputDir = layout.buildDirectory.dir("generated-sources/openapi").get().asFile.absolutePath
+    packageName = "io.modelcontextprotocol.kotlin.sdk.models"
+    modelPackage = "io.modelcontextprotocol.kotlin.sdk.models"
+    apiPackage = "io.modelcontextprotocol.kotlin.sdk.api"
+    generateModelTests = false
+    generateModelDocumentation = false
+    cleanupOutput = false
+    skipValidateSpec = true // do not validate spec
+    library = "multiplatform"
+    ignoreFileOverride = "${layout.projectDirectory}/.openapi-generator-ignore"
+    globalProperties.set(
+        mapOf(
+            "supportingFiles" to "",
+            "models" to "", // or generate all models
+        ),
+    )
+    configOptions.set(
+        mapOf(
+            "omitGradleWrapper" to "true",
+            "enumPropertyNaming" to "UPPERCASE",
+            "dateLibrary" to "kotlinx-datetime",
+            "explicitApi" to "true",
+            "modelMutable" to "false",
+        ),
+    )
 }
 
 // Generation library versions
 val generateLibVersion by tasks.registering {
     val outputDir = layout.buildDirectory.dir("generated-sources/libVersion")
     outputs.dir(outputDir)
 
+    // Capture version at configuration time to avoid configuration cache issues
+    val projectVersion = project.version.toString()
+
     doLast {
         val sourceFile = outputDir.get().file("io/modelcontextprotocol/kotlin/sdk/LibVersion.kt").asFile
         sourceFile.parentFile.mkdirs()
         sourceFile.writeText(
             """
             package io.modelcontextprotocol.kotlin.sdk
 
-            public const val LIB_VERSION: String = "${project.version}"
+            public const val LIB_VERSION: String = "$projectVersion"
             
             """.trimIndent(),
         )
@@ -63,6 +122,7 @@ kotlin {
         commonTest {
             dependencies {
                 implementation(kotlin("test"))
+                implementation(libs.kotest.assertions.core)
                 implementation(libs.kotest.assertions.json)
             }
         }
diff --git a/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types.kt b/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types.kt
@@ -512,6 +512,10 @@ public data class InitializeResult(
     val protocolVersion: String = LATEST_PROTOCOL_VERSION,
     val capabilities: ServerCapabilities = ServerCapabilities(),
     val serverInfo: Implementation,
+    /**
+     * Optional instructions from the server to the client about how to use this server.
+     */
+    val instructions: String? = null,
     override val _meta: JsonObject = EmptyJsonObject,
 ) : ServerResult
 
diff --git a/kotlin-sdk-core/src/commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/TypesTest.kt b/kotlin-sdk-core/src/commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/TypesTest.kt
@@ -394,4 +394,63 @@ class TypesTest {
         assertEquals("id", request.argument.name)
         assertEquals("123", request.argument.value)
     }
+
+    // InitializeResult Tests
+    @Test
+    fun `should create InitializeResult with default instructions`() {
+        val serverInfo = Implementation(name = "test-server", version = "1.0.0")
+        val result = InitializeResult(
+            serverInfo = serverInfo,
+        )
+
+        assertEquals(LATEST_PROTOCOL_VERSION, result.protocolVersion)
+        assertEquals(serverInfo, result.serverInfo)
+        assertEquals(null, result.instructions)
+    }
+
+    @Test
+    fun `should create InitializeResult with custom instructions`() {
+        val serverInfo = Implementation(name = "test-server", version = "1.0.0")
+        val instructions = "Use this server to perform calculations. Call the 'add' tool to add numbers."
+        val result = InitializeResult(
+            serverInfo = serverInfo,
+            instructions = instructions,
+        )
+
+        assertEquals(LATEST_PROTOCOL_VERSION, result.protocolVersion)
+        assertEquals(serverInfo, result.serverInfo)
+        assertEquals(instructions, result.instructions)
+    }
+
+    @Test
+    fun `should serialize and deserialize InitializeResult with instructions`() {
+        val serverInfo = Implementation(name = "test-server", version = "1.0.0")
+        val instructions = "This server provides file system access. Use the 'read' tool to read files."
+        val result = InitializeResult(
+            serverInfo = serverInfo,
+            instructions = instructions,
+        )
+
+        val json = McpJson.encodeToString(result)
+        val decoded = McpJson.decodeFromString<InitializeResult>(json)
+
+        assertEquals(LATEST_PROTOCOL_VERSION, decoded.protocolVersion)
+        assertEquals(serverInfo, decoded.serverInfo)
+        assertEquals(instructions, decoded.instructions)
+    }
+
+    @Test
+    fun `should serialize and deserialize InitializeResult without instructions`() {
+        val serverInfo = Implementation(name = "test-server", version = "1.0.0")
+        val result = InitializeResult(
+            serverInfo = serverInfo,
+        )
+
+        val json = McpJson.encodeToString(result)
+        val decoded = McpJson.decodeFromString<InitializeResult>(json)
+
+        assertEquals(LATEST_PROTOCOL_VERSION, decoded.protocolVersion)
+        assertEquals(serverInfo, decoded.serverInfo)
+        assertEquals(null, decoded.instructions)
+    }
 }
diff --git a/kotlin-sdk-core/src/commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/models/ProgressNotificationsTest.kt b/kotlin-sdk-core/src/commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/models/ProgressNotificationsTest.kt
diff --git a/kotlin-sdk-server/api/kotlin-sdk-server.api b/kotlin-sdk-server/api/kotlin-sdk-server.api
diff --git a/kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/Server.kt b/kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/Server.kt
diff --git a/kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/ServerSession.kt b/kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/ServerSession.kt
diff --git a/kotlin-sdk-test/src/jvmTest/kotlin/io/modelcontextprotocol/kotlin/sdk/server/ServerTest.kt b/kotlin-sdk-test/src/jvmTest/kotlin/io/modelcontextprotocol/kotlin/sdk/server/ServerTest.kt
diff --git a/samples/kotlin-mcp-server/src/commonMain/kotlin/server.kt b/samples/kotlin-mcp-server/src/commonMain/kotlin/server.kt

Original file line number	Diff line number	Diff line change
`@@ -112,7 +112,9 @@ val server = Server(`
`112`	`112`	`)`
`113`	`113`	`)`
`114`	`114`	`)`
`115`		`-)`
	`115`	`+){`
	`116`	`+ "This server provides example resources and demonstrates MCP capabilities."`
	`117`	`+}`
`116`	`118`
`117`	`119`	`// Add a resource`
`118`	`120`	`server.addResource(`
`@@ -156,8 +158,10 @@ fun Application.module() {`
`156`	`158`	`prompts = ServerCapabilities.Prompts(listChanged = null),`
`157`	`159`	`resources = ServerCapabilities.Resources(subscribe = null, listChanged = null)`
`158`	`160`	`)`
`159`		`- )`
`160`		`- )`
	`161`	`+ ),`
	`162`	`+ ) {`
	`163`	`+ "This SSE server provides prompts and resources via Server-Sent Events."`
	`164`	`+ }`
`161`	`165`	`}`
`162`	`166`	`}`
`163`	`167`	```
`@@ -184,8 +188,10 @@ fun Application.module() {`
`184`	`188`	`prompts = ServerCapabilities.Prompts(listChanged = null),`
`185`	`189`	`resources = ServerCapabilities.Resources(subscribe = null, listChanged = null)`
`186`	`190`	`)`
`187`		`- )`
`188`		`- )`
	`191`	`+ ),`
	`192`	`+ ) {`
	`193`	`+ "Connect via SSE to interact with this MCP server."`
	`194`	`+ }`
`189`	`195`	`}`
`190`	`196`	`}`
`191`	`197`	`}`
Original file line number	Diff line number	Diff line change
`@@ -33,10 +33,18 @@ dokka {`
`33`	`33`	`}`
`34`	`34`	`}`
`35`	`35`
	`36`	`+ktlint {`
	`37`	`+ filter {`
	`38`	`+ exclude("*/generated/**")`
	`39`	`+ }`
	`40`	`+}`
	`41`	`+`
`36`	`42`	`kover {`
`37`	`43`	`reports {`
`38`	`44`	`filters {`
`39`	`45`	`includes.classes("io.modelcontextprotocol.kotlin.sdk.*")`
	`46`	`+ excludes.classes("io.modelcontextprotocol.kotlin.sdk.models.*") // temporary`
	`47`	`+ excludes.classes("io.modelcontextprotocol.kotlin.sdk.models.infrastructure.*") // generated`
`40`	`48`	`}`
`41`	`49`	`total {`
`42`	`50`	`log {`