kotlin-sdk/AGENTS.md

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:

   ./gradlew build
   

2. Run tests. To save time, run only the module you changed:

   ./gradlew :kotlin-sdk-core:test
   ./gradlew :kotlin-sdk-client:test
   ./gradlew :kotlin-sdk-server:test
   

3. For platform-specific tests:

   ./gradlew jsTest
   ./gradlew wasmJsTest
   

4. Check binary compatibility (required before commit):

   ./gradlew apiCheck
   

5. If you intentionally changed public APIs, update the API dump:

   ./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.
• For nullable objects with nested properties, prefer shouldNotBeNull { ... } blocks:

  content.annotations shouldNotBeNull {
      priority shouldBe 1.0
  }
  

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

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.