Align Kotlin SDK with DRAFT-2025-v3 Specification

[kpavlov]

Overview

The Kotlin SDK currently implements protocol version 2025-06-18 but is missing several features defined in the DRAFT-2025-v3 TypeScript specification. This issue tracks the discrepancies and required implementations.

AI-generated tasks

Critical Missing Features

1. Protocol Version ❌

Current: LATEST_PROTOCOL_VERSION = "2025-06-18"
Required: LATEST_PROTOCOL_VERSION = "DRAFT-2025-v3"

Files:

• kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/common.kt:13

---

2. Task Augmentation System ❌ (Complete Feature Missing)

The entire task system is absent from the Kotlin SDK.

2.1 Missing Core Types

• TaskMetadata - Metadata for task-augmented requests
• Task - Task state data (taskId, status, createdAt, ttl, etc.)
• TaskStatus - Enum: working | input_required | completed | failed | cancelled
• RelatedTaskMetadata - For associating messages with tasks

2.2 Missing RequestParams Field

• Add task: TaskMetadata? field to RequestParams interface
  • File: kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/request.kt:29
  • Update all implementing classes

2.3 Missing Request/Response Types

• CreateTaskResult - Response to task-augmented requests
• GetTaskRequest / GetTaskResult - Retrieve task state
• GetTaskPayloadRequest / GetTaskPayloadResult - Retrieve completed task result
• CancelTaskRequest / CancelTaskResult - Cancel a running task
• ListTasksRequest / ListTasksResult - List all tasks

2.4 Missing Notifications

• TaskStatusNotification - Notification of task status changes
• TaskStatusNotificationParams

2.5 Missing DSL Builders

• Update RequestBuilder to support task metadata
• GetTaskRequestBuilder
• ListTasksRequestBuilder
• CancelTaskRequestBuilder

---

3. Tool Use in Sampling ❌

3.1 Missing CreateMessageRequestParams Fields

File: kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/sampling.kt:191

// Current implementation missing:
public data class CreateMessageRequestParams(
    // ... existing fields ...
    // ❌ Missing: val tools: List<Tool>? = null,
    // ❌ Missing: val toolChoice: ToolChoice? = null,
) : RequestParams

Required:

• Add tools: List<Tool>? parameter
• Add toolChoice: ToolChoice? parameter
• Update CreateMessageRequestBuilder DSL to support these fields

3.2 Missing ToolChoice Type

Required TypeScript Definition:

export interface ToolChoice {
  mode?: "auto" | "required" | "none";
}

• Create ToolChoice data class
• Add tool choice mode enum/sealed class

3.3 Missing Content Types for Tool Use

File: kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/content.kt

Current ContentTypes enum:

public enum class ContentTypes(public val value: String) {
    TEXT("text"),
    IMAGE("image"),
    AUDIO("audio"),
    RESOURCE_LINK("resource_link"),
    EMBEDDED_RESOURCE("resource"),
    // ❌ Missing: TOOL_USE("tool_use"),
    // ❌ Missing: TOOL_RESULT("tool_result"),
}

Required:

• Add TOOL_USE to ContentTypes enum
• Add TOOL_RESULT to ContentTypes enum
• Create ToolUseContent data class with fields:
  • type: "tool_use"
  • id: String
  • name: String
  • input: JsonObject
  • _meta
• Create ToolResultContent data class with fields:
  • type: "tool_result"
  • toolUseId: String
  • content: List<ContentBlock>
  • structuredContent: JsonObject?
  • isError: Boolean?
  • _meta
• Update SamplingMessage.content type to support tool content blocks
• Add DSL builders in content.dsl.kt

3.4 Missing StopReason Value

File: kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/sampling.kt:248

Current:

public value class StopReason(public val value: String) {
    public companion object {
        public val EndTurn: StopReason = StopReason("endTurn")
        public val StopSequence: StopReason = StopReason("stopSequence")
        public val MaxTokens: StopReason = StopReason("maxTokens")
        // ❌ Missing: public val ToolUse: StopReason = StopReason("toolUse")
    }
}

• Add ToolUse stop reason value

---

4. Structured Capabilities ⚠️ (Partially Implemented)

4.1 ClientCapabilities - Needs Nested Structures

File: kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/capabilities.kt:50

Current (Flat):

public data class ClientCapabilities(
    public val sampling: JsonObject? = null,      // ⚠️ Should be structured
    public val roots: Roots? = null,              // ✓ OK
    public val elicitation: JsonObject? = null,   // ⚠️ Should be structured
    public val experimental: JsonObject? = null,  // ✓ OK
    // ❌ Missing: public val tasks: Tasks? = null
)

