modelcontextprotocol / modelcontextprotocol/kotlin-sdk

Data classes exposed in public APIs might cause down-compatibility issues

Open
#34 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

api breaking enhancement P2 ready for work refactoring
Dominant language
Kotlin
Stars
1.5k
Forks
248
Avg merge
1d 20h
Merged PRs (30d)
23

Description

Is your feature request related to a problem? Please describe.
The official Kotlin guidelines discourage use of data classes in public APIs:

https://kotlinlang.org/docs/api-guidelines-backward-compatibility.html#avoid-using-data-classes-in-your-api

This project is using data classes to express all the types of MCP protocol. This might cause all the down-compatibility issues described in linked document, if the MCP protocol evolves.

Describe the solution you'd like
A possible way to overcome this issues is to stop using data classes in favor of classes with private constructors, and allow to create them only with builders. If the MCP protocol is extended, the new class properties can be put in any order in the private constructor, to follow the protocol evolution. Example of such an approach here:

https://github.com/xemantic/xemantic-ai-tool-schema/blob/main/src/commonMain/kotlin/JsonSchema.kt

(e.g. ObjectSchema class). The tests are here:

https://github.com/xemantic/xemantic-ai-tool-schema/blob/main/src/commonTest/kotlin/JsonSchemaTest.kt

If this is considered a way to go, I would be happy to prepare this PR.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the Kotlin backward-compatibility guidance linked in the issue, then review the SDK's MCP protocol types to identify which data classes are exposed publicly. Compare the proposed builder-based approach with the linked JsonSchema.kt and JsonSchemaTest.kt example; done means the affected public types preserve protocol behavior while avoiding the stated compatibility risks.

Written by the indexing model from the issue text.

Assessment

Tech stack
kotlin
Domain
api, backend-api-design
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.