kotlin-sdk/AGENTS.md

AGENTS: Development Guidelines for AI Contributors

This document is for autonomous agents and AI copilots contributing code to this repository. Follow these rules to keep changes safe, comprehensible, and easy to maintain.

Repository Layout

• kotlin-sdk-core: Core protocol types, transport abstractions, serialization utilities
• 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
• test-utils: Shared test utilities
• integration-test: Integration tests with TypeScript/other implementations
• conformance-test: Protocol conformance tests
• samples/: Sample projects (composite builds)
• Package structure: io.modelcontextprotocol.kotlin.sdk.*
• JVM 11+, Kotlin 2.2+

Prime Directives

1. Tests first, always.
   • Before changing code, identify or add tests that express the desired behavior.
   • Prefer readable, minimal tests over clever ones. Tests are documentation.
2. Keep tests simple and explicit.
   • Arrange/Act/Assert structure; avoid hidden magic and overuse of helpers.
   • Prefer concrete inputs/outputs; avoid randomness and time dependence.
3. Uphold SOLID principles in production code:
   • Single Responsibility: each class/function should do one thing well.
   • Open/Closed: extend via new code, avoid risky edits to stable code paths.
   • Liskov Substitution: honor contracts; keep types substitutable.
   • Interface Segregation: keep abstractions small and focused.
   • Dependency Inversion: depend on abstractions, not concretions.
4. Make the minimal change that satisfies the tests and the issue. Stay focused on a single concern and avoid "drive-by" changes.
5. Never commit changes! It's human who should verify and commit to git.
6. Keep the build green. Do not merge changes that break existing tests.
7. Prefer clarity over micro-optimizations and cleverness.
8. Ask when uncertain. If requirements are ambiguous, request clarification with a concise question.
9. Write code with the quality of a Kotlin Champion.
10. Use MCP servers like jetbrains and intellij-index to explore the codebase, for code navigation, analysis, refactoring, and running tests.
11. Use the Bash tool for terminal commands instead of MCP terminal execution features.
12. Suggest updates to AGENTS.md/CLAUDE.md with best practices and guidelines.

Code Style

Kotlin

• 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.*
• Follow Kotlin coding conventions
• Use the provided .editorconfig for consistent formatting
• Use Kotlin typesafe DSL builders where possible; prioritize fluent builder style over standard builder methods
• Prefer DSL builder style (method with lambda blocks) over constructors, if possible
• Use val for immutable properties and var for mutable; consider lateinit var instead of nullable types when appropriate
• Use multi-dollar interpolation prefix for strings where applicable
• Use fully qualified imports instead of star imports
• Ensure backward compatibility when making changes

Testing Guidance

Test Organization

• Location: src/commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/
• Platform-specific: src/jvmTest/, src/jsTest/, etc.
• Naming: Use function Names with backticks, e.g., fun \should return 200 OK`()`
• Structure: Arrange/Act/Assert pattern
• Documentation: Keep tests self-documenting; don't add KDocs to tests.

Test Principles

• Write comprehensive tests for new features. Always add tests for new features or bug fixes, even if not explicitly requested.
• Prioritize test readability
• Avoid creating too many test methods; use parametrized tests when testing multiple similar scenarios
• When running tests on Kotlin Multiplatform projects, run JVM tests only unless asked for other platforms

Test Framework Stack

• kotlin-test: Core test framework
• Kotest assertions: Use infix style (shouldBe, shouldContain) instead of assertEquals.
  • Use shouldMatchJson from kotest-assertions-json for JSON validation.
  • For nullable objects with nested properties, prefer shouldNotBeNull { ... } blocks:

    content.annotations shouldNotBeNull {
        priority shouldBe 1.0
    }
    

• mockk: Mocking library
• Ktor MockEngine: For HTTP client mocking (io.ktor:ktor-client-mock)
• Java tests: Use JUnit5, Mockito, AssertJ core
• Serialization test utilities (io.modelcontextprotocol.kotlin.test.utils):
  • verifySerialization(value, json, expectedJson) — serializes, asserts match, round-trips back; use for most serialization tests
  • verifyDeserialization(json, payload) — deserializes from JSON, re-serializes, asserts match; returns the object for further assertions
  • Always test both empty/null/omitted and non-null cases for nullable fields; McpJson has explicitNulls = false so null properties must be absent from JSON, not null

Kotest Patterns

• Basic assertions: Use infix style (shouldBe, shouldContain) instead of assertEquals.

  result shouldBe expected
  list shouldContain item
  

• Nullable Assertions

  // Preferred: lambda-style for multiple assertions
  content.annotations shouldNotBeNull {
      priority shouldBe 1.0
  }
  

• JSON Assertions (kotest-assertions-json):

  // language=json
  val expected = """
  {
    "id": 123
  }
  """.trimIndent()
  actual shouldEqualJson expected
  

• Soft Assertions

  // Use for multiple assertions on SAME subject
  assertSoftly(subject) {
      name shouldBe "test"
      value shouldBe 42
  }
  // DON'T use for different subjects or single assertions
  