Required:

• Create SamplingCapability data class:

  data class SamplingCapability(
      val context: JsonObject? = null,
      val tools: JsonObject? = null,
  )

• Create ElicitationCapability data class:

  data class ElicitationCapability(
      val form: JsonObject? = null,
      val url: JsonObject? = null,
  )

• Create TasksCapability with nested structure:

  data class TasksCapability(
      val list: JsonObject? = null,
      val cancel: JsonObject? = null,
      val requests: TasksRequestCapability? = null,
  )
  
  data class TasksRequestCapability(
      val sampling: TasksSamplingCapability? = null,
      val elicitation: TasksElicitationCapability? = null,
  )
  
  data class TasksSamplingCapability(
      val createMessage: JsonObject? = null,
  )
  
  data class TasksElicitationCapability(
      val create: JsonObject? = null,
  )

• Update ClientCapabilities to use these types
• Update ClientCapabilitiesBuilder in capabilities.dsl.kt

4.2 ServerCapabilities - Missing Tasks

File: kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/capabilities.kt:94

Current:

public data class ServerCapabilities(
    val tools: Tools? = null,
    val resources: Resources? = null,
    val prompts: Prompts? = null,
    val logging: JsonObject? = null,
    val completions: JsonObject? = null,
    val experimental: JsonObject? = null,
    // ❌ Missing: val tasks: Tasks? = null,
)

Required:

• Create ServerTasksCapability data class:

  data class ServerTasksCapability(
      val list: JsonObject? = null,
      val cancel: JsonObject? = null,
      val requests: ServerTasksRequestCapability? = null,
  )
  
  data class ServerTasksRequestCapability(
      val tools: ServerTasksToolsCapability? = null,
  )
  
  data class ServerTasksToolsCapability(
      val call: JsonObject? = null,
  )

• Add tasks field to ServerCapabilities

---

Implementation Checklist Summary

Phase 1: Core Types (High Priority)

• Update protocol version to "DRAFT-2025-v3"
• Add RequestParams.task field
• Implement task core types (TaskMetadata, Task, TaskStatus, RelatedTaskMetadata)
• Implement ToolChoice type
• Add TOOL_USE and TOOL_RESULT to ContentTypes enum
• Implement ToolUseContent and ToolResultContent types

Phase 2: Request/Response Types (High Priority)

• Add tools and toolChoice to CreateMessageRequestParams
• Update SamplingMessage to support tool content types
• Add StopReason.ToolUse value
• Implement all task request types (GetTask, ListTasks, CancelTask, GetTaskPayload)
• Implement all task result types
• Implement TaskStatusNotification

Phase 3: Capabilities (Medium Priority)

• Restructure ClientCapabilities.sampling to SamplingCapability
• Restructure ClientCapabilities.elicitation to ElicitationCapability
• Add ClientCapabilities.tasks with full nested structure
• Add ServerCapabilities.tasks with full nested structure

Phase 4: DSL Builders (Medium Priority)

• Update CreateMessageRequestBuilder with tools/toolChoice support
• Add task metadata support to RequestBuilder base class
• Create task-related request builders
• Update ClientCapabilitiesBuilder for new structures
• Add tool content builders to content.dsl.kt

Phase 5: Testing & Documentation

• Add unit tests for all new types
• Update integration tests
• Document breaking changes
• Create migration guide
• Update examples

---

Quick Reference: What's Already Implemented ✓

• ✓ CallToolResult.structuredContent - Already present
• ✓ CreateMessageResult.stopReason - Already present (but missing "toolUse" value)
• ✓ Tool.outputSchema - Already present
• ✓ Basic content types (text, image, audio, resource_link, embedded_resource)
• ✓ Tool annotations with hints (readOnlyHint, destructiveHint, etc.)

---

Breaking Changes Warning

Implementing full spec compliance will require breaking changes to:

1. RequestParams interface (adding task field)
2. ClientCapabilities structure (changing from JsonObject to nested types)
3. ServerCapabilities structure (adding tasks)
4. CreateMessageRequestParams (adding tools/toolChoice)
5. ContentTypes enum (adding new variants)
6. SamplingMessage content type (supporting tool content)

Consider versioning strategy before implementation.

---

References

• Spec Version: DRAFT-2025-v3 (TypeScript specification)
• Current SDK Version: 2025-06-18
• Related PR: Proposal: DSL Builders for request types #399 (DSL builders - does not include spec alignment)
• Key Files: kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/