Skip to content

AGENTS.md

Latest commit

 

History

History
82 lines (63 loc) · 3.75 KB

AGENTS.md

File metadata and controls

82 lines (63 loc) · 3.75 KB

AGENTS: Development Guidelines for AI Contributors

This file provides guidance to AI coding agents working with code in this repository.

Project

Kotlin Multiplatform SDK for the Model Context Protocol (MCP). Targets JVM, Native (macOS/Linux/Windows), JS, and Wasm. Implements both MCP clients and servers with pluggable transports.

Build Commands

./gradlew ktlintCheck                # Lint check
./gradlew detekt                     # Static analysis
./gradlew ktlintFormat               # Auto-fix lint issues
./gradlew apiCheck                   # Check public API compatibility (run before committing)
./gradlew apiDump                    # Update API dump after intentional API changes
./gradlew koverLog                   # Print coverage summary
./gradlew koverXmlReport            # Generate XML coverage report

Run a single test class:

./gradlew :kotlin-sdk-server:jvmTest --tests "io.modelcontextprotocol.kotlin.sdk.server.StdioServerTransportTest"

Run a single test method:

./gradlew :kotlin-sdk-core:jvmTest --tests "*.ProtocolTest.should preserve existing meta when adding progress token"

Conformance tests (requires Node.js + npx):

./conformance-test/run-conformance.sh all           # All suites sequentially
./conformance-test/run-conformance.sh server         # Server suite only
./conformance-test/run-conformance.sh client         # Client core suite (initialize, tools_call, elicitation, sse-retry)
./conformance-test/run-conformance.sh client-auth    # Client auth suite (20 OAuth scenarios)

Module Structure

kotlin-sdk-core      Core: protocol types, JSON-RPC, Transport abstraction, Protocol base class
kotlin-sdk-client    Client: MCP client implementation (tools, prompts, resources, sampling)
kotlin-sdk-server    Server: MCP server implementation (feature registries, sessions)
kotlin-sdk-testing   ChannelTransport for in-memory client-server testing
kotlin-sdk           Umbrella module aggregating client + server
test-utils           Shared test helpers (mockk, kotest, awaitility)
conformance-test     MCP specification compliance tests (external runner)
integration-test     End-to-end tests
samples/             Runnable examples (servers and clients)

Architecture

Layered design:

Application (tools, prompts, resources)
  → Client / Server  (typed MCP operations, capability enforcement)
    → Protocol        (JSON-RPC framing, request correlation, timeouts)
      → Transport     (pluggable I/O: stdio, SSE, Streamable HTTP, WebSocket)

Code Conventions

  • Explicit API mode (Strict): all public declarations must have explicit visibility modifiers and return types
  • DSL builders: prefer DSL builder style (lambda blocks) over direct constructors
  • Multi-dollar interpolation: use $$"""...""" for strings containing literal $ (e.g., JSON with $ref, $defs)
  • McpJson has explicitNulls = false: null properties must be absent from JSON, not "field": null
  • Logging: use io.github.oshai.kotlinlogging.KotlinLogging
  • Structured concurrency: every coroutine must have a bounded scope and lifetime; always re-throw CancellationException; never hold Mutex across suspension points

Testing

  • JVM first: run jvmTest instead of test — full multiplatform test runs are slow and rarely needed during development
  • Test naming: use backtick syntax — fun \should return 200 OK`()`
  • Frameworks: JUnit 5 (runner) + Kotest (assertions) + MockK (mocking) + Awaitility (async waits)
  • In-memory testing: ChannelTransport.createLinkedPair() connects client and server without network

Skills

  • /mcp-docs — fetches live MCP specification and docs; use when implementing or debugging MCP protocol features