6fee82ff1a<!-- Provide a brief summary of your changes -->
## Motivation and Context
<!-- Why is this change needed? What problem does it solve? -->
The dsl builders in [this
commit](74c93745cd (diff-598edaa01d))
were mistakenly marked internal and are therefore unusable. I have
simply marked them as public.
## How Has This Been Tested?
<!-- Have you tested this in a real application? Which scenarios were
tested? -->
## Breaking Changes
No
## Types of changes
<!-- What types of changes does your code introduce? Put an `x` in all
the boxes that apply: -->
- [x] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
## Checklist
<!-- Go over all the following points, and put an `x` in all the boxes
that apply. -->
- [ ] I have read the [MCP
Documentation](https://modelcontextprotocol.io)
- [ ] My code follows the repository's style guidelines
- [x] New and existing tests pass locally
- [ ] I have added appropriate error handling
- [ ] I have added or updated documentation as needed
## Additional context
<!-- Add any other context, implementation notes, or design decisions
-->
---------
Co-authored-by: Konstantin Pavlov <1517853+kpavlov@users.noreply.github.com>
101 lines
3.9 KiB
Markdown
101 lines
3.9 KiB
Markdown
# 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.
|
|
- For nullable objects with nested properties, prefer `shouldNotBeNull { ... }` blocks:
|
|
```kotlin
|
|
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](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.
|