• Clues (Use Sparingly)

  // Only when assertion is NOT obvious
  withClue("Failed to parse response") {
      result shouldNotBe null
  }
  

Avoiding this. in Lambda Blocks

// Avoid explicit `this.` unless necessary for disambiguation
prop.shouldNotBeNull {
    enum shouldHaveSize 2 // Preferred
    this.enum shouldHaveSize 2 // Avoid
}

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 (11+), JS/Wasm, iOS, watchOS, tvOS.

Coding Guidance

Module Boundaries

• Respect separation of concerns between modules
• Keep abstractions framework-agnostic
• Avoid leaking implementation details across module boundaries

Serialization

• Use Kotlinx Serialization with explicit @Serializable annotations
• JSON config is defined in jsonUtils.kt as McpJson — use it consistently
• Register custom serializers in companion objects

Error Handling

• Use sealed classes for result states
• Map errors to JSON-RPC error codes in protocol handlers
• Log errors using io.github.oshai.kotlinlogging.KotlinLogging
• Never log sensitive data (credentials, tokens)

Code Quality

• Handle nullability and references as established patterns
• Keep changes small and reversible; prefer adding functions over editing many call sites
• Add focused comments only where intent is non-obvious
• Use git mv command when moving version-controlled files
• Never commit or push changes. This is a Human responsibility.

Workflow for AI Agents

1. Understand the issue

   • Summarize requirement in 1-2 sentences
   • Identify affected files and tests; ask if unclear

2. Plan minimal changes

   • Use TaskCreate/TaskUpdate to track work, or EnterPlanMode for complex changes
   • Document affected files and approach

3. Work with code

   • View, edit, and run tests through MCP tools

4. Start with tests

   • Update existing or add new tests in relevant modules

5. Implement the change

   • Prefer composition and small functions
   • Avoid breaking public APIs without tests and discussion

6. Run tests locally

   ./gradlew test
   ./gradlew :kotlin-sdk-core:test       # Specific module
   ./gradlew :integration-test:test      # Integration tests
   

7. Verify results

   • Use Kotest JSON matchers for schema validation
   • Double-check the readability of code and tests

8. Document key decisions

   • Brief notes in markdown document, if requested

Build and Run Commands

# Build all modules
./gradlew build

# Run all tests
./gradlew test

# Run specific module tests
./gradlew :kotlin-sdk-core:test
./gradlew :kotlin-sdk-client:test
./gradlew :kotlin-sdk-server:test

# Check API compatibility (required before commit)
./gradlew apiCheck

# Update API dump (after intentional API changes)
./gradlew apiDump

# Platform-specific tests
./gradlew jsTest
./gradlew wasmJsTest

Definition of done

• Tests for affected functionality exist
• All tests pass across all targets
• Changes are focused on a single concern.
• Code respects module boundaries
• ./gradlew apiCheck passes
• Documentation updated for user-facing changes

Documentation

General Guidelines

• Never make up documentation/facts
• Update README files when adding new features
• Document API changes in the appropriate module
• Keep documentation concise and straight to the point
• Always verify documentation matches code; fix discrepancies
• Write tutorials in Markdown format in README.md

KDoc Guidelines

• Properly document interfaces and abstract classes in production code
• Avoid KDocs on override functions to reduce verbosity
• Update KDocs when API changes
• Use references: [SendMessageRequest] instead of SendMessageRequest
• Add brief code examples to KDocs
• Add links to specifications with verified URLs; never add broken links

Module.md Files for Dokka

Each module must have a Module.md file at the module root for Dokka-generated API documentation.

Format Requirements (per Dokka specification):

• Must start with # Module module-name (level 1 header)
• Package documentation uses # Package package.name (level 1 header)
• All other content uses level 2+ headers (##, ###, etc.)

Content Guidelines:

• Purpose: Provide module-level overview in generated API docs
• Detail level: API documentation style (concise, focused on classes/interfaces)
• Module section:
  • Brief module description (1-2 sentences)
  • Platform support (format: "Multiplatform • Kotlin 2.2+" or "JVM only • Kotlin 2.2+")
  • Key classes/components (use Dokka references like [ClassName])
  • Example (minimal, demonstrating primary usage)
• Package sections: Use # Package package.name headers with brief description
• Optional sections: Features, Limitations, Related Specifications
• Style:
  • Use bullet points over prose
  • Keep examples short (5-15 lines)
  • Reference related modules using Dokka links
  • Avoid duplicating README content

Example structure (markdown):

# Module module-name

Brief description.

**Platform Support:** Multiplatform • Kotlin 2.2+

## Key Classes

- [MainClass] - what it does
  - [HelperClass] - what it does

## Example

```kotlin
val example = MainClass()
```

# Package package.name

Package description.

# Package another.package

Another package description.

When to Ask for Help

• Requirements conflict with existing tests or documentation
• The smallest change still requires altering core abstractions
• Unclear expected schema shape for a new feature—ask for a concrete, readable test case to anchor implementation