mcp 0.25.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 829c2bc3c3644f2a7edcf5fd44b96d87887c37da3a4cf4766eed79a2676425ee
-  data.tar.gz: 1a168f15a16ad704db47e8c8c2aa7be3f4f869af2a5199fa54d44b4a05990aa0
+  metadata.gz: 356017978ae1c4a455d50d37bd9a178aba8989ee5e001bed8ab309977071f71f
+  data.tar.gz: cc62cd7e64421b3a45c49d60709610cf0bf552183b4a2f08c2adef9e0bde2e29
 SHA512:
-  metadata.gz: e6ca51112faf60a4a2b9f5be2db20f9fe25b6581ca327708f483c03f021b9a68ce8df8c3342e5430132ac670103a26d4ac2f9617e3e0358e074745d6fa4c7743
-  data.tar.gz: a57eea28ea7e173422e855702789780381032e888bed42eb42900251e05f8a2806df4220c50c0727423d6c5a8e9124127cdc53e9e9bf34170e6a7c2afa058e7a
+  metadata.gz: 5464fcaa9535b838cd7b3bccffa7c9d4f461cb4ca91ac08067d9f9fa97bde4124bd9214c57c6d7928ce4315135dcabcfff445d48b24f325f0acaace0b8af5fc9
+  data.tar.gz: 118dba080f17a6464892b4d65a57e147ffe405539457940a7f25184ead416af03accf4ac27809e5b4c0fb2d1a6942e58edcc8f73b71c88fc364bf658861353f0

data/README.md

@@ -872,6 +872,53 @@ class WeatherTool < MCP::Tool
 end
 ```
 
+### Tool Responses with Image, Audio, and Embedded Resources
+
+Tool responses are not limited to text. The `MCP::Content` module provides `Image`, `Audio`, and `EmbeddedResource` content types,
+which serialize to the `image`, `audio`, and `resource` content blocks defined by the MCP spec. Image and audio data is passed as
+a base64-encoded string together with its MIME type:
+
+```ruby
+class ChartTool < MCP::Tool
+  description "Render a chart as a PNG image"
+
+  def self.call(server_context:)
+    MCP::Tool::Response.new([
+      MCP::Content::Text.new("Here is the rendered chart:").to_h,
+      MCP::Content::Image.new(Base64.strict_encode64(render_chart_png), "image/png").to_h,
+    ])
+  end
+end
+
+class SpeechTool < MCP::Tool
+  description "Synthesize speech audio"
+
+  def self.call(server_context:)
+    MCP::Tool::Response.new([
+      MCP::Content::Audio.new(Base64.strict_encode64(synthesize_wav), "audio/wav").to_h,
+    ])
+  end
+end
+```
+
+An embedded resource wraps `MCP::Resource::TextContents` or `MCP::Resource::BlobContents`, allowing a tool to return resource contents inline:
+
+```ruby
+class ReportTool < MCP::Tool
+  description "Return a report as an embedded resource"
+
+  def self.call(server_context:)
+    contents = MCP::Resource::TextContents.new(
+      uri: "report://monthly",
+      mime_type: "application/json",
+      text: { total: 42 }.to_json,
+    )
+
+    MCP::Tool::Response.new([MCP::Content::EmbeddedResource.new(contents).to_h])
+  end
+end
+```
+
 ### Prompts
 
 MCP spec includes [Prompts](https://modelcontextprotocol.io/specification/latest/server/prompts), which enable servers to define reusable prompt templates and workflows that clients can easily surface to users and LLMs.
@@ -1010,6 +1057,49 @@ The server will handle prompt listing and execution through the MCP protocol met
 - `prompts/list` - Lists all registered prompts and their schemas
 - `prompts/get` - Retrieves and executes a specific prompt with arguments
 
+### Prompts with Image and Embedded Resource Content
+
+Prompt messages are not limited to text. The same `MCP::Content` types used in tool responses can be used as message content,
+letting a prompt template include images or inline resource contents. Unlike tool responses, the content object is passed directly rather than as a hash;
+`MCP::Prompt::Message` serializes it when the prompt result is returned:
+
+```ruby
+class CodeReviewPrompt < MCP::Prompt
+  prompt_name "code_review"
+  description "Review a source file with an accompanying diagram"
+  arguments [
+    MCP::Prompt::Argument.new(name: "file_uri", description: "URI of the file to review", required: true),
+  ]
+
+  class << self
+    def template(args, server_context:)
+      MCP::Prompt::Result.new(
+        messages: [
+          MCP::Prompt::Message.new(
+            role: "user",
+            content: MCP::Content::EmbeddedResource.new(
+              MCP::Resource::TextContents.new(
+                uri: args["file_uri"],
+                mime_type: "text/x-ruby",
+                text: read_source(args["file_uri"]),
+              ),
+            ),
+          ),
+          MCP::Prompt::Message.new(
+            role: "user",
+            content: MCP::Content::Image.new(architecture_diagram_base64, "image/png"),
+          ),
+          MCP::Prompt::Message.new(
+            role: "user",
+            content: MCP::Content::Text.new("Please review the code above, using the diagram for context."),
+          ),
+        ],
+      )
+    end
+  end
+end
+```
+
 ### Resources
 
 MCP spec includes [Resources](https://modelcontextprotocol.io/specification/latest/server/resources).
@@ -1126,6 +1216,34 @@ server.resources_read_handler do |params|
 end
 ```
 
