feat: add tasks models by devcrocod · Pull Request #566 · modelcontextprotocol/kotlin-sdk

devcrocod · 2026-02-26T13:09:54Z

Motivation and Context

closes #421
#406

How Has This Been Tested?

Unit tests

Breaking Changes

NaN

Types of changes

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

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

Copilot

Pull request overview

Adds initial Kotlin SDK type support for MCP “tasks” (SEP-1686) by introducing task models, task-related request/response/notification types, and wiring them into the existing JSON (de)serialization layer.

Changes:

Introduces core task types (Task, TaskStatus, TaskMetadata, RelatedTaskMetadata) and task RPC types (tasks/get, tasks/result, tasks/list, tasks/cancel) plus notifications/tasks/status.
Registers new methods and hooks task requests/notifications/results into the polymorphic serializers.
Adds/extends unit tests for task serialization/deserialization and updates detekt baselines / public API snapshot.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/tasks.kt	New task models + task RPC request/result types.
kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt	Adds `TaskStatusNotification` and params.
kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/methods.kt	Registers new task methods + notification method.
kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/serializers.kt	Wires task request/notification deserialization and result shape matching.
kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/request.kt	Adds `RequestMeta.relatedTask` accessor.
kotlin-sdk-core/src/commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/types/TasksTest.kt	New comprehensive tests for task types and RPCs.
kotlin-sdk-core/src/commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/types/NotificationTest.kt	Adds tests for `notifications/tasks/status`.
kotlin-sdk-core/detekt-baseline-*.xml	Baseline updates/suppressions for new code/tests.
kotlin-sdk-core/api/kotlin-sdk-core.api	Updates public API snapshot for new types.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/request.kt

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/tasks.kt

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt

kotlin-sdk-core/src/commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/types/TasksTest.kt

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/serializers.kt

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/tasks.kt

kpavlov

Thank you, @devcrocod
There are copilot findings that look legitimate.
Let's split big classes and don't inflate detekt baselines.

kpavlov · 2026-03-01T09:04:21Z

kotlin-sdk-core/detekt-baseline-commonTestSourceSet.xml

+<SmellBaseline>
+  <ManuallySuppressedIssues/>
+  <CurrentIssues>
+    <ID>LargeClass:TasksTest.kt:TasksTest</ID>


Let's not inflate detekt baselines.
In this case the test class should be splitted

#567 (comment)

kpavlov · 2026-03-01T09:12:40Z

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/request.kt

+     */
+    public val relatedTask: RelatedTaskMetadata?
+        get() = json[RELATED_TASK_META_KEY]?.let { element ->
+            McpJson.decodeFromJsonElement(element)


Could we cache it or handle during deserialization in the serializer? Currently, it will run json parsing every time

json is not parsed every time, It’s not an expensive operation

I can do it that way, but then we’ll have to modify the class since it’s value class

handle during deserialization in the serializer

And that would require a custom serializer, which I’d prefer to avoid

json is not parsed every time, It’s not an expensive operation

I see the getter is not cached, so every property call will result in json parsing. In general, it should be avoided. The application would have to cache it.

A value class may not be the best solution here, as it introduces unnecessary restrictions.

Additionally, RequestMeta risks becoming a God Object as more metadata (e.g., RelatedTaskMetadata) is added over time. This pattern hinders extensibility and violates clean design principles.

An alternative solution is to use an extension function:

public fun RequestMeta.relatedTaskMetadata(): RelatedTaskMetadata? = this.json[RELATED_TASK_META_KEY]?.let { McpJson.decodeFromJsonElement(it) }

This approach is more extensible and avoids the pitfalls of the current solution, even if it doesn't address the lack of caching.

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt

kpavlov · 2026-03-01T09:17:51Z

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/tasks.kt

+    ServerResult,
+    TaskFields
+
+// ============================================================================


This file is getting huge. Let's split it. There are clear boundaries: models, requests, responses

kpavlov · 2026-03-01T09:26:04Z

kotlin-sdk-core/detekt-baseline-main.xml

  <ManuallySuppressedIssues/>
  <CurrentIssues>
    <ID>CyclomaticComplexMethod:jsonUtils.kt:@OptIn(ExperimentalUnsignedTypes::class, ExperimentalSerializationApi::class) private fun convertToJsonElement: JsonElement</ID>
+    <ID>CyclomaticComplexMethod:serializers.kt:private fun selectServerResultDeserializer: DeserializationStrategy&lt;ServerResult>?</ID>


Can we address it in a proper way?

…ods and tests

codecov-commenter · 2026-03-02T18:37:01Z

Codecov Report

❌ Patch coverage is 79.81651% with 22 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
.../io/modelcontextprotocol/kotlin/sdk/types/tasks.kt	81.08%	0 Missing and 14 partials ⚠️
...delcontextprotocol/kotlin/sdk/types/serializers.kt	62.50%	0 Missing and 6 partials ⚠️
...elcontextprotocol/kotlin/sdk/types/notification.kt	83.33%	0 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!

kpavlov · 2026-03-02T18:59:59Z

kotlin-sdk-core/src/commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/types/TasksTest.kt

+        assertNotNull(result.meta)
+        assertEquals("task-42", result.meta?.get("origin")?.jsonPrimitive?.content)
+        assertNotNull(result["content"])
+        assertNotNull(result["isError"])


Why not give Kotest a try for our new tests?

kpavlov · 2026-03-02T19:01:45Z

kotlin-sdk-core/src/commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/types/TasksTest.kt

+
+        assertEquals("task-1", cancelResult.taskId)
+        assertEquals(TaskStatus.Cancelled, cancelResult.status)
+    }


