Merge remote-tracking branch 'origin/kpavlov/JSONRPCRequest-constructors' into kpavlov/JSONRPCRequest-constructors

Author: kpavlov

.github/workflows/build.yml

@@ -59,14 +59,14 @@ jobs:
 
       - name: Upload Reports
         if: ${{ !cancelled() }}
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v5
         with:
           name: reports
           path: |
             **/build/reports/
 
       - name: Publish Test Report
-        uses: mikepenz/action-junit-report@v5
+        uses: mikepenz/action-junit-report@v6
         if: ${{ !cancelled() }} # always run even if the previous step fails
         with:
           report_paths: '**/test-results/**/TEST-*.xml'

.github/workflows/samples.yml

@@ -51,7 +51,7 @@ jobs:
 
       - name: Upload Reports
         if: ${{ !cancelled() }}
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v5
         with:
           name: reports-${{ matrix.sample }}
           path: |

.gitignore

@@ -21,6 +21,7 @@ out/
 
 ### Kotlin ###
 .kotlin
+kotlin-js-store
 yarn.lock
 
 ### Eclipse ###

AGENTS.md

@@ -0,0 +1,95 @@
+# kotlin-mcp-sdk
+
+MCP Kotlin SDK — Kotlin Multiplatform implementation of the Model Context Protocol.
+
+## Repository Layout
+- `kotlin-sdk-core`: Core protocol types, transport abstractions, WebSocket implementation
+- `kotlin-sdk-client`: Client transports (STDIO, SSE, StreamableHttp, WebSocket)
+- `kotlin-sdk-server`: Server transports + Ktor integration (STDIO, SSE, WebSocket)
+- `kotlin-sdk`: Umbrella module that aggregates all three above
+- `kotlin-sdk-test`: Shared test utilities
+- `samples/`: Three sample projects (composite builds)
+
+## General Guidance
+- Avoid changing public API signatures. Run `./gradlew apiCheck` before every commit.
+- **Explicit API mode** is strict: all public APIs must have explicit visibility modifiers and return types.
+- Anything under an `internal` directory is not part of the public API and may change freely.
+- Package structure follows: `io.modelcontextprotocol.kotlin.sdk.*`
+- The SDK targets Kotlin 2.2+ and JVM 1.8+ as minimum.
+
+## Building and Testing
+1. Build the project:
+   ```bash
+   ./gradlew build
+   ```
+2. Run tests. To save time, run only the module you changed:
+   ```bash
+   ./gradlew :kotlin-sdk-core:test
+   ./gradlew :kotlin-sdk-client:test
+   ./gradlew :kotlin-sdk-server:test
+   ```
+3. For platform-specific tests:
+   ```bash
+   ./gradlew jsTest
+   ./gradlew wasmJsTest
+   ```
+4. Check binary compatibility (required before commit):
+   ```bash
+   ./gradlew apiCheck
+   ```
+5. If you intentionally changed public APIs, update the API dump:
+   ```bash
+   ./gradlew apiDump
+   ```
+
+## Tests
+- All tests for each module are located in `src/commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/`
+- Platform-specific tests go in `src/jvmTest/`, `src/jsTest/`, etc.
+- Use Kotest assertions (`shouldBe`, `shouldContain`, etc.) for readable test failures.
+- Use `shouldMatchJson` from Kotest for JSON validation.
+- Mock Ktor HTTP clients using `MockEngine` from `io.ktor:ktor-client-mock`.
+- Always add tests for new features or bug fixes, even if not explicitly requested.
+
+## Code Conventions
+
+### Multiplatform Patterns
+- Use `expect`/`actual` pattern for platform-specific implementations in `utils.*` files.
+- Test changes on JVM first, then verify platform-specific behavior if needed.
+- Supported targets: JVM (1.8+), JS/Wasm, iOS, watchOS, tvOS.
+
+### Serialization
+- Use Kotlinx Serialization with explicit `@Serializable` annotations.
+- Custom serializers should be registered in the companion object.
+- JSON config is defined in `McpJson.kt` — use it consistently.
+
+### Concurrency and State
+- Use `kotlinx.atomicfu` for thread-safe operations across platforms.
+- Prefer coroutines over callbacks where possible.
+- Transport implementations extend `AbstractTransport` for consistent callback management.
+
+### Error Handling
+- Use sealed classes for representing different result states.
+- Map errors to JSON-RPC error codes in protocol handlers.
+- Log errors using `io.github.oshai.kotlinlogging.KotlinLogging`.
+
+### Logging
+- Use `KotlinLogging.logger {}` for structured logging.
+- Never log sensitive data (credentials, tokens).
+
+## Pull Requests
+- Base all PRs on the `main` branch.
+- PR title format: Brief description of the change
+- Include in PR description:
+  - **What changed?**
+  - **Why? Motivation and context**
+  - **Breaking changes?** (if any)
+- Run `./gradlew apiCheck` before submitting.
+- Link PR to related issue (except for minor docs/typo fixes).
+- Follow [Kotlin Coding Conventions](https://kotlinlang.org/docs/reference/coding-conventions.html).
+
+## Review Checklist
+- `./gradlew apiCheck` must pass.
+- `./gradlew test` must succeed for affected modules.
+- New tests added for any new feature or bug fix.
+- Documentation updated for user-facing changes.
+- No breaking changes to public APIs without discussion.

gradle.properties

@@ -14,4 +14,4 @@ kotlin.mpp.enableCInteropCommonization=true
 kotlin.native.ignoreDisabledTargets=true
 
 group=io.modelcontextprotocol
-version=0.7.4-SNAPSHOT
+version=0.7.4

gradle/libs.versions.toml

@@ -1,7 +1,7 @@
 [versions]
 # plugins version
-kotlin = "2.2.10"
-dokka = "2.0.0"
+kotlin = "2.2.21"
+dokka = "2.1.0"
 atomicfu = "0.29.0"
 ktlint = "13.1.0"
 kover = "0.9.3"
@@ -14,18 +14,13 @@ serialization = "1.9.0"
 collections-immutable = "0.4.0"
 coroutines = "1.10.2"
 kotlinx-io = "0.8.0"
-ktor = "3.3.0"
+ktor = "3.2.3"
 logging = "7.0.13"
 slf4j = "2.0.17"
 kotest = "6.0.4"
 awaitility = "4.3.0"
 mokksy = "0.6.1"
 
-# Samples
-mcp-kotlin = "0.7.3"
-anthropic = "2.9.0"
-shadow = "9.2.2"
-
 [libraries]
 # Plugins
 kotlin-gradle = { module = "org.jetbrains.kotlin:kotlin-gradle-plugin", version.ref = "kotlin" }
@@ -47,9 +42,7 @@ ktor-bom = { group = "io.ktor", name = "ktor-bom", version.ref = "ktor" }
 ktor-client-core = { group = "io.ktor", name = "ktor-client-core", version.ref = "ktor" }
 ktor-client-logging = { group = "io.ktor", name = "ktor-client-logging"}
 ktor-client-apache5 = { group = "io.ktor", name = "ktor-client-apache5" }
-ktor-client-okhttp = { group = "io.ktor", name = "ktor-client-okhttp" }
 ktor-server-sse = { group = "io.ktor", name = "ktor-server-sse", version.ref = "ktor" }
-ktor-server-netty = { group = "io.ktor", name = "ktor-server-netty" }
 ktor-server-websockets = { group = "io.ktor", name = "ktor-server-websockets", version.ref = "ktor" }
 ktor-server-core = { group = "io.ktor", name = "ktor-server-core", version.ref = "ktor" }
 
@@ -67,19 +60,8 @@ netty-bom = { group = "io.netty", name = "netty-bom", version.ref = "netty" }
 # Samples
 ktor-client-cio = { group = "io.ktor", name = "ktor-client-cio", version.ref = "ktor" }
 ktor-server-cio = { group = "io.ktor", name = "ktor-server-cio", version.ref = "ktor" }
-mcp-kotlin-client = { group = "io.modelcontextprotocol", name = "kotlin-sdk-client", version.ref = "mcp-kotlin" }
-mcp-kotlin-server = { group = "io.modelcontextprotocol", name = "kotlin-sdk-server", version.ref = "mcp-kotlin" }
-anthropic-java = { group = "com.anthropic", name = "anthropic-java", version.ref = "anthropic" }
-ktor-client-content-negotiation = { group = "io.ktor", name = "ktor-client-content-negotiation", version.ref = "ktor" }
-ktor-serialization-kotlinx-json = { group = "io.ktor", name = "ktor-serialization-kotlinx-json", version.ref = "ktor" }
 
 [plugins]
 kotlinx-binary-compatibility-validator = { id = "org.jetbrains.kotlinx.binary-compatibility-validator", version.ref = "binaryCompatibilityValidatorPlugin" }
 ktlint = { id = "org.jlleitschuh.gradle.ktlint", version.ref = "ktlint" }
 kover = { id = "org.jetbrains.kotlinx.kover", version.ref = "kover" }
-
-# Samples
-kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }
-kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }
-kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }
-shadow = { id = "com.gradleup.shadow", version.ref = "shadow" }