+### Reading Binary Resources
+
+For binary resources, respond with a base64-encoded `blob` field instead of `text`.
+The `MCP::Resource::TextContents` and `MCP::Resource::BlobContents` classes build the two contents shapes defined by the spec:
+
+```ruby
+server.resources_read_handler do |params|
+  case params[:uri]
+  when "file:///logo.png"
+    [
+      MCP::Resource::BlobContents.new(
+        uri: params[:uri],
+        mime_type: "image/png",
+        data: Base64.strict_encode64(File.binread("logo.png")),
+      ).to_h,
+    ]
+  else
+    [
+      MCP::Resource::TextContents.new(
+        uri: params[:uri],
+        mime_type: "text/plain",
+        text: "Hello from example resource!",
+      ).to_h,
+    ]
+  end
+end
+```
+
 ### Resource Templates
 
 Resource templates follow the same pattern. Class-based templates declare a `uri_template` and
@@ -1201,6 +1319,31 @@ server = MCP::Server.new(
 )
 ```
 
+Registered templates are listed through the `resources/templates/list` protocol method.
+To serve reads for URIs that match a template, extract the variable parts of the URI in your `resources_read_handler`:
+
+```ruby
+resource_template = MCP::ResourceTemplate.new(
+  uri_template: "file:///items/{item_id}",
+  name: "item",
+  mime_type: "application/json",
+)
+
+server = MCP::Server.new(name: "my_server", resource_templates: [resource_template])
+
+server.resources_read_handler do |params|
+  if (match = params[:uri].match(%r{\Afile:///items/(?<item_id>[^/]+)\z}))
+    [{
+      uri: params[:uri],
+      mimeType: "application/json",
+      text: { id: match[:item_id] }.to_json,
+    }]
+  else
+    raise MCP::Server::ResourceNotFoundError.new(params[:uri], params)
+  end
+end
+```
+
 ### Roots
 
 The Model Context Protocol allows servers to request filesystem roots from clients through the `roots/list` method.
@@ -1793,6 +1936,40 @@ server.define_tool(name: "collect_contact", description: "Collect contact info")
 end
 ```
 
+The `requested_schema` must be a flat object schema: a top-level `type: "object"` whose `properties` are limited to
+primitive types (`string`, `number`, `integer`, `boolean`). Nested objects and arrays are not allowed, which keeps
+the schema simple enough for clients to render as a form. Per the MCP specification, the client validates
+the user's input against this schema before returning it, so the `content` of an `accept` response matches the requested shape.
+
+#### Default Values and Enums
+
+Properties may declare a `default` value (SEP-1034), which clients use to pre-fill the form.
+String properties may declare `enum` values, optionally with human-readable `enumNames` (SEP-1330), which clients render as a choice list:
+
+```ruby
+server.define_tool(name: "configure_deploy", description: "Configure a deployment") do |server_context:|
+  result = server_context.create_form_elicitation(
+    message: "Configure the deployment",
+    requested_schema: {
+      type: "object",
+      properties: {
+        replicas: { type: "integer", default: 3 },
+        verbose: { type: "boolean", default: false },
+        environment: {
+          type: "string",
+          enum: ["dev", "staging", "prod"],
+          enumNames: ["Development", "Staging", "Production"],
+          default: "dev",
+        },
+      },
+      required: ["environment"],
+    },
+  )
+
+  MCP::Tool::Response.new([{ type: "text", text: "Deploying to #{result[:content][:environment]}" }])
+end
+```
+
 #### URL Mode
 
 URL mode directs the user to an external URL for out-of-band interactions such as OAuth flows:

data/lib/mcp/client/tool.rb

@@ -3,13 +3,14 @@
 module MCP
   class Client
     class Tool
-      attr_reader :name, :description, :input_schema, :output_schema
+      attr_reader :name, :description, :input_schema, :output_schema, :annotations
 
-      def initialize(name:, description:, input_schema:, output_schema: nil)
+      def initialize(name:, description:, input_schema:, output_schema: nil, annotations: nil)
         @name = name
         @description = description
         @input_schema = input_schema
         @output_schema = output_schema
+        @annotations = annotations
       end
     end
   end

data/lib/mcp/client.rb

@@ -166,6 +166,7 @@ module MCP
           description: tool["description"],
           input_schema: tool["inputSchema"],
           output_schema: tool["outputSchema"],
+          annotations: tool["annotations"],
         )
       end
 

data/lib/mcp/configuration.rb

@@ -2,12 +2,27 @@
 
 module MCP
   class Configuration
-    LATEST_STABLE_PROTOCOL_VERSION = "2025-11-25"
+    LATEST_STABLE_PROTOCOL_VERSION = "2026-07-28"
     SUPPORTED_STABLE_PROTOCOL_VERSIONS = [
-      LATEST_STABLE_PROTOCOL_VERSION, "2025-06-18", "2025-03-26", "2024-11-05",
+      LATEST_STABLE_PROTOCOL_VERSION, "2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05",
     ].freeze
     DEFAULT_NEGOTIATED_PROTOCOL_VERSION = "2025-03-26"
 
+    # Protocol versions of the stateless "modern" lifecycle introduced by the MCP 2026-07-28 spec release (SEP-2575).
+    # 2026-07-28 serves both lifecycles of the dual-era model: it is negotiable through the legacy `initialize`
+    # handshake (so it also appears in `SUPPORTED_STABLE_PROTOCOL_VERSIONS`), and it is the version of the modern
+    # lifecycle, where each request carries its own version in `_meta` and is validated against this list
+    # independently, with no handshake.
+    # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575
+    LATEST_MODERN_PROTOCOL_VERSION = "2026-07-28"
+    SUPPORTED_MODERN_PROTOCOL_VERSIONS = [LATEST_MODERN_PROTOCOL_VERSION].freeze
+
+    class << self
+      def modern_protocol_version?(version)
+        SUPPORTED_MODERN_PROTOCOL_VERSIONS.include?(version)
+      end
+    end
+
     attr_writer :exception_reporter, :around_request
 
     # @deprecated Use {#around_request=} instead. `instrumentation_callback`

data/lib/mcp/error_codes.rb

@@ -3,18 +3,24 @@
 module MCP
   # MCP-specific JSON-RPC error codes, complementing the generic codes in `JsonRpcHandler::ErrorCode`.
   #
-  # Both constants below are introduced by the stateless lifecycle of the MCP 2026-07-28 draft (SEP-2575):
-  # `UNSUPPORTED_PROTOCOL_VERSION` rejects a request whose `_meta`-carried protocol version the server does not
-  # support (`error.data: { supported: [...], requested: "..." }`), and `MISSING_REQUIRED_CLIENT_CAPABILITY`
-  # rejects a request that requires a client capability the request did not declare
-  # (`error.data: { requiredCapabilities: {...} }`). The SDK exports the vocabulary; it does not raise
-  # these codes itself yet.
+  # All three constants below are introduced by the stateless lifecycle of the MCP 2026-07-28 draft (SEP-2575):
   #
-  # The values come from the spec's MCP-specific error code block, which is allocated sequentially from
-  # `-32020` toward `-32099`. `-32020` (`HEADER_MISMATCH`, SEP-2243) precedes the two codes defined here.
+  # - `HEADER_MISMATCH` rejects an HTTP request whose headers do not match the corresponding body values,
+  #   or whose required headers are missing or malformed (no `error.data`). It is reserved for
+  #   the Streamable HTTP transport, since headers do not exist on stdio.
+  # - `MISSING_REQUIRED_CLIENT_CAPABILITY` rejects a request that requires a client capability
+  #   the request did not declare (`error.data: { requiredCapabilities: {...} }`).
+  #   Raised via `Server::MissingRequiredClientCapabilityError`.
+  # - `UNSUPPORTED_PROTOCOL_VERSION` rejects a request whose `_meta`-carried protocol version the server
+  #   does not support (`error.data: { supported: [...], requested: "..." }`). Raised via
+  #   `Server::UnsupportedProtocolVersionError`.
+  #
+  # The values come from the spec's MCP-specific error code block, which is allocated sequentially from `-32020`
+  # toward `-32099`.
   #
   # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575
   module ErrorCodes
+    HEADER_MISMATCH = -32020
     MISSING_REQUIRED_CLIENT_CAPABILITY = -32021
     UNSUPPORTED_PROTOCOL_VERSION = -32022
   end

data/lib/mcp/request_envelope.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module MCP
+  # The per-request `_meta` envelope of the stateless "modern" lifecycle (MCP 2026-07-28, SEP-2575).
+  # The modern lifecycle has no `initialize` handshake: every request identifies its protocol version,
+  # client, and client capabilities through reserved `_meta` keys, and the server validates
+  # each request independently. Servers MUST NOT infer capabilities from prior requests,
+  # which is why the envelope is a per-request value object rather than session state.
+  #
+  # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575
+  class RequestEnvelope
+    PROTOCOL_VERSION_META_KEY = "io.modelcontextprotocol/protocolVersion"
+    CLIENT_INFO_META_KEY = "io.modelcontextprotocol/clientInfo"
+    CLIENT_CAPABILITIES_META_KEY = "io.modelcontextprotocol/clientCapabilities"
+
+    # Optional per-request log level, replacing the `logging/setLevel` RPC in the modern lifecycle.
+    # Deprecated as of 2026-07-28 (SEP-2577) but still part of the wire format.
+    LOG_LEVEL_META_KEY = "io.modelcontextprotocol/logLevel"
+
+    REQUIRED_META_KEYS = [
+      PROTOCOL_VERSION_META_KEY,
+      CLIENT_INFO_META_KEY,
+      CLIENT_CAPABILITIES_META_KEY,
+    ].freeze
+
+    class << self
+      # A request is classified as modern only when the full REQUIRED triple is present,
+      # matching the TypeScript SDK's `RequestMetaEnvelopeSchema` and the Python SDK's `_has_modern_envelope`.
+      # A partial triple is treated as legacy so existing `_meta` usage (`progressToken`, trace context) keeps
+      # flowing through the legacy path.
+      def modern?(params)
+        meta = extract_meta(params)
+        return false unless meta.is_a?(Hash)
+
+        REQUIRED_META_KEYS.all? { |key| !read(meta, key).nil? }
+      end
+
+      # Parses and validates the envelope. `request` is only used to enrich the raised error;
+      # callers dispatching notifications can omit it.
+      def parse!(params, request: nil)
+        meta = extract_meta(params)
+        meta = {} unless meta.is_a?(Hash)
+
+        protocol_version = read(meta, PROTOCOL_VERSION_META_KEY)
+        client_info = read(meta, CLIENT_INFO_META_KEY)
+        client_capabilities = read(meta, CLIENT_CAPABILITIES_META_KEY)
+
+        unless protocol_version.is_a?(String) && client_info.is_a?(Hash) && client_capabilities.is_a?(Hash)
+          raise Server::RequestHandlerError.new(
+            "Invalid Request: modern requests require `#{REQUIRED_META_KEYS.join("`, `")}` in `_meta`",
+            request,
+            error_type: :invalid_request,
+          )
+        end
+
+        unless Configuration.modern_protocol_version?(protocol_version)
+          raise Server::UnsupportedProtocolVersionError.new(protocol_version, request)
+        end
+
+        new(
+          protocol_version: protocol_version,
+          client_info: client_info,
+          client_capabilities: client_capabilities,
+          log_level: read(meta, LOG_LEVEL_META_KEY),
+        )
+      end
+
+      private
+
+      # `Server#handle` accepts hashes parsed with either symbol or string keys, so read both forms
+      # (the same tolerance as `Server#handle_cancelled_notification`).
+      def extract_meta(params)
+        return unless params.is_a?(Hash)
+
+        meta = params[:_meta]
+        meta.nil? ? params["_meta"] : meta
+      end
+
+      def read(meta, key)
+        value = meta[key.to_sym]
+        value.nil? ? meta[key] : value
+      end
+    end
+
+    attr_reader :protocol_version, :client_info, :client_capabilities, :log_level
+
+    def initialize(protocol_version:, client_info:, client_capabilities:, log_level: nil)
+      @protocol_version = protocol_version
+      @client_info = client_info
+      @client_capabilities = client_capabilities
+      @log_level = log_level
+      freeze
+    end
+  end
+end

data/lib/mcp/server.rb

@@ -59,6 +59,41 @@ module MCP
       end
     end
 
+    # Raised when a request carries a protocol version the server does not support under the stateless lifecycle of
+    # MCP 2026-07-28 (SEP-2575). Maps to JSON-RPC error `-32022` with `data: { supported: [...], requested: "..." }`
+    # so the client can select a mutually supported version and retry.
+    #
+    # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575
+    class UnsupportedProtocolVersionError < RequestHandlerError
+      def initialize(requested, request = nil, supported: Configuration::SUPPORTED_MODERN_PROTOCOL_VERSIONS)
+        super(
+          "Unsupported protocol version",
+          request,
+          error_type: :unsupported_protocol_version,
+          error_code: ErrorCodes::UNSUPPORTED_PROTOCOL_VERSION,
+          error_data: { supported: supported, requested: requested || "unknown" },
+        )
+      end
+    end
+
+    # Raised when processing a request requires a client capability the request did not declare in `_meta`
+    # (`io.modelcontextprotocol/clientCapabilities`). Per SEP-2575, servers MUST NOT rely on capabilities
+    # the client has not declared. Maps to JSON-RPC error `-32021` with `data: { requiredCapabilities: {...} }`
+    # listing the missing capabilities.
+    #
+    # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575
+    class MissingRequiredClientCapabilityError < RequestHandlerError
+      def initialize(required_capabilities, request = nil)
+        super(
+          "Missing required client capability",
+          request,
+          error_type: :missing_required_client_capability,
+          error_code: ErrorCodes::MISSING_REQUIRED_CLIENT_CAPABILITY,
+          error_data: { requiredCapabilities: required_capabilities },
+        )
+      end
+    end
+
     # Raised when a requested resource URI does not exist. Per SEP-2164,
     # resource-not-found errors use the standard JSON-RPC Invalid Params code (-32602)
     # with the requested URI in the error `data` member. Raise this from
@@ -745,11 +780,15 @@ module MCP
 
       progress_token = request.dig(:_meta, :progressToken)
 
-      result = call_tool_with_args(
+      response = call_tool_with_args(
         tool, arguments, server_context_with_meta(request), progress_token: progress_token, session: session, related_request_id: related_request_id, cancellation: cancellation
       )
+      result = response.to_h
       validate_tool_call_result!(tool, result)
-      serialize_structured_content_fallback(result)
+      serialize_structured_content_fallback(
+        result,
+        content_provided: response.respond_to?(:content_provided?) && response.content_provided?,
+      )
     rescue RequestHandlerError, CancelledError
       # CancelledError is intentionally not wrapped so `handle_request` can turn it into
       # `JsonRpcHandler::NO_RESPONSE` per the MCP cancellation spec.
@@ -986,14 +1025,18 @@ module MCP
 
     # Per SEP-2106, `structuredContent` may be any JSON value, not only an object.
     # Clients on older protocol versions may only read `content`,
-    # so when a tool returns non-object structured content without providing
-    # any content blocks, mirror the value into `content` as serialized JSON text.
-    def serialize_structured_content_fallback(result)
+    # so when a tool returns non-object structured content without explicitly
+    # providing `content`, mirror the value into serialized JSON text.
+    def serialize_structured_content_fallback(result, content_provided: false)
       structured = result[:structuredContent]
       return result if structured.nil? || structured.is_a?(Hash)
+      return result if content_provided
       return result unless result[:content].nil? || result[:content].empty?
 
-      result.merge(content: [{ type: "text", text: JSON.generate(structured) }])
+      serialized = JSON.generate(structured)
+      return result if JSON.parse(serialized).is_a?(Hash)
+
+      result.merge(content: [{ type: "text", text: serialized }])
     end
 
     # Whether a tool/prompt handler opts in to receiving an `MCP::ServerContext`.
@@ -1026,9 +1069,9 @@ module MCP
           related_request_id: related_request_id,
           cancellation: cancellation,
         )
-        tool.call(**args, server_context: server_context).to_h
+        tool.call(**args, server_context: server_context)
       else
-        tool.call(**args).to_h
+        tool.call(**args)
       end
     end
 

data/lib/mcp/tool/response.rb

@@ -7,18 +7,24 @@ module MCP
 
       attr_reader :content, :structured_content, :meta
 
-      def initialize(content = nil, deprecated_error = NOT_GIVEN, error: false, structured_content: nil, meta: nil)
+      def initialize(content = NOT_GIVEN, deprecated_error = NOT_GIVEN, error: false, structured_content: nil, meta: nil)
         if deprecated_error != NOT_GIVEN
           warn("Passing `error` with the 2nd argument of `Response.new` is deprecated. Use keyword argument like `Response.new(content, error: error)` instead.", uplevel: 1)
           error = deprecated_error
         end
 
-        @content = content || []
+        content_given = !content.equal?(NOT_GIVEN)
+        @content_provided = content_given && !content.nil?
+        @content = content_given ? (content || []) : []
         @error = error
         @structured_content = structured_content
         @meta = meta
       end
 
+      def content_provided?
+        @content_provided
+      end
+
       def error?
         !!@error
       end

data/lib/mcp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MCP
-  VERSION = "0.25.0"
+  VERSION = "1.1.0"
 end

data/lib/mcp.rb

@@ -16,6 +16,7 @@ module MCP
   autoload :ErrorCodes, "mcp/error_codes"
   autoload :Icon, "mcp/icon"
   autoload :Prompt, "mcp/prompt"
+  autoload :RequestEnvelope, "mcp/request_envelope"
   autoload :Resource, "mcp/resource"
   autoload :ResourceTemplate, "mcp/resource_template"
   autoload :ResultType, "mcp/result_type"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mcp
 version: !ruby/object:Gem::Version
-  version: 0.25.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Model Context Protocol
@@ -69,6 +69,7 @@ files:
 - lib/mcp/prompt/argument.rb
 - lib/mcp/prompt/message.rb
 - lib/mcp/prompt/result.rb
+- lib/mcp/request_envelope.rb
 - lib/mcp/resource.rb
 - lib/mcp/resource/contents.rb
 - lib/mcp/resource/embedded.rb
@@ -97,7 +98,7 @@ licenses:
 - Apache-2.0
 metadata:
   allowed_push_host: https://rubygems.org
-  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v0.25.0
+  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v1.1.0
   homepage_uri: https://ruby.sdk.modelcontextprotocol.io
   source_code_uri: https://github.com/modelcontextprotocol/ruby-sdk
   bug_tracker_uri: https://github.com/modelcontextprotocol/ruby-sdk/issues