Rewrite and restructure schema types

Author: devcrocod

kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/shared/Protocol.kt

@@ -51,6 +51,7 @@ public const val IMPLEMENTATION_NAME: String = "mcp-ktor"
 public typealias ProgressCallback = (Progress) -> Unit
 
 @OptIn(ExperimentalSerializationApi::class)
+@Deprecated("Use McpJson instead", ReplaceWith("McpJson"))
 public val McpJson: Json by lazy {
     Json {
         ignoreUnknownKeys = true

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

@@ -265,6 +265,11 @@ internal object JSONRPCMessagePolymorphicSerializer :
     }
 }
 
+@Deprecated(
+    message = "Use `io.modelcontextprotocol.kotlin.sdk.types.EmptyJsonObject` instead",
+    replaceWith = ReplaceWith("EmptyJsonObject", "io.modelcontextprotocol.kotlin.sdk.types.EmptyJsonObject"),
+    level = DeprecationLevel.WARNING,
+)
 public val EmptyJsonObject: JsonObject = JsonObject(emptyMap())
 
 public class RequestIdSerializer : KSerializer<RequestId> {

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

@@ -0,0 +1,14 @@
+package io.modelcontextprotocol.kotlin.sdk.types
+
+import kotlinx.serialization.json.JsonObject
+
+/**
+ * Represents an error specific to the MCP protocol.
+ *
+ * @property code The error code.
+ * @property message The error message.
+ * @property data Additional error data as a JSON object.
+ */
+public class McpException(public val code: Int, message: String, public val data: JsonObject? = null) : Exception() {
+    override val message: String = "MCP error $code: $message"
+}

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

@@ -0,0 +1,145 @@
+package io.modelcontextprotocol.kotlin.sdk.types
+
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.JsonObject
+
+/**
+ * Describes an MCP (Model Context Protocol) implementation.
+ *
+ * This metadata helps clients identify and display information about servers or clients,
+ * including their name, version, and optional branding elements like icons and website links.
+ *
+ * @property name The programmatic identifier for this implementation.
+ * Intended for logical use and API identification. If [title] is not provided,
+ * this should be used as a fallback display name.
+ * @property version The version string of this implementation (e.g., "1.0.0", "2.1.3-beta").
+ * @property title Optional human-readable display name for this implementation.
+ * Intended for UI and end-user contexts, optimized to be easily understood
+ * even by those unfamiliar with domain-specific terminology.
+ * If not provided, [name] should be used for display purposes.
+ * @property websiteUrl Optional URL of the website for this implementation.
+ * Can be used to provide documentation, support, or additional information.
+ * @property icons Optional set of sized icons that clients can display in their user interface.
+ * See [Icon] for supported formats and requirements.
+ */
+@Serializable
+public data class Implementation(
+    val name: String,
+    val version: String,
+    val title: String? = null,
+    val websiteUrl: String? = null,
+    val icons: List<Icon>? = null,
+)
+
+/**
+ * Capabilities that a client may support.
+ *
+ * Known capabilities are defined here, but this is not a closed set: any client
+ * can define its own additional capabilities through the [experimental] field.
+ *
+ * The presence of a capability object (non-null value) indicates that the client
+ * supports that capability.
+ *
+ * @property sampling Present if the client supports sampling from an LLM.
+ * @property roots Present if the client supports listing roots.
+ * @property elicitation Present if the client supports elicitation from the server.
+ * @property experimental Experimental, non-standard capabilities that the client supports.
+ * Keys are capability names, values are capability-specific configuration objects.
+ */
+@Serializable
+public data class ClientCapabilities(
+    public val sampling: JsonObject? = null,
+    public val roots: Roots? = null,
+    public val elicitation: JsonObject? = null,
+    public val experimental: JsonObject? = null,
+) {
+
+    public companion object {
+        public val sampling: JsonObject = EmptyJsonObject
+        public val elicitation: JsonObject = EmptyJsonObject
+    }
+
+    /**
+     * Indicates that the client supports listing roots.
+     *
+     * Roots are the top-level directories or locations that the server can access.
+     * When present (non-null), the server can query available roots and optionally
+     * receive notifications when the roots list changes.
+     *
+     * @property listChanged Whether the client supports notifications for changes to the roots list.
+     * If true, the client will send notifications when roots are added or removed.
+     */
+    @Serializable
+    public data class Roots(val listChanged: Boolean? = null)
+}
+
+/**
+ * Capabilities that a server may support.
+ *
+ * Known capabilities are defined here, but this is not a closed set: any server
+ * can define its own additional capabilities through the [experimental] field.
+ *
+ * The presence of a capability object (non-null value) indicates that the server
+ * supports that capability.
+ *
+ * @property tools Present if the server offers any tools to call.
+ * @property resources Present if the server offers any resources to read.
+ * @property prompts Present if the server offers any prompt templates.
+ * @property logging Present if the server supports sending log messages to the client.
+ * @property completions Present if the server supports argument autocompletion suggestions.
+ * Keys are capability names, values are capability-specific configuration objects.
+ * @property experimental Experimental, non-standard capabilities that the server supports.
+ */
+@Serializable
+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,
+) {
+
+    public companion object {
+        public val Logging: JsonObject = EmptyJsonObject
+        public val Completions: JsonObject = EmptyJsonObject
+    }
+
+    /**
+     * Indicates that the server offers tools to call.
+     *
+     * When present (non-null), clients can list and invoke tools (functions, actions, etc.)
+     * provided by the server.
+     *
+     * @property listChanged Whether this server supports notifications for changes to the tool list.
+     * If true, the server will send notifications when tools are added, modified, or removed.
+     */
+    @Serializable
+    public data class Tools(val listChanged: Boolean? = null)
+
+    /**
+     * Indicates that the server offers resources to read.
+     *
+     * When present (non-null), clients can list and read resources (files, data sources, etc.)
+     * provided by the server.
+     *
+     * @property listChanged Whether this server supports notifications for changes to the resource list.
+     * If true, the server will send notifications when resources are added or removed.
+     * @property subscribe Whether this server supports subscribing to resource updates.
+     * If true, clients can subscribe to receive notifications when specific
+     * resources are modified.
+     */
+    @Serializable
+    public data class Resources(val listChanged: Boolean? = null, val subscribe: Boolean? = null)
+
+    /**
+     * Indicates that the server offers prompt templates.
+     *
+     * When present (non-null), clients can list and invoke prompts provided by the server.
+     *
+     * @property listChanged Whether this server supports notifications for changes to the prompt list.
+     * If true, the server will send notifications when prompts are added, modified, or removed.
+     */
+    @Serializable
+    public data class Prompts(val listChanged: Boolean? = null)
+}

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

@@ -0,0 +1,176 @@
+package io.modelcontextprotocol.kotlin.sdk.types
+
+import kotlinx.serialization.ExperimentalSerializationApi
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.JsonClassDiscriminator
+import kotlinx.serialization.json.JsonObject
+import kotlin.jvm.JvmInline
+
+// ============================================================================
+// Protocol Version Constants
+// ============================================================================
+
+public const val LATEST_PROTOCOL_VERSION: String = "2025-03-26"
+
+public val SUPPORTED_PROTOCOL_VERSIONS: Array<String> = arrayOf(
+    LATEST_PROTOCOL_VERSION,
+    "2024-11-05",
+)
+
+// ============================================================================
+// Base Interfaces
+// ============================================================================
+
+/**
+ * Represents an entity that includes additional metadata in its responses.
+ */
+// TODO: реализовать meta
+// The _meta property/parameter is reserved by MCP to allow clients and servers to attach additional metadata to their interactions.
+// Certain key names are reserved by MCP for protocol-level metadata, as specified below; implementations MUST NOT make assumptions about values at these keys.
+// Additionally, definitions in the schema may reserve particular names for purpose-specific metadata, as declared in those definitions.
+// Key name format: valid _meta key names have two segments: an optional prefix, and a name.
+// Prefix:
+// If specified, MUST be a series of labels separated by dots (.), followed by a slash (/).
+// Labels MUST start with a letter and end with a letter or digit; interior characters can be letters, digits, or hyphens (-).
+// Any prefix beginning with zero or more valid labels, followed by modelcontextprotocol or mcp, followed by any valid label, is reserved for MCP use.
+// For example: modelcontextprotocol.io/, mcp.dev/, api.modelcontextprotocol.org/, and tools.mcp.com/ are all reserved.
+// Name:
+// Unless empty, MUST begin and end with an alphanumeric character ([a-z0-9A-Z]).
+// MAY contain hyphens (-), underscores (_), dots (.), and alphanumerics in between.
+@Serializable
+public sealed interface WithMeta {
+    @SerialName("_meta")
+    public val meta: JsonObject?
+}
+
+// ============================================================================
+// Tokens
+// ============================================================================
+
+/**
+ * A progress token, used to associate progress notifications with the original request.
+ */
+@Serializable // TODO custom serializer
+public sealed interface ProgressToken {
+    @JvmInline
+    @Serializable
+    public value class ProgressTokenString(public val value: String) : ProgressToken
+
+    @JvmInline
+    @Serializable
+    public value class ProgressTokenInt(public val value: Long) : ProgressToken
+}
+
+// ============================================================================
+// Visual Elements
+// ============================================================================
+
+/**
+ * An optionally sized icon that can be displayed in a user interface.
+ *
+ * Icons help clients provide visual branding and identification for MCP implementations.
+ *
+ * **Security considerations:**
+ * - Consumers SHOULD ensure URLs serving icons are from the same domain as the client/server
+ *   or a trusted domain to prevent malicious content.
+ * - Consumers SHOULD take appropriate precautions when rendering SVGs as they can contain
+ *   executable JavaScript. Consider sanitizing SVG content or rendering in isolated contexts.
+ *
+ * @property src A standard URI pointing to an icon resource.
+ * Maybe an HTTP/HTTPS URL or a data: URI with Base64-encoded image data.
+ * Example: "https://example.com/icon.png" or "data:image/png;base64,iVBORw0KG..."
+ * @property mimeType Optional MIME type override if the source MIME type is missing or generic.
+ * For example, "image/png", "image/jpeg", or "image/svg+xml".
+ * Useful when the URL doesn't include a file extension or uses a generic MIME type.
+ * @property sizes Optional array of strings that specify sizes at which the icon can be used.
+ * Each string should be in WxH format (e.g., "48x48", "96x96") or "any" for
+ * scalable formats like SVG. If not provided, the client should assume that
+ * the icon can be used at any size.
+ * @property theme Optional specifier for the theme this icon is designed for.
+ * [Theme.Light] indicates the icon is designed for a light background,
+ * [Theme.Dark] indicates the icon is designed for a dark background.
+ * If not provided, the client should assume the icon can be used with any theme.
+ */
+@Serializable
+public data class Icon(
+    val src: String,
+    val mimeType: String? = null,
+    val sizes: List<String>? = null,
+    val theme: Theme? = null,
+) {
+    /**
+     * The theme context for which an icon is designed.
+     *
+     * @property Light Icon designed for use with a light background (typically darker icon).
+     * @property Dark Icon designed for use with a dark background (typically lighter icon).
+     */
+    @Serializable
+    public enum class Theme {
+        /** Icon designed for use with a light background */
+        @SerialName("light")
+        Light,
+
+        /** Icon designed for use with a dark background */
+        @SerialName("dark")
+        Dark,
+    }
+}
+
+// ============================================================================
+// Roles and References
+// ============================================================================
+
+/**
+ * The sender or recipient of messages and data in a conversation.
+ */
+@Serializable
+public enum class Role {
+    @SerialName("user")
+    User,
+
+    @SerialName("assistant")
+    Assistant,
+}
+
+/**
+ * Base interface for reference types in the protocol.
+ *
+ * References are used to point to other entities (prompts, resources, etc.)
+ * without including their full definitions.
+ */
+@OptIn(ExperimentalSerializationApi::class)
+@Serializable
+@JsonClassDiscriminator("type")
+public sealed interface Reference
+
+// ============================================================================
+// Annotations and Metadata
+// ============================================================================
+
+/**
+ * Optional annotations for the client.
+ *
+ * The client can use annotations to inform how objects are used or displayed.
+ *
+ * @property audience Describes who the intended customer of this object or data is.
+ * Can include multiple entries to indicate content useful for multiple audiences
+ * (e.g., [Role.user, Role.assistant]).
+ * @property priority Describes how important this data is for operating the server.
+ * A value of 1.0 means "most important" and indicates that the data is effectively required,
+ * while 0.0 means "least important" and indicates that the data is entirely optional.
+ * Should be a value between 0.0 and 1.0.
+ * @property lastModified The moment the resource was last modified, as an ISO 8601 formatted string
+ *  (e.g., "2025-01-12T15:00:58Z").
+ *  Examples: last activity timestamp in an open file, timestamp when the resource was attached, etc.
+ */
+@Serializable
+public data class Annotations(
+    val audience: List<Role>? = null,
+    val priority: Double? = null,
+    val lastModified: String? = null,
+) {
+    init {
+        require(priority == null || priority in 0.0..1.0) { "Priority must be between 0.0 and 1.0" }
+    }
+}