kotlin-sdk-client/build.gradle.kts

@@ -43,6 +43,7 @@ kotlin {
                 implementation(kotlin("test"))
                 implementation(dependencies.platform(libs.ktor.bom))
                 implementation(libs.ktor.client.mock)
+                implementation(libs.ktor.server.websockets)
                 implementation(libs.kotlinx.coroutines.test)
                 implementation(libs.ktor.client.logging)
             }

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

@@ -315,7 +315,7 @@ public open class Client(private val clientInfo: Implementation, options: Client
      * @throws IllegalStateException If the server does not support logging.
      */
     public suspend fun setLoggingLevel(level: LoggingLevel, options: RequestOptions? = null): EmptyRequestResult =
-        request<EmptyRequestResult>(SetLevelRequest(level), options)
+        request(SetLevelRequest(level), options)
 
     /**
      * Retrieves a prompt by name from the server.

kotlin-sdk-client/src/commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/client/StreamableHttpClientTransportTest.kt

@@ -18,7 +18,6 @@ import io.modelcontextprotocol.kotlin.sdk.JSONRPCNotification
 import io.modelcontextprotocol.kotlin.sdk.JSONRPCRequest
 import io.modelcontextprotocol.kotlin.sdk.shared.McpJson
 import kotlinx.coroutines.Dispatchers
-import kotlinx.coroutines.TimeoutCancellationException
 import kotlinx.coroutines.delay
 import kotlinx.coroutines.test.runTest
 import kotlinx.coroutines.withContext
@@ -29,9 +28,9 @@ import kotlinx.serialization.json.buildJsonObject
 import kotlin.test.Ignore
 import kotlin.test.Test
 import kotlin.test.assertEquals
+import kotlin.test.assertFailsWith
 import kotlin.test.assertNull
 import kotlin.test.assertTrue
-import kotlin.test.fail
 import kotlin.time.Duration.Companion.seconds
 
 class StreamableHttpClientTransportTest {
@@ -404,26 +403,18 @@ class StreamableHttpClientTransportTest {
             ),
         )
 
-        runCatching {
+        try {
             // Real time-keeping is needed; otherwise Protocol will always throw TimeoutCancellationException in tests
-            withContext(Dispatchers.Default.limitedParallelism(1)) {
-                withTimeout(5.seconds) {
-                    client.connect(transport)
-                }
-            }
-        }.onSuccess {
-            fail("Expected client.connect to fail on invalid JSON response")
-        }.onFailure { e ->
-            when (e) {
-                is TimeoutCancellationException -> fail("Client connect caused a hang", e)
-
-                is IllegalStateException -> {
-                    // Expected behavior: connect finishes and fails with an exception.
+            assertFailsWith<IllegalStateException>(
+                message = "Expected client.connect to fail on invalid JSON response",
+            ) {
+                withContext(Dispatchers.Default.limitedParallelism(1)) {
+                    withTimeout(5.seconds) {
+                        client.connect(transport)
+                    }
                 }
-
-                else -> fail("Unexpected exception during client.connect", e)
             }
-        }.also {
+        } finally {
             transport.close()
         }
     }

kotlin-sdk-core/build.gradle.kts

@@ -7,7 +7,7 @@ plugins {
     id("mcp.publishing")
     id("mcp.dokka")
     alias(libs.plugins.kotlinx.binary.compatibility.validator)
-    id("org.openapi.generator") version "7.16.0"
+    id("org.openapi.generator") version "7.17.0"
 }
 
 /*
@@ -113,8 +113,8 @@ kotlin {
                 api(libs.kotlinx.serialization.json)
                 api(libs.kotlinx.coroutines.core)
                 api(libs.kotlinx.io.core)
-                api(libs.ktor.server.websockets)
                 api(libs.kotlinx.collections.immutable)
+                implementation(libs.ktor.server.websockets)
                 implementation(libs.kotlin.logging)
             }
         }