Wow, that’s almost 800 lines!

How about we break things down a bit? We could split tasks.kt and TaskTest.kt into different files, like GetTask.kt, ListTasks.kt and CancelTask.kt, based on what each one does.

kpavlov · 2026-03-02T19:03:48Z

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/tasks.kt

-    @SerialName("_meta")
-    override val meta: JsonObject? = null,
-) : ServerResult
+public value class GetTaskPayloadResult(public val json: JsonObject) :


I am not sure I understand the advantages of moving to the value class here. It seems like it might not be possible to extend it by the user.
@e5l, do you think we are safe here?

Copilot

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-02T19:08:14Z

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/tasks.kt

+/**
+ * Metadata for augmenting a request with task execution.
+ * Include this in the `task` field of the request parameters.
+ *
+ * @property ttl Requested duration in milliseconds to retain task from creation.
+ */
+@Serializable
+public data class TaskMetadata(val ttl: Double? = null)
+


PR description says this change “closes #421 / #406”, but this PR appears to only add task-related model/types, serializers, and tests. Key items called out in those issues (e.g., updating LATEST_PROTOCOL_VERSION to 2025-11-25 and adding task: TaskMetadata? to RequestParams/request params) are not included here, so merging this as-is likely shouldn’t auto-close those tracking issues. Consider updating the PR description/linked issues to reflect the actual scope (e.g., “partial” / “follow-ups”).

kpavlov · 2026-03-03T12:11:27Z

@devcrocod, please consider defining a public typealias TaskId = String or value class for type safety and, potentially, validation

kpavlov · 2026-03-03T13:03:58Z

kotlin-sdk-core/src/commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/types/TasksTest.kt

+
+    @Test
+    fun `RELATED_TASK_META_KEY should have correct value`() {
+        assertEquals("io.modelcontextprotocol/related-task", RELATED_TASK_META_KEY)


This test is not valuable. Let's verify RequestMeta deserialization with RelatedTaskMetadata instead.

Would it be possible to get some test data from the spec? https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks, e.g. https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks#retrieving-task-results response is pretty good.

kpavlov · 2026-03-03T13:06:19Z

kotlin-sdk-core/src/commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/types/TasksTest.kt

+            {
+              "method": "tasks/get",
+              "params": {
+                "taskId": "task-11"


Are we missing the "io.modelcontextprotocol/related-task" here?

5.7.1.
Associating Task-Related Messages
All requests, notifications, and responses related to a task MUST include the io.modelcontextprotocol/related-task key in their _meta field, with the value set to an object with a taskId matching the associated task ID.

devcrocod requested a review from Amaneusz February 26, 2026 15:18

devcrocod marked this pull request as ready for review February 26, 2026 15:18

Copilot AI review requested due to automatic review settings February 26, 2026 15:18

Copilot started reviewing on behalf of devcrocod February 26, 2026 15:18 View session

Copilot AI reviewed Feb 26, 2026

View reviewed changes

kpavlov requested changes Mar 1, 2026

View reviewed changes

devcrocod added 5 commits March 2, 2026 19:10

Add task models, related methods, serializers, and tests

4137a66

Add TaskStatusNotification model, methods, serializers, and tests

9ec1403

update apiDump

36ca4e8

update detekt baselines

403a21c

Refactor GetTaskPayloadResult to a value class, update related meth…

cb0c75b

…ods and tests

devcrocod force-pushed the devcrocod/tasks-classes branch from f43c48b to cb0c75b Compare March 2, 2026 18:20

update api

2507883

Copilot AI review requested due to automatic review settings March 2, 2026 19:00

Copilot started reviewing on behalf of devcrocod March 2, 2026 19:00 View session

devcrocod requested a review from kpavlov March 2, 2026 19:01

kpavlov reviewed Mar 2, 2026

View reviewed changes

Copilot AI reviewed Mar 2, 2026

View reviewed changes

kpavlov reviewed Mar 3, 2026

View reviewed changes

kpavlov mentioned this pull request Mar 3, 2026

Align Kotlin SDK with 2025-11-25 Specification #406

Open

61 tasks

Conversation

devcrocod commented Feb 26, 2026

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kpavlov left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codecov-commenter commented Mar 2, 2026

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kpavlov Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

kpavlov commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

kpavlov Mar 2, 2026 •

edited

Loading

kpavlov commented Mar 3, 2026 •

edited

Loading