Align Kotlin SDK with 2025-11-25 Specification

[kpavlov]

Overview

The Kotlin SDK currently implements protocol version 2025-06-18 but is missing several features defined in the 2025-11 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 = "2025-11-25"

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/

[kpavlov]

Status update — 2025-11-25 spec (finalized)

The spec referenced in this issue as "DRAFT-2025-v3" has since been published as the final https://modelcontextprotocol.io/specification/2025-11-25. A full
gap analysis has been done comparing the Kotlin SDK against the finalized spec. The findings are tracked in ../blob/main/missing-mcp-features.md in the
repo root.

Spin-off issues filed (one concern per issue)

All items from the original checklist have been broken out into focused issues:

Topic / Issue

• Tasks (SEP-1686) - Implement SEP-1686: Tasks #421
• URL-mode elicitation (SEP-1036) — not in original issue - Implement SEP-1036: URL Mode Elicitation for Secure Out-of-Band Interactions #410, Elicitation - protocol version 2025-11-25 #540, Add notifications/elicitation/complete #546
• Sampling with tools (SEP-1577) — types - add tool use/result content to sampling content blocks #541
• Sampling with tools — tools/toolChoice params - Add ToolChoice and tools/toolChoice fields to CreateMessageRequestParams #542
• Tool.execution.taskSupport - Add ToolExecution to Tool definition #543
• Structured sampling/elicitation/tasks capabilities - Capabilities extensions for tasks and sampling/elicitation detail #544
• Elicitation enum/default schema improvements - Implement SEP-1330: Elicitation Enum Schema Improvements #412, Implement SEP-1034: Default Values for Elicitation Schemas #414
• SSE polling via server-side disconnect (SEP-1699) - Implement SEP-1699: Support SSE Polling via Server-Side Disconnect #420
• JSON Schema 2020-12 default dialect (SEP-1613) - Implement SEP-1613: JSON Schema 2020-12 as Default Dialect #422
• Tool name validation guidance (SEP-986) - Implement SEP-986: Tool Name Guidance #417
• OAuth / authorization alignment - Implement SEP-985: Align OAuth 2.0 Protected Resource Metadata with RFC 9728 #411, Implement SEP-991: URL-based Client Registration (OAuth Client ID Metadata) #416, Implement SEP-1046: Support OAuth client credentials flow in authorization #418, Implement SEP-835: Default Scopes Definition in Authorization #419, Implement SEP-990: Enterprise Managed Authorization (Extension) #423
• Default scopes in WWW-Authenticate (SEP-835) - Implement SEP-835: Default Scopes Definition in Authorization #419
• Decouple request payload from RPC methods (SEP-1319) - Implement SEP-1319: Decouple Request Payload from RPC Methods #413
• Implementation.description field - tracked in this issue

Open PRs in progress:

• chore: update protocol version #539 - Bump LATEST_PROTOCOL_VERSION to 2025-11-25
• feat: add tasks models #566 - Task types — Implement SEP-1686: Tasks #421
• feat: add tool execution properties to Tool #567 - Tool.execution.taskSupport — Add ToolExecution to Tool definition #543
• Implement resource templates #503 - Resource templates
• feat: Verify MCP endpoints with authentication for Streamable HTTP transport, test for SSE transport #535 - Streamable HTTP auth / Origin validation

Items not in the original issue

The 2025-11-25 spec added URL-mode elicitation (SEP-1036), which was not present when this issue was written. It requires:

• mode, url, elicitationId fields on ElicitRequestParams
• New notification notifications/elicitation/complete
• New error code -32042 (URLElicitationRequiredError)
• Typed ElicitationCapability (currently JsonObject?)

Tracked in #410, #540, #546.