Add ModelContextProtocol.Core package (#428)

src/ModelContextProtocol.Core/Protocol/Annotations.cs

@@ -0,0 +1,29 @@
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Represents annotations that can be attached to content, resources, and resource templates.
+/// </summary>
+/// <remarks>
+/// Annotations enable filtering and prioritization of content for different audiences.
+/// See the <see href="https://github.com/modelcontextprotocol/specification/blob/main/schema/">schema</see> for details.
+/// </remarks>
+public class Annotations
+{
+    /// <summary>
+    /// Gets or sets the intended audience for this content as an array of <see cref="Role"/> values.
+    /// </summary>
+    [JsonPropertyName("audience")]
+    public Role[]? Audience { get; init; }
+
+    /// <summary>
+    /// Gets or sets a value indicating how important this data is for operating the server.
+    /// </summary>
+    /// <remarks>
+    /// The value is a floating-point number between 0 and 1, where 0 represents the lowest priority
+    /// 1 represents highest priority.
+    /// </remarks>
+    [JsonPropertyName("priority")]
+    public float? Priority { get; init; }
+}

src/ModelContextProtocol.Core/Protocol/Argument.cs

@@ -0,0 +1,29 @@
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Represents an argument used in completion requests to provide context for auto-completion functionality.
+/// </summary>
+/// <remarks>
+/// This class is used when requesting completion suggestions for a particular field or parameter.
+/// See the <see href="https://github.com/modelcontextprotocol/specification/blob/main/schema/">schema</see> for details.
+/// </remarks>
+public class Argument
+{
+    /// <summary>
+    /// Gets or sets the name of the argument being completed.
+    /// </summary>
+    [JsonPropertyName("name")]
+    public string Name { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets the current partial text value for which completion suggestions are requested.
+    /// </summary>
+    /// <remarks>
+    /// This represents the text that has been entered so far and for which completion
+    /// options should be generated.
+    /// </remarks>
+    [JsonPropertyName("value")]
+    public string Value { get; set; } = string.Empty;
+}

src/ModelContextProtocol.Core/Protocol/BlobResourceContents.cs

@@ -0,0 +1,30 @@
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Represents the binary contents of a resource in the Model Context Protocol.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <see cref="BlobResourceContents"/> is used when binary data needs to be exchanged through
+/// the Model Context Protocol. The binary data is represented as a base64-encoded string
+/// in the <see cref="Blob"/> property.
+/// </para>
+/// <para>
+/// This class inherits from <see cref="ResourceContents"/>, which also has a sibling implementation
+/// <see cref="TextResourceContents"/> for text-based resources. When working with resources, the
+/// appropriate type is chosen based on the nature of the content.
+/// </para>
+/// <para>
+/// See the <see href="https://github.com/modelcontextprotocol/specification/blob/main/schema/">schema</see> for more details.
+/// </para>
+/// </remarks>
+public class BlobResourceContents : ResourceContents
+{
+    /// <summary>
+    /// Gets or sets the base64-encoded string representing the binary data of the item.
+    /// </summary>
+    [JsonPropertyName("blob")]
+    public string Blob { get; set; } = string.Empty;
+}

src/ModelContextProtocol.Core/Protocol/CallToolRequestParams.cs

@@ -0,0 +1,28 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Represents the parameters used with a <see cref="RequestMethods.ToolsCall"/> request from a client to invoke a tool provided by the server.
+/// </summary>
+/// <remarks>
+/// The server will respond with a <see cref="CallToolResponse"/> containing the result of the tool invocation.
+/// See the <see href="https://github.com/modelcontextprotocol/specification/blob/main/schema/">schema</see> for details.
+/// </remarks>
+public class CallToolRequestParams : RequestParams
+{
+    /// <summary>Gets or sets the name of the tool to invoke.</summary>
+    [JsonPropertyName("name")]
+    public required string Name { get; init; }
+
+    /// <summary>
+    /// Gets or sets optional arguments to pass to the tool when invoking it on the server.
+    /// </summary>
+    /// <remarks>
+    /// This dictionary contains the parameter values to be passed to the tool. Each key-value pair represents 
+    /// a parameter name and its corresponding argument value.
+    /// </remarks>
+    [JsonPropertyName("arguments")]
+    public IReadOnlyDictionary<string, JsonElement>? Arguments { get; init; }
+}

src/ModelContextProtocol.Core/Protocol/CallToolResponse.cs

@@ -0,0 +1,41 @@
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Represents the result of a <see cref="RequestMethods.ToolsCall"/> request from a client to invoke a tool provided by the server.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Any errors that originate from the tool should be reported inside the result
+/// object, with <see cref="IsError"/> set to true, rather than as a <see cref="JsonRpcError"/>.
+/// </para>
+/// <para>
+/// However, any errors in finding the tool, an error indicating that the
+/// server does not support tool calls, or any other exceptional conditions,
+/// should be reported as an MCP error response.
+/// </para>
+/// <para>
+/// See the <see href="https://github.com/modelcontextprotocol/specification/blob/main/schema/">schema</see> for details.
+/// </para>
+/// </remarks>
+public class CallToolResponse
+{
+    /// <summary>
+    /// Gets or sets the response content from the tool call.
+    /// </summary>
+    [JsonPropertyName("content")]
+    public List<Content> Content { get; set; } = [];
+
+    /// <summary>
+    /// Gets or sets an indication of whether the tool call was unsuccessful.
+    /// </summary>
+    /// <remarks>
+    /// When set to <see langword="true"/>, it signifies that the tool execution failed.
+    /// Tool errors are reported with this property set to <see langword="true"/> and details in the <see cref="Content"/>
+    /// property, rather than as protocol-level errors. This allows LLMs to see that an error occurred
+    /// and potentially self-correct in subsequent requests.
+    /// </remarks>
+    [JsonPropertyName("isError")]
+    public bool IsError { get; set; }
+}

src/ModelContextProtocol.Core/Protocol/CancelledNotification.cs

@@ -0,0 +1,30 @@
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Represents a notification indicating that a request has been cancelled by the client,
+/// and that any associated processing should cease immediately.
+/// </summary>
+/// <remarks>
+/// This class is typically used in conjunction with the <see cref="NotificationMethods.CancelledNotification"/>
+/// method identifier. When a client sends this notification, the server should attempt to
+/// cancel any ongoing operations associated with the specified request ID.
+/// </remarks>
+public sealed class CancelledNotification
+{
+    /// <summary>
+    /// Gets or sets the ID of the request to cancel.
+    /// </summary>
+    /// <remarks>
+    /// This must match the ID of an in-flight request that the sender wishes to cancel.
+    /// </remarks>
+    [JsonPropertyName("requestId")]
+    public RequestId RequestId { get; set; }
+
+    /// <summary>
+    /// Gets or sets an optional string describing the reason for the cancellation request.
+    /// </summary>
+    [JsonPropertyName("reason")]
+    public string? Reason { get; set; }
+}

src/ModelContextProtocol.Core/Protocol/ClientCapabilities.cs

@@ -0,0 +1,87 @@
+using ModelContextProtocol.Server;
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Represents the capabilities that a client may support.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Capabilities define the features and functionality that a client can handle when communicating with an MCP server.
+/// These are advertised to the server during the initialize handshake.
+/// </para>
+/// <para>
+/// See the <see href="https://github.com/modelcontextprotocol/specification/blob/main/schema/">schema</see> for details.
+/// </para>
+/// </remarks>
+public class ClientCapabilities
+{
+    /// <summary>
+    /// Gets or sets experimental, non-standard capabilities that the client supports.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// The <see cref="Experimental"/> dictionary allows clients to advertise support for features that are not yet 
+    /// standardized in the Model Context Protocol specification. This extension mechanism enables 
+    /// future protocol enhancements while maintaining backward compatibility.
+    /// </para>
+    /// <para>
+    /// Values in this dictionary are implementation-specific and should be coordinated between client 
+    /// and server implementations. Servers should not assume the presence of any experimental capability 
+    /// without checking for it first.
+    /// </para>
+    /// </remarks>
+    [JsonPropertyName("experimental")]
+    public Dictionary<string, object>? Experimental { get; set; }
+
+    /// <summary>
+    /// Gets or sets the client's roots capability, which are entry points for resource navigation.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// When <see cref="Roots"/> is non-<see langword="null"/>, the client indicates that it can respond to 
+    /// server requests for listing root URIs. Root URIs serve as entry points for resource navigation in the protocol.
+    /// </para>
+    /// <para>
+    /// The server can use <see cref="McpServerExtensions.RequestRootsAsync"/> to request the list of
+    /// available roots from the client, which will trigger the client's <see cref="RootsCapability.RootsHandler"/>.
+    /// </para>
+    /// </remarks>
+    [JsonPropertyName("roots")]
+    public RootsCapability? Roots { get; set; }
+
+    /// <summary>
+    /// Gets or sets the client's sampling capability, which indicates whether the client 
+    /// supports issuing requests to an LLM on behalf of the server.
+    /// </summary>
+    [JsonPropertyName("sampling")]
+    public SamplingCapability? Sampling { get; set; }
+
+    /// <summary>
+    /// Gets or sets the client's elicitation capability, which indicates whether the client 
+    /// supports elicitation of additional information from the user on behalf of the server.
+    /// </summary>
+    [JsonPropertyName("elicitation")]
+    public ElicitationCapability? Elicitation { get; set; }
+
+    /// <summary>Gets or sets notification handlers to register with the client.</summary>
+    /// <remarks>
+    /// <para>
+    /// When constructed, the client will enumerate these handlers once, which may contain multiple handlers per notification method key.
+    /// The client will not re-enumerate the sequence after initialization.
+    /// </para>
+    /// <para>
+    /// Notification handlers allow the client to respond to server-sent notifications for specific methods.
+    /// Each key in the collection is a notification method name, and each value is a callback that will be invoked
+    /// when a notification with that method is received.
+    /// </para>
+    /// <para>
+    /// Handlers provided via <see cref="NotificationHandlers"/> will be registered with the client for the lifetime of the client.
+    /// For transient handlers, <see cref="IMcpEndpoint.RegisterNotificationHandler"/> may be used to register a handler that can
+    /// then be unregistered by disposing of the <see cref="IAsyncDisposable"/> returned from the method.
+    /// </para>
+    /// </remarks>
+    [JsonIgnore]
+    public IEnumerable<KeyValuePair<string, Func<JsonRpcNotification, CancellationToken, ValueTask>>>? NotificationHandlers { get; set; }
+}

src/ModelContextProtocol.Core/Protocol/CompleteRequestParams.cs

@@ -0,0 +1,34 @@
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Represents the parameters used with a <see cref="RequestMethods.CompletionComplete"/> request from 
+/// a client to ask a server for auto-completion suggestions.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <see cref="RequestMethods.CompletionComplete"/> is used in the Model Context Protocol completion workflow
+/// to provide intelligent suggestions for partial inputs related to resources, prompts, or other referenceable entities.
+/// The completion mechanism in MCP allows clients to request suggestions based on partial inputs.
+/// The server will respond with a <see cref="CompleteResult"/> containing matching values.
+/// </para>
+/// <para>
+/// See the <see href="https://github.com/modelcontextprotocol/specification/blob/main/schema/">schema</see> for details.
+/// </para>
+/// </remarks>
+public class CompleteRequestParams : RequestParams
+{
+    /// <summary>
+    /// Gets or sets the reference's information.
+    /// </summary>
+    [JsonPropertyName("ref")]
+    public required Reference Ref { get; init; }
+
+    /// <summary>
+    /// Gets or sets the argument information for the completion request, specifying what is being completed
+    /// and the current partial input.
+    /// </summary>
+    [JsonPropertyName("argument")]
+    public required Argument Argument { get; init; }    
+}

src/ModelContextProtocol.Core/Protocol/CompleteResult.cs

@@ -0,0 +1,37 @@
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Represents the server's response to a <see cref="RequestMethods.CompletionComplete"/> request, 
+/// containing suggested values for a given argument.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <see cref="CompleteResult"/> is returned by the server in response to a <see cref="RequestMethods.CompletionComplete"/> 
+/// request from the client. It provides suggested completions or valid values for a specific argument in a tool or resource reference.
+/// </para>
+/// <para>
+/// The result contains a <see cref="Completion"/> object with suggested values, pagination information,
+/// and the total number of available completions. This is similar to auto-completion functionality in code editors.
+/// </para>
+/// <para>
+/// Clients typically use this to implement auto-suggestion features when users are inputting parameters
+/// for tool calls or resource references.
+/// </para>
+/// <para>
+/// See the <see href="https://github.com/modelcontextprotocol/specification/blob/main/schema/">schema</see> for details.
+/// </para>
+/// </remarks>
+public class CompleteResult
+{
+    /// <summary>
+    /// Gets or sets the completion object containing the suggested values and pagination information.
+    /// </summary>
+    /// <remarks>
+    /// If no completions are available for the given input, the <see cref="Completion.Values"/> 
+    /// collection will be empty.
+    /// </remarks>
+    [JsonPropertyName("completion")]
+    public Completion Completion { get; set; } = new Completion();
+}

src/ModelContextProtocol.Core/Protocol/Completion.cs

@@ -0,0 +1,39 @@
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Represents a completion object in the server's response to a <see cref="RequestMethods.CompletionComplete"/> request.
+/// </summary>
+/// <remarks>
+/// See the <see href="https://github.com/modelcontextprotocol/specification/blob/main/schema/">schema</see> for details.
+/// </remarks>
+public class Completion
+{
+    /// <summary>
+    /// Gets or sets an array of completion values (auto-suggestions) for the requested input.
+    /// </summary>
+    /// <remarks>
+    /// This collection contains the actual text strings to be presented to users as completion suggestions.
+    /// The array will be empty if no suggestions are available for the current input.
+    /// Per the specification, this should not exceed 100 items.
+    /// </remarks>
+    [JsonPropertyName("values")]
+    public string[] Values { get; set; } = [];
+
+    /// <summary>
+    /// Gets or sets the total number of completion options available.
+    /// </summary>
+    /// <remarks>
+    /// This can exceed the number of values actually sent in the response.
+    /// </remarks>
+    [JsonPropertyName("total")]
+    public int? Total { get; set; }
+
+    /// <summary>
+    /// Gets or sets an indicator as to whether there are additional completion options beyond 
+    /// those provided in the current response, even if the exact total is unknown.
+    /// </summary>
+    [JsonPropertyName("hasMore")]
+    public bool? HasMore { get; set; }
+}

src/ModelContextProtocol.Core/Protocol/CompletionsCapability.cs

@@ -0,0 +1,37 @@
+using ModelContextProtocol.Server;
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Represents the completions capability for providing auto-completion suggestions
+/// for prompt arguments and resource references.
+/// </summary>
+/// <remarks>
+/// <para>
+/// When enabled, this capability allows a Model Context Protocol server to provide 
+/// auto-completion suggestions. This capability is advertised to clients during the initialize handshake.
+/// </para>
+/// <para>
+/// The primary function of this capability is to improve the user experience by offering
+/// contextual suggestions for argument values or resource identifiers based on partial input.
+/// </para>
+/// <para>
+/// See the <see href="https://github.com/modelcontextprotocol/specification/blob/main/schema/">schema</see> for details.
+/// </para>
+/// </remarks>
+public class CompletionsCapability
+{
+    // Currently empty in the spec, but may be extended in the future.
+
+    /// <summary>
+    /// Gets or sets the handler for completion requests.
+    /// </summary>
+    /// <remarks>
+    /// This handler provides auto-completion suggestions for prompt arguments or resource references in the Model Context Protocol.
+    /// The handler receives a reference type (e.g., "ref/prompt" or "ref/resource") and the current argument value,
+    /// and should return appropriate completion suggestions.
+    /// </remarks>
+    [JsonIgnore]
+    public Func<RequestContext<CompleteRequestParams>, CancellationToken, ValueTask<CompleteResult>>? CompleteHandler { get; set; }
+}

src/ModelContextProtocol.Core/Protocol/Content.cs

@@ -0,0 +1,92 @@
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Represents content within the Model Context Protocol (MCP) that can contain text, binary data, or references to resources.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The <see cref="Content"/> class is a fundamental type in the MCP that can represent different forms of content
+/// based on the <see cref="Type"/> property. The main content types are:
+/// </para>
+/// <list type="bullet">
+///   <item><description>"text" - Textual content, stored in the <see cref="Text"/> property</description></item>
+///   <item><description>"image" - Image data, stored as base64 in the <see cref="Data"/> property with appropriate MIME type</description></item>
+///   <item><description>"audio" - Audio data, stored as base64 in the <see cref="Data"/> property with appropriate MIME type</description></item>
+///   <item><description>"resource" - Reference to a resource, accessed through the <see cref="Resource"/> property</description></item>
+/// </list>
+/// <para>
+/// This class is used extensively throughout the MCP for representing content in messages, tool responses,
+/// and other communication between clients and servers.
+/// </para>
+/// <para>
+/// See the <see href="https://github.com/modelcontextprotocol/specification/blob/main/schema/">schema</see> for more details.
+/// </para>
+/// </remarks>
+public class Content
+{
+    /// <summary>
+    /// Gets or sets the type of content.
+    /// </summary>
+    /// <remarks>
+    /// This determines the structure of the content object. Valid values include "image", "audio", "text", and "resource".
+    /// </remarks>
+    [JsonPropertyName("type")]
+    public string Type { get; set; } = "text";
+
+    /// <summary>
+    /// Gets or sets the text content of the message.
+    /// </summary>
+    [JsonPropertyName("text")]
+    public string? Text { get; set; }
+
+    /// <summary>
+    /// Gets or sets the base64-encoded image or audio data.
+    /// </summary>
+    [JsonPropertyName("data")]
+    public string? Data { get; set; }
+
+    /// <summary>
+    /// Gets or sets the MIME type (or "media type") of the content, specifying the format of the data.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This property is used when <see cref="Type"/> is "image", "audio", or "resource", to indicate the specific format of the binary data.
+    /// Common values include "image/png", "image/jpeg", "audio/wav", and "audio/mp3".
+    /// </para>
+    /// <para>
+    /// This property is required when the <see cref="Data"/> property contains binary content,
+    /// as it helps clients properly interpret and render the content.
+    /// </para>
+    /// </remarks>
+    [JsonPropertyName("mimeType")]
+    public string? MimeType { get; set; }
+
+    /// <summary>
+    /// Gets or sets the resource content of the message when <see cref="Type"/> is "resource".
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This property is used to embed or reference resource data within a message. It's only 
+    /// applicable when the <see cref="Type"/> property is set to "resource".
+    /// </para>
+    /// <para>
+    /// Resources can be either text-based (<see cref="TextResourceContents"/>) or 
+    /// binary (<see cref="BlobResourceContents"/>), allowing for flexible data representation.
+    /// Each resource has a URI that can be used for identification and retrieval.
+    /// </para>
+    /// </remarks>
+    [JsonPropertyName("resource")]
+    public ResourceContents? Resource { get; set; }
+
+    /// <summary>
+    /// Gets or sets optional annotations for the content.
+    /// </summary>
+    /// <remarks>
+    /// These annotations can be used to specify the intended audience (<see cref="Role.User"/>, <see cref="Role.Assistant"/>, or both)
+    /// and the priority level of the content. Clients can use this information to filter or prioritize content for different roles.
+    /// </remarks>
+    [JsonPropertyName("annotations")]
+    public Annotations? Annotations { get; init; }
+}

src/ModelContextProtocol.Core/Protocol/ContextInclusion.cs

@@ -0,0 +1,31 @@
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Specifies the context inclusion options for a request in the Model Context Protocol (MCP).
+/// </summary>
+/// <remarks>
+/// See the <see href="https://github.com/modelcontextprotocol/specification/blob/main/schema/">schema</see> for details.
+/// </remarks>
+[JsonConverter(typeof(CustomizableJsonStringEnumConverter<ContextInclusion>))]
+public enum ContextInclusion
+{
+    /// <summary>
+    /// Indicates that no context should be included.
+    /// </summary>
+    [JsonStringEnumMemberName("none")]
+    None,
+
+    /// <summary>
+    /// Indicates that context from the server that sent the request should be included.
+    /// </summary>
+    [JsonStringEnumMemberName("thisServer")]
+    ThisServer,
+
+    /// <summary>
+    /// Indicates that context from all servers that the client is connected to should be included.
+    /// </summary>
+    [JsonStringEnumMemberName("allServers")]
+    AllServers
+}

src/ModelContextProtocol.Core/Protocol/CreateMessageRequestParams.cs

@@ -0,0 +1,103 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Represents the parameters used with a <see cref="RequestMethods.SamplingCreateMessage"/> 
+/// request from a server to sample an LLM via the client.
+/// </summary>
+/// <remarks>
+/// See the <see href="https://github.com/modelcontextprotocol/specification/blob/main/schema/">schema</see> for details.
+/// </remarks>
+public class CreateMessageRequestParams : RequestParams
+{
+    /// <summary>
+    /// Gets or sets an indication as to which server contexts should be included in the prompt.
+    /// </summary>
+    /// <remarks>
+    /// The client may ignore this request.
+    /// </remarks>
+    [JsonPropertyName("includeContext")]
+    public ContextInclusion? IncludeContext { get; init; }
+
+    /// <summary>
+    /// Gets or sets the maximum number of tokens to generate in the LLM response, as requested by the server.
+    /// </summary>
+    /// <remarks>
+    /// A token is generally a word or part of a word in the text. Setting this value helps control 
+    /// response length and computation time. The client may choose to sample fewer tokens than requested.
+    /// </remarks>
+    [JsonPropertyName("maxTokens")]
+    public int? MaxTokens { get; init; }
+
+    /// <summary>
+    /// Gets or sets the messages requested by the server to be included in the prompt.
+    /// </summary>
+    [JsonPropertyName("messages")]
+    public required IReadOnlyList<SamplingMessage> Messages { get; init; }
+
+    /// <summary>
+    /// Gets or sets optional metadata to pass through to the LLM provider.
+    /// </summary>
+    /// <remarks>
+    /// The format of this metadata is provider-specific and can include model-specific settings or
+    /// configuration that isn't covered by standard parameters. This allows for passing custom parameters 
+    /// that are specific to certain AI models or providers.
+    /// </remarks>
+    [JsonPropertyName("metadata")]
+    public JsonElement? Metadata { get; init; }
+
+    /// <summary>
+    /// Gets or sets the server's preferences for which model to select.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// The client may ignore these preferences.
+    /// </para>
+    /// <para>
+    /// These preferences help the client make an appropriate model selection based on the server's priorities
+    /// for cost, speed, intelligence, and specific model hints.
+    /// </para>
+    /// <para>
+    /// When multiple dimensions are specified (cost, speed, intelligence), the client should balance these
+    /// based on their relative values. If specific model hints are provided, the client should evaluate them
+    /// in order and prioritize them over numeric priorities.
+    /// </para>
+    /// </remarks>
+    [JsonPropertyName("modelPreferences")]
+    public ModelPreferences? ModelPreferences { get; init; }
+
+    /// <summary>
+    /// Gets or sets optional sequences of characters that signal the LLM to stop generating text when encountered.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// When the model generates any of these sequences during sampling, text generation stops immediately,
+    /// even if the maximum token limit hasn't been reached. This is useful for controlling generation 
+    /// endings or preventing the model from continuing beyond certain points.
+    /// </para>
+    /// <para>
+    /// Stop sequences are typically case-sensitive, and typically the LLM will only stop generation when a produced
+    /// sequence exactly matches one of the provided sequences. Common uses include ending markers like "END", punctuation
+    /// like ".", or special delimiter sequences like "###".
+    /// </para>
+    /// </remarks>
+    [JsonPropertyName("stopSequences")]
+    public IReadOnlyList<string>? StopSequences { get; init; }
+
+    /// <summary>
+    /// Gets or sets an optional system prompt the server wants to use for sampling.
+    /// </summary>
+    /// <remarks>
+    /// The client may modify or omit this prompt.
+    /// </remarks>
+    [JsonPropertyName("systemPrompt")]
+    public string? SystemPrompt { get; init; }
+
+    /// <summary>
+    /// Gets or sets the temperature to use for sampling, as requested by the server.
+    /// </summary>
+    [JsonPropertyName("temperature")]
+    public float? Temperature { get; init; }
+}

src/ModelContextProtocol.Core/Protocol/CreateMessageResult.cs

@@ -0,0 +1,53 @@
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Represents a client's response to a <see cref="RequestMethods.SamplingCreateMessage"/> from the server.
+/// </summary>
+/// <remarks>
+/// See the <see href="https://github.com/modelcontextprotocol/specification/blob/main/schema/">schema</see> for details.
+/// </remarks>
+public class CreateMessageResult
+{
+    /// <summary>
+    /// Gets or sets the content of the message.
+    /// </summary>
+    [JsonPropertyName("content")]
+    public required Content Content { get; init; }
+
+    /// <summary>
+    /// Gets or sets the name of the model that generated the message.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This should contain the specific model identifier such as "claude-3-5-sonnet-20241022" or "o3-mini".
+    /// </para>
+    /// <para>
+    /// This property allows the server to know which model was used to generate the response,
+    /// enabling appropriate handling based on the model's capabilities and characteristics.
+    /// </para>
+    /// </remarks>
+    [JsonPropertyName("model")]
+    public required string Model { get; init; }
+
+    /// <summary>
+    /// Gets or sets the reason why message generation (sampling) stopped, if known.
+    /// </summary>
+    /// <remarks>
+    /// Common values include:
+    /// <list type="bullet">
+    ///   <item><term>endTurn</term><description>The model naturally completed its response.</description></item>
+    ///   <item><term>maxTokens</term><description>The response was truncated due to reaching token limits.</description></item>
+    ///   <item><term>stopSequence</term><description>A specific stop sequence was encountered during generation.</description></item>
+    /// </list>
+    /// </remarks>
+    [JsonPropertyName("stopReason")]
+    public string? StopReason { get; init; }
+
+    /// <summary>
+    /// Gets or sets the role of the user who generated the message.
+    /// </summary>
+    [JsonPropertyName("role")]
+    public required Role Role { get; init; }
+}

src/ModelContextProtocol.Core/Protocol/ElicitRequestParams.cs

@@ -0,0 +1,230 @@
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Represents a message issued from the server to elicit additional information from the user via the client.
+/// </summary>
+public class ElicitRequestParams
+{
+    /// <summary>
+    /// Gets or sets the message to present to the user.
+    /// </summary>
+    [JsonPropertyName("message")]
+    public string Message { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets the requested schema.
+    /// </summary>
+    /// <remarks>
+    /// May be one of <see cref="StringSchema"/>, <see cref="NumberSchema"/>, <see cref="BooleanSchema"/>, or <see cref="EnumSchema"/>.
+    /// </remarks>
+    [JsonPropertyName("requestedSchema")]
+    [field: MaybeNull]
+    public RequestSchema RequestedSchema
+    {
+        get => field ??= new RequestSchema();
+        set => field = value;
+    }
+
+    /// <summary>Represents a request schema used in an elicitation request.</summary>
+    public class RequestSchema
+    {
+        /// <summary>Gets the type of the schema.</summary>
+        /// <remarks>This is always "object".</remarks>
+        [JsonPropertyName("type")]
+        public string Type => "object";
+
+        /// <summary>Gets or sets the properties of the schema.</summary>
+        [JsonPropertyName("properties")]
+        [field: MaybeNull]
+        public IDictionary<string, PrimitiveSchemaDefinition> Properties
+        {
+            get => field ??= new Dictionary<string, PrimitiveSchemaDefinition>();
+            set
+            {
+                Throw.IfNull(value);
+                field = value;
+            }
+        }
+
+        /// <summary>Gets or sets the required properties of the schema.</summary>
+        [JsonPropertyName("required")]
+        public IList<string>? Required { get; set; }
+    }
+
+
+    /// <summary>
+    /// Represents restricted subset of JSON Schema: 
+    /// <see cref="StringSchema"/>, <see cref="NumberSchema"/>, <see cref="BooleanSchema"/>, or <see cref="EnumSchema"/>.
+    /// </summary>
+    [JsonDerivedType(typeof(BooleanSchema))]
+    [JsonDerivedType(typeof(EnumSchema))]
+    [JsonDerivedType(typeof(NumberSchema))]
+    [JsonDerivedType(typeof(StringSchema))]
+    public abstract class PrimitiveSchemaDefinition
+    {
+        protected private PrimitiveSchemaDefinition()
+        {
+        }
+    }
+
+    /// <summary>Represents a schema for a string type.</summary>
+    public sealed class StringSchema : PrimitiveSchemaDefinition
+    {
+        /// <summary>Gets the type of the schema.</summary>
+        /// <remarks>This is always "string".</remarks>
+        [JsonPropertyName("type")]
+        public string Type => "string";
+
+        /// <summary>Gets or sets a title for the string.</summary>
+        [JsonPropertyName("title")]
+        public string? Title { get; set; }
+
+        /// <summary>Gets or sets a description for the string.</summary>
+        [JsonPropertyName("description")]
+        public string? Description { get; set; }
+
+        /// <summary>Gets or sets the minimum length for the string.</summary>
+        [JsonPropertyName("minLength")]
+        public int? MinLength
+        {
+            get => field;
+            set
+            {
+                if (value < 0)
+                {
+                    throw new ArgumentOutOfRangeException(nameof(value), "Minimum length cannot be negative.");
+                }
+
+                field = value;
+            }
+        }
+
+        /// <summary>Gets or sets the maximum length for the string.</summary>
+        [JsonPropertyName("maxLength")]
+        public int? MaxLength
+        {
+            get => field;
+            set
+            {
+                if (value < 0)
+                {
+                    throw new ArgumentOutOfRangeException(nameof(value), "Maximum length cannot be negative.");
+                }
+
+                field = value;
+            }
+        }
+
+        /// <summary>Gets or sets a specific format for the string ("email", "uri", "date", or "date-time").</summary>
+        [JsonPropertyName("format")]
+        public string? Format
+        {
+            get => field;
+            set
+            {
+                if (value is not (null or "email" or "uri" or "date" or "date-time"))
+                {
+                    throw new ArgumentException("Format must be 'email', 'uri', 'date', or 'date-time'.", nameof(value));
+                }
+
+                field = value;
+            }
+        }
+    }
+
+    /// <summary>Represents a schema for a number or integer type.</summary>
+    public sealed class NumberSchema : PrimitiveSchemaDefinition
+    {
+        /// <summary>Gets the type of the schema.</summary>
+        /// <remarks>This should be "number" or "integer".</remarks>
+        [JsonPropertyName("type")]
+        [field: MaybeNull]
+        public string Type
+        {
+            get => field ??= "number";
+            set
+            {
+                if (value is not ("number" or "integer"))
+                {
+                    throw new ArgumentException("Type must be 'number' or 'integer'.", nameof(value));
+                }
+
+                field = value;
+            }
+        }
+
+        /// <summary>Gets or sets a title for the number input.</summary>
+        [JsonPropertyName("title")]
+        public string? Title { get; set; }
+
+        /// <summary>Gets or sets a description for the number input.</summary>
+        [JsonPropertyName("description")]
+        public string? Description { get; set; }
+
+        /// <summary>Gets or sets the minimum allowed value.</summary>
+        [JsonPropertyName("minimum")]
+        public double? Minimum { get; set; }
+
+        /// <summary>Gets or sets the maximum allowed value.</summary>
+        [JsonPropertyName("maximum")]
+        public double? Maximum { get; set; }
+    }
+
+    /// <summary>Represents a schema for a Boolean type.</summary>
+    public sealed class BooleanSchema : PrimitiveSchemaDefinition
+    {
+        /// <summary>Gets the type of the schema.</summary>
+        /// <remarks>This is always "boolean".</remarks>
+        [JsonPropertyName("type")]
+        public string Type => "boolean";
+
+        /// <summary>Gets or sets a title for the Boolean.</summary>
+        [JsonPropertyName("title")]
+        public string? Title { get; set; }
+
+        /// <summary>Gets or sets a description for the Boolean.</summary>
+        [JsonPropertyName("description")]
+        public string? Description { get; set; }
+
+        /// <summary>Gets or sets the default value for the Boolean.</summary>
+        [JsonPropertyName("default")]
+        public bool? Default { get; set; }
+    }
+
+    /// <summary>Represents a schema for an enum type.</summary>
+    public sealed class EnumSchema : PrimitiveSchemaDefinition
+    {
+        /// <summary>Gets the type of the schema.</summary>
+        /// <remarks>This is always "string".</remarks>
+        [JsonPropertyName("type")]
+        public string Type => "string";
+
+        /// <summary>Gets or sets a title for the enum.</summary>
+        [JsonPropertyName("title")]
+        public string? Title { get; set; }
+
+        /// <summary>Gets or sets a description for the enum.</summary>
+        [JsonPropertyName("description")]
+        public string? Description { get; set; }
+
+        /// <summary>Gets or sets the list of allowed string values for the enum.</summary>
+        [JsonPropertyName("enum")]
+        [field: MaybeNull]
+        public IList<string> Enum
+        {
+            get => field ??= [];
+            set
+            {
+                Throw.IfNull(value);
+                field = value;
+            }
+        }
+
+        /// <summary>Gets or sets optional display names corresponding to the enum values.</summary>
+        [JsonPropertyName("enumNames")]
+        public IList<string>? EnumNames { get; set; }
+    }
+}

src/ModelContextProtocol.Core/Protocol/ElicitResult.cs

@@ -0,0 +1,41 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Represents the client's response to an elicitation request.
+/// </summary>
+public class ElicitResult
+{
+    /// <summary>
+    /// Gets or sets the user action in response to the elicitation.
+    /// </summary>
+    /// <remarks>
+    /// <list type="bullet">
+    ///   <item>
+    ///     <term>"accept"</term>
+    ///     <description>User submitted the form/confirmed the action</description>
+    ///   </item>
+    ///   <item>
+    ///     <term>"decline"</term>
+    ///     <description>User explicitly declined the action</description>
+    ///   </item>
+    ///   <item>
+    ///     <term>"cancel"</term>
+    ///     <description>User dismissed without making an explicit choice</description>
+    ///   </item>
+    /// </list>
+    /// </remarks>
+    [JsonPropertyName("action")]
+    public string Action { get; set; } = "cancel";
+
+    /// <summary>
+    /// Gets or sets the submitted form data.
+    /// </summary>
+    /// <remarks>
+    /// This is typically omitted if the action is "cancel" or "decline".
+    /// </remarks>
+    [JsonPropertyName("content")]
+    public JsonElement? Content { get; set; }
+}

src/ModelContextProtocol.Core/Protocol/ElicitationCapability.cs

@@ -0,0 +1,36 @@
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Represents the capability for a client to provide server-requested additional information during interactions.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This capability enables the MCP client to respond to elicitation requests from an MCP server.
+/// </para>
+/// <para>
+/// When this capability is enabled, an MCP server can request the client to provide additional information
+/// during interactions. The client must set a <see cref="ElicitationHandler"/> to process these requests.
+/// </para>
+/// </remarks>
+public class ElicitationCapability
+{
+    // Currently empty in the spec, but may be extended in the future.
+
+    /// <summary>
+    /// Gets or sets the handler for processing <see cref="RequestMethods.ElicitationCreate"/> requests.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This handler function is called when an MCP server requests the client to provide additional
+    /// information during interactions. The client must set this property for the elicitation capability to work.
+    /// </para>
+    /// <para>
+    /// The handler receives message parameters and a cancellation token.
+    /// It should return a <see cref="ElicitResult"/> containing the response to the elicitation request.
+    /// </para>
+    /// </remarks>
+    [JsonIgnore]
+    public Func<ElicitRequestParams?, CancellationToken, ValueTask<ElicitResult>>? ElicitationHandler { get; set; }
+}

src/ModelContextProtocol.Core/Protocol/EmptyResult.cs

@@ -0,0 +1,13 @@
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Represents an empty result object for operations that need to indicate successful completion 
+/// but don't need to return any specific data.
+/// </summary>
+public class EmptyResult
+{
+    [JsonIgnore]
+    internal static EmptyResult Instance { get; } = new();
+}

src/ModelContextProtocol.Core/Protocol/GetPromptRequestParams.cs

@@ -0,0 +1,31 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Represents the parameters used with a <see cref="RequestMethods.PromptsGet"/> request from a client to get a prompt provided by a server.
+/// </summary>
+/// <remarks>
+/// The server will respond with a <see cref="GetPromptResult"/> containing the resulting prompt.
+/// See the <see href="https://github.com/modelcontextprotocol/specification/blob/main/schema/">schema</see> for details.
+/// </remarks>
+public class GetPromptRequestParams : RequestParams
+{
+    /// <summary>
+    /// Gets or sets the name of the prompt.
+    /// </summary>
+    [JsonPropertyName("name")]
+    public required string Name { get; init; }
+
+    /// <summary>
+    /// Gets or sets arguments to use for templating the prompt when retrieving it from the server.
+    /// </summary>
+    /// <remarks>
+    /// Typically, these arguments are used to replace placeholders in prompt templates. The keys in this dictionary
+    /// should match the names defined in the prompt's <see cref="Prompt.Arguments"/> list. However, the server may
+    /// choose to use these arguments in any way it deems appropriate to generate the prompt.
+    /// </remarks>
+    [JsonPropertyName("arguments")]
+    public IReadOnlyDictionary<string, JsonElement>? Arguments { get; init; }
+}