Merge remote-tracking branch 'origin/main' into 158-support-resource-links

Author: dstibbe

.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: |-

.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

.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

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."
+                }
             }
         }
     }

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 {

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

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;

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,12 +162,15 @@ public open class Client(private val clientInfo: Implementation, options: Client
 
             serverCapabilities = result.capabilities
             serverVersion = result.serverInfo
+            serverInstructions = result.instructions
 
             notification(InitializedNotification())
         } catch (error: Throwable) {
+            logger.error(error) { "Failed to initialize client: ${error.message}" }
             close()
+
             if (error !is CancellationException) {
-                throw IllegalStateException("Error connecting to transport: ${error.message}")
+                throw IllegalStateException("Error connecting to transport: ${error.message}", error)
             }
 
             throw error

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

@@ -1,5 +1,6 @@
 package io.modelcontextprotocol.kotlin.sdk.client
 
+import io.github.oshai.kotlinlogging.KotlinLogging
 import io.ktor.client.HttpClient
 import io.ktor.client.plugins.sse.ClientSSESession
 import io.ktor.client.plugins.sse.sseSession
@@ -46,6 +47,8 @@ public class SseClientTransport(
     private val reconnectionTime: Duration? = null,
     private val requestBuilder: HttpRequestBuilder.() -> Unit = {},
 ) : AbstractTransport() {
+    private val logger = KotlinLogging.logger {}
+
     private val initialized: AtomicBoolean = AtomicBoolean(false)
     private val endpoint = CompletableDeferred<String>()
 
@@ -111,6 +114,8 @@ public class SseClientTransport(
                 val text = response.bodyAsText()
                 error("Error POSTing to endpoint (HTTP ${response.status}): $text")
             }
+
+            logger.debug { "Client successfully sent message via SSE $endpoint" }
         } catch (e: Throwable) {
             _onError(e)
             throw e
@@ -158,6 +163,7 @@ public class SseClientTransport(
             val path = if (eventData.startsWith("/")) eventData.substring(1) else eventData
             val endpointUrl = Url("$baseUrl/$path")
             endpoint.complete(endpointUrl.toString())
+            logger.debug { "Client connected to endpoint: $endpointUrl" }
         } catch (e: Throwable) {
             _onError(e)
             endpoint.completeExceptionally(e)

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

@@ -1,5 +1,6 @@
 package io.modelcontextprotocol.kotlin.sdk.client
 
+import io.github.oshai.kotlinlogging.KotlinLogging
 import io.ktor.client.HttpClient
 import io.ktor.client.plugins.websocket.webSocketSession
 import io.ktor.client.request.HttpRequestBuilder
@@ -10,6 +11,8 @@ import io.modelcontextprotocol.kotlin.sdk.shared.MCP_SUBPROTOCOL
 import io.modelcontextprotocol.kotlin.sdk.shared.WebSocketMcpTransport
 import kotlin.properties.Delegates
 
+private val logger = KotlinLogging.logger {}
+
 /**
  * Client transport for WebSocket: this will connect to a server over the WebSocket protocol.
  */
@@ -21,6 +24,8 @@ public class WebSocketClientTransport(
     override var session: WebSocketSession by Delegates.notNull()
 
     override suspend fun initializeSession() {
+        logger.debug { "Websocket session initialization started..." }
+
         session = urlString?.let {
             client.webSocketSession(it) {
                 requestBuilder()
@@ -32,5 +37,7 @@ public class WebSocketClientTransport(
 
             header(HttpHeaders.SecWebSocketProtocol, MCP_SUBPROTOCOL)
         }
+
+        logger.debug { "Websocket session initialization finished" }
     }
 }