Skip to content

Add support for elicitation #138

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jul 11, 2025
Merged

Add support for elicitation #138

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3865234
feat(client): add support for elicitation
ptitjes Jul 6, 2025
476655b
feat(client): add a convenience method to set the elicitation handler
ptitjes Jul 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
124 changes: 120 additions & 4 deletions api/kotlin-sdk.api
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -167,14 +167,16 @@ public final class io/modelcontextprotocol/kotlin/sdk/CancelledNotification$Comp
public final class io/modelcontextprotocol/kotlin/sdk/ClientCapabilities {
public static final field Companion Lio/modelcontextprotocol/kotlin/sdk/ClientCapabilities$Companion;
public fun <init> ()V
public fun <init> (Lkotlinx/serialization/json/JsonObject;Lkotlinx/serialization/json/JsonObject;Lio/modelcontextprotocol/kotlin/sdk/ClientCapabilities$Roots;)V
public synthetic fun <init> (Lkotlinx/serialization/json/JsonObject;Lkotlinx/serialization/json/JsonObject;Lio/modelcontextprotocol/kotlin/sdk/ClientCapabilities$Roots;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
public fun <init> (Lkotlinx/serialization/json/JsonObject;Lkotlinx/serialization/json/JsonObject;Lio/modelcontextprotocol/kotlin/sdk/ClientCapabilities$Roots;Lkotlinx/serialization/json/JsonObject;)V
public synthetic fun <init> (Lkotlinx/serialization/json/JsonObject;Lkotlinx/serialization/json/JsonObject;Lio/modelcontextprotocol/kotlin/sdk/ClientCapabilities$Roots;Lkotlinx/serialization/json/JsonObject;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
public final fun component1 ()Lkotlinx/serialization/json/JsonObject;
public final fun component2 ()Lkotlinx/serialization/json/JsonObject;
public final fun component3 ()Lio/modelcontextprotocol/kotlin/sdk/ClientCapabilities$Roots;
public final fun copy (Lkotlinx/serialization/json/JsonObject;Lkotlinx/serialization/json/JsonObject;Lio/modelcontextprotocol/kotlin/sdk/ClientCapabilities$Roots;)Lio/modelcontextprotocol/kotlin/sdk/ClientCapabilities;
public static synthetic fun copy$default (Lio/modelcontextprotocol/kotlin/sdk/ClientCapabilities;Lkotlinx/serialization/json/JsonObject;Lkotlinx/serialization/json/JsonObject;Lio/modelcontextprotocol/kotlin/sdk/ClientCapabilities$Roots;ILjava/lang/Object;)Lio/modelcontextprotocol/kotlin/sdk/ClientCapabilities;
public final fun component4 ()Lkotlinx/serialization/json/JsonObject;
public final fun copy (Lkotlinx/serialization/json/JsonObject;Lkotlinx/serialization/json/JsonObject;Lio/modelcontextprotocol/kotlin/sdk/ClientCapabilities$Roots;Lkotlinx/serialization/json/JsonObject;)Lio/modelcontextprotocol/kotlin/sdk/ClientCapabilities;
public static synthetic fun copy$default (Lio/modelcontextprotocol/kotlin/sdk/ClientCapabilities;Lkotlinx/serialization/json/JsonObject;Lkotlinx/serialization/json/JsonObject;Lio/modelcontextprotocol/kotlin/sdk/ClientCapabilities$Roots;Lkotlinx/serialization/json/JsonObject;ILjava/lang/Object;)Lio/modelcontextprotocol/kotlin/sdk/ClientCapabilities;
public fun equals (Ljava/lang/Object;)Z
public final fun getElicitation ()Lkotlinx/serialization/json/JsonObject;
public final fun getExperimental ()Lkotlinx/serialization/json/JsonObject;
public final fun getRoots ()Lio/modelcontextprotocol/kotlin/sdk/ClientCapabilities$Roots;
public final fun getSampling ()Lkotlinx/serialization/json/JsonObject;
Expand Down Expand Up @@ -383,6 +385,117 @@ public final class io/modelcontextprotocol/kotlin/sdk/CompleteResult$Completion$
public final fun serializer ()Lkotlinx/serialization/KSerializer;
}

public final class io/modelcontextprotocol/kotlin/sdk/CreateElicitationRequest : io/modelcontextprotocol/kotlin/sdk/ServerRequest, io/modelcontextprotocol/kotlin/sdk/WithMeta {
public static final field Companion Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationRequest$Companion;
public fun <init> (Ljava/lang/String;Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationRequest$RequestedSchema;Lkotlinx/serialization/json/JsonObject;)V
public synthetic fun <init> (Ljava/lang/String;Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationRequest$RequestedSchema;Lkotlinx/serialization/json/JsonObject;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
public final fun component1 ()Ljava/lang/String;
public final fun component2 ()Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationRequest$RequestedSchema;
public final fun component3 ()Lkotlinx/serialization/json/JsonObject;
public final fun copy (Ljava/lang/String;Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationRequest$RequestedSchema;Lkotlinx/serialization/json/JsonObject;)Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationRequest;
public static synthetic fun copy$default (Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationRequest;Ljava/lang/String;Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationRequest$RequestedSchema;Lkotlinx/serialization/json/JsonObject;ILjava/lang/Object;)Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationRequest;
public fun equals (Ljava/lang/Object;)Z
public final fun getMessage ()Ljava/lang/String;
public fun getMethod ()Lio/modelcontextprotocol/kotlin/sdk/Method;
public final fun getRequestedSchema ()Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationRequest$RequestedSchema;
public fun get_meta ()Lkotlinx/serialization/json/JsonObject;
public fun hashCode ()I
public fun toString ()Ljava/lang/String;
}

public final synthetic class io/modelcontextprotocol/kotlin/sdk/CreateElicitationRequest$$serializer : kotlinx/serialization/internal/GeneratedSerializer {
public static final field INSTANCE Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationRequest$$serializer;
public final fun childSerializers ()[Lkotlinx/serialization/KSerializer;
public final fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationRequest;
public synthetic fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Object;
public final fun getDescriptor ()Lkotlinx/serialization/descriptors/SerialDescriptor;
public final fun serialize (Lkotlinx/serialization/encoding/Encoder;Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationRequest;)V
public synthetic fun serialize (Lkotlinx/serialization/encoding/Encoder;Ljava/lang/Object;)V
public fun typeParametersSerializers ()[Lkotlinx/serialization/KSerializer;
}

public final class io/modelcontextprotocol/kotlin/sdk/CreateElicitationRequest$Companion {
public final fun serializer ()Lkotlinx/serialization/KSerializer;
}

public final class io/modelcontextprotocol/kotlin/sdk/CreateElicitationRequest$RequestedSchema {
public static final field Companion Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationRequest$RequestedSchema$Companion;
public fun <init> ()V
public fun <init> (Lkotlinx/serialization/json/JsonObject;Ljava/util/List;)V
public synthetic fun <init> (Lkotlinx/serialization/json/JsonObject;Ljava/util/List;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
public final fun component1 ()Lkotlinx/serialization/json/JsonObject;
public final fun component2 ()Ljava/util/List;
public final fun copy (Lkotlinx/serialization/json/JsonObject;Ljava/util/List;)Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationRequest$RequestedSchema;
public static synthetic fun copy$default (Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationRequest$RequestedSchema;Lkotlinx/serialization/json/JsonObject;Ljava/util/List;ILjava/lang/Object;)Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationRequest$RequestedSchema;
public fun equals (Ljava/lang/Object;)Z
public final fun getProperties ()Lkotlinx/serialization/json/JsonObject;
public final fun getRequired ()Ljava/util/List;
public final fun getType ()Ljava/lang/String;
public fun hashCode ()I
public fun toString ()Ljava/lang/String;
}

public final synthetic class io/modelcontextprotocol/kotlin/sdk/CreateElicitationRequest$RequestedSchema$$serializer : kotlinx/serialization/internal/GeneratedSerializer {
public static final field INSTANCE Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationRequest$RequestedSchema$$serializer;
public final fun childSerializers ()[Lkotlinx/serialization/KSerializer;
public final fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationRequest$RequestedSchema;
public synthetic fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Object;
public final fun getDescriptor ()Lkotlinx/serialization/descriptors/SerialDescriptor;
public final fun serialize (Lkotlinx/serialization/encoding/Encoder;Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationRequest$RequestedSchema;)V
public synthetic fun serialize (Lkotlinx/serialization/encoding/Encoder;Ljava/lang/Object;)V
public fun typeParametersSerializers ()[Lkotlinx/serialization/KSerializer;
}

public final class io/modelcontextprotocol/kotlin/sdk/CreateElicitationRequest$RequestedSchema$Companion {
public final fun serializer ()Lkotlinx/serialization/KSerializer;
}

public final class io/modelcontextprotocol/kotlin/sdk/CreateElicitationResult : io/modelcontextprotocol/kotlin/sdk/ClientResult {
public static final field Companion Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationResult$Companion;
public fun <init> (Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationResult$Action;Lkotlinx/serialization/json/JsonObject;Lkotlinx/serialization/json/JsonObject;)V
public synthetic fun <init> (Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationResult$Action;Lkotlinx/serialization/json/JsonObject;Lkotlinx/serialization/json/JsonObject;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
public final fun component1 ()Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationResult$Action;
public final fun component2 ()Lkotlinx/serialization/json/JsonObject;
public final fun component3 ()Lkotlinx/serialization/json/JsonObject;
public final fun copy (Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationResult$Action;Lkotlinx/serialization/json/JsonObject;Lkotlinx/serialization/json/JsonObject;)Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationResult;
public static synthetic fun copy$default (Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationResult;Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationResult$Action;Lkotlinx/serialization/json/JsonObject;Lkotlinx/serialization/json/JsonObject;ILjava/lang/Object;)Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationResult;
public fun equals (Ljava/lang/Object;)Z
public final fun getAction ()Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationResult$Action;
public final fun getContent ()Lkotlinx/serialization/json/JsonObject;
public fun get_meta ()Lkotlinx/serialization/json/JsonObject;
public fun hashCode ()I
public fun toString ()Ljava/lang/String;
}

public final synthetic class io/modelcontextprotocol/kotlin/sdk/CreateElicitationResult$$serializer : kotlinx/serialization/internal/GeneratedSerializer {
public static final field INSTANCE Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationResult$$serializer;
public final fun childSerializers ()[Lkotlinx/serialization/KSerializer;
public final fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationResult;
public synthetic fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Object;
public final fun getDescriptor ()Lkotlinx/serialization/descriptors/SerialDescriptor;
public final fun serialize (Lkotlinx/serialization/encoding/Encoder;Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationResult;)V
public synthetic fun serialize (Lkotlinx/serialization/encoding/Encoder;Ljava/lang/Object;)V
public fun typeParametersSerializers ()[Lkotlinx/serialization/KSerializer;
}

public final class io/modelcontextprotocol/kotlin/sdk/CreateElicitationResult$Action : java/lang/Enum {
public static final field Companion Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationResult$Action$Companion;
public static final field accept Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationResult$Action;
public static final field cancel Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationResult$Action;
public static final field decline Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationResult$Action;
public static fun getEntries ()Lkotlin/enums/EnumEntries;
public static fun valueOf (Ljava/lang/String;)Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationResult$Action;
public static fun values ()[Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationResult$Action;
}

public final class io/modelcontextprotocol/kotlin/sdk/CreateElicitationResult$Action$Companion {
public final fun serializer ()Lkotlinx/serialization/KSerializer;
}

public final class io/modelcontextprotocol/kotlin/sdk/CreateElicitationResult$Companion {
public final fun serializer ()Lkotlinx/serialization/KSerializer;
}

public final class io/modelcontextprotocol/kotlin/sdk/CreateMessageRequest : io/modelcontextprotocol/kotlin/sdk/ServerRequest, io/modelcontextprotocol/kotlin/sdk/WithMeta {
public static final field Companion Lio/modelcontextprotocol/kotlin/sdk/CreateMessageRequest$Companion;
public fun <init> (Ljava/util/List;Ljava/lang/String;Lio/modelcontextprotocol/kotlin/sdk/CreateMessageRequest$IncludeContext;Ljava/lang/Double;ILjava/util/List;Lkotlinx/serialization/json/JsonObject;Lio/modelcontextprotocol/kotlin/sdk/ModelPreferences;Lkotlinx/serialization/json/JsonObject;)V
Expand Down Expand Up @@ -1381,6 +1494,7 @@ public final class io/modelcontextprotocol/kotlin/sdk/Method$Custom$Companion {
public final class io/modelcontextprotocol/kotlin/sdk/Method$Defined : java/lang/Enum, io/modelcontextprotocol/kotlin/sdk/Method {
public static final field Companion Lio/modelcontextprotocol/kotlin/sdk/Method$Defined$Companion;
public static final field CompletionComplete Lio/modelcontextprotocol/kotlin/sdk/Method$Defined;
public static final field ElicitationCreate Lio/modelcontextprotocol/kotlin/sdk/Method$Defined;
public static final field Initialize Lio/modelcontextprotocol/kotlin/sdk/Method$Defined;
public static final field LoggingSetLevel Lio/modelcontextprotocol/kotlin/sdk/Method$Defined;
public static final field NotificationsCancelled Lio/modelcontextprotocol/kotlin/sdk/Method$Defined;
Expand Down Expand Up @@ -2868,6 +2982,8 @@ public class io/modelcontextprotocol/kotlin/sdk/server/Server : io/modelcontextp
protected fun assertCapabilityForMethod (Lio/modelcontextprotocol/kotlin/sdk/Method;)V
protected fun assertNotificationCapability (Lio/modelcontextprotocol/kotlin/sdk/Method;)V
public fun assertRequestHandlerCapability (Lio/modelcontextprotocol/kotlin/sdk/Method;)V
public final fun createElicitation (Ljava/lang/String;Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationRequest$RequestedSchema;Lio/modelcontextprotocol/kotlin/sdk/shared/RequestOptions;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
public static synthetic fun createElicitation$default (Lio/modelcontextprotocol/kotlin/sdk/server/Server;Ljava/lang/String;Lio/modelcontextprotocol/kotlin/sdk/CreateElicitationRequest$RequestedSchema;Lio/modelcontextprotocol/kotlin/sdk/shared/RequestOptions;Lkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
public final fun createMessage (Lio/modelcontextprotocol/kotlin/sdk/CreateMessageRequest;Lio/modelcontextprotocol/kotlin/sdk/shared/RequestOptions;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
public static synthetic fun createMessage$default (Lio/modelcontextprotocol/kotlin/sdk/server/Server;Lio/modelcontextprotocol/kotlin/sdk/CreateMessageRequest;Lio/modelcontextprotocol/kotlin/sdk/shared/RequestOptions;Lkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
public final fun getClientCapabilities ()Lio/modelcontextprotocol/kotlin/sdk/ClientCapabilities;
Expand Down
8 changes: 8 additions & 0 deletions src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/Client.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -262,6 +262,14 @@ public open class Client(
}
}

Method.Defined.ElicitationCreate -> {
if (capabilities.elicitation == null) {
throw IllegalStateException(
"Client does not support elicitation capability (required for $method)"
Copy link

Copilot AI Jul 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The exception message is inconsistent with the server-side text and the test expectation. Consider matching it to "Client does not support elicitation (required for elicitation/create)" and use method.value rather than $method for clarity.

Suggested change
"Client does not support elicitation capability (required for $method)"
"Client does not support elicitation (required for elicitation/create)"

Copilot uses AI. Check for mistakes.
)
}
}

Method.Defined.Ping -> {
// No capability required
}
Expand Down
18 changes: 18 additions & 0 deletions src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/Server.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,9 @@ import io.github.oshai.kotlinlogging.KotlinLogging
import io.modelcontextprotocol.kotlin.sdk.CallToolRequest
import io.modelcontextprotocol.kotlin.sdk.CallToolResult
import io.modelcontextprotocol.kotlin.sdk.ClientCapabilities
import io.modelcontextprotocol.kotlin.sdk.CreateElicitationRequest
import io.modelcontextprotocol.kotlin.sdk.CreateElicitationRequest.RequestedSchema
import io.modelcontextprotocol.kotlin.sdk.CreateElicitationResult
import io.modelcontextprotocol.kotlin.sdk.CreateMessageRequest
import io.modelcontextprotocol.kotlin.sdk.CreateMessageResult
import io.modelcontextprotocol.kotlin.sdk.EmptyJsonObject
Expand Down Expand Up @@ -525,6 +528,15 @@ public open class Server(
return request<ListRootsResult>(ListRootsRequest(params), options)
}

public suspend fun createElicitation(
message: String,
requestedSchema: RequestedSchema,
options: RequestOptions? = null
): CreateElicitationResult {
logger.debug { "Creating elicitation with message: $message" }
return request(CreateElicitationRequest(message, requestedSchema), options)
}

/**
* Sends a logging message notification to the client.
*
Expand Down Expand Up @@ -666,6 +678,12 @@ public open class Server(
}
}

"elicitation/create" -> {
if (clientCapabilities?.elicitation == null) {
throw IllegalStateException("Client does not support elicitation (required for ${method.value})")
}
}

"ping" -> {
// No specific capability required
}
Expand Down
49 changes: 48 additions & 1 deletion src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,8 @@ public sealed interface Method {
LoggingSetLevel("logging/setLevel"),
SamplingCreateMessage("sampling/createMessage"),
CompletionComplete("completion/complete"),
RootsList("roots/list")
RootsList("roots/list"),
ElicitationCreate("elicitation/create"),
}

/**
Expand Down Expand Up @@ -337,6 +338,10 @@ public data class ClientCapabilities(
* Present if the client supports listing roots.
*/
val roots: Roots? = null,
/**
* Present if the client supports elicitation.
*/
val elicitation: JsonObject? = null,
) {
@Serializable
public data class Roots(
Expand Down Expand Up @@ -1544,6 +1549,48 @@ public class RootsListChangedNotification : ClientNotification {
override val method: Method = Method.Defined.NotificationsRootsListChanged
}

/**
* Sent from the server to create an elicitation from the client.
*/
@Serializable
public data class CreateElicitationRequest(
public val message: String,
public val requestedSchema: RequestedSchema,
override val _meta: JsonObject = EmptyJsonObject,
) : ServerRequest, WithMeta {
override val method: Method = Method.Defined.ElicitationCreate

@Serializable
public data class RequestedSchema(
val properties: JsonObject = EmptyJsonObject,
val required: List<String>? = null,
) {
@OptIn(ExperimentalSerializationApi::class)
@EncodeDefault
val type: String = "object"
}
}

/**
* The client's response to an elicitation/create request from the server.
*/
@Serializable
public data class CreateElicitationResult(
public val action: Action,
public val content: JsonObject? = null,
override val _meta: JsonObject = EmptyJsonObject,
) : ClientResult {

init {
require(action == Action.accept || content == null) {
"Content can only be provided for an 'accept' action"
}
}

@Serializable
public enum class Action { accept, decline, cancel }
}

/**
* Represents an error specific to the MCP protocol.
*
Expand Down
Loading