mcp 0.11.0 → 0.13.0

data/lib/json_rpc_handler.rb

@@ -117,20 +117,27 @@ module JsonRpcHandler
   end
 
   def handle_request_error(error, id, id_validation_pattern)
-    error_type = error.respond_to?(:error_type) ? error.error_type : nil
-
-    code, message = case error_type
-    when :invalid_request then [ErrorCode::INVALID_REQUEST, "Invalid Request"]
-    when :invalid_params then [ErrorCode::INVALID_PARAMS, "Invalid params"]
-    when :parse_error then [ErrorCode::PARSE_ERROR, "Parse error"]
-    when :internal_error then [ErrorCode::INTERNAL_ERROR, "Internal error"]
-    else [ErrorCode::INTERNAL_ERROR, "Internal error"]
+    if error.respond_to?(:error_code) && error.error_code
+      code = error.error_code
+      message = error.message
+    else
+      error_type = error.respond_to?(:error_type) ? error.error_type : nil
+
+      code, message = case error_type
+      when :invalid_request then [ErrorCode::INVALID_REQUEST, "Invalid Request"]
+      when :invalid_params then [ErrorCode::INVALID_PARAMS, "Invalid params"]
+      when :parse_error then [ErrorCode::PARSE_ERROR, "Parse error"]
+      when :internal_error then [ErrorCode::INTERNAL_ERROR, "Internal error"]
+      else [ErrorCode::INTERNAL_ERROR, "Internal error"]
+      end
     end
 
+    data = error.respond_to?(:error_data) && error.error_data ? error.error_data : error.message
+
     error_response(id: id, id_validation_pattern: id_validation_pattern, error: {
       code: code,
       message: message,
-      data: error.message,
+      data: data,
     })
   end
 

data/lib/mcp/client/http.rb

@@ -7,9 +7,10 @@ module MCP
 
       attr_reader :url
 
-      def initialize(url:, headers: {})
+      def initialize(url:, headers: {}, &block)
         @url = url
         @headers = headers
+        @faraday_customizer = block
       end
 
       def send_request(request:)
@@ -78,6 +79,8 @@ module MCP
           headers.each do |key, value|
             faraday.headers[key] = value
           end
+
+          @faraday_customizer&.call(faraday)
         end
       end
 

data/lib/mcp/configuration.rb

@@ -7,11 +7,18 @@ module MCP
       LATEST_STABLE_PROTOCOL_VERSION, "2025-06-18", "2025-03-26", "2024-11-05",
     ]
 
-    attr_writer :exception_reporter, :instrumentation_callback
+    attr_writer :exception_reporter, :around_request
 
-    def initialize(exception_reporter: nil, instrumentation_callback: nil, protocol_version: nil,
+    # @deprecated Use {#around_request=} instead. `instrumentation_callback`
+    #   fires only after a request completes and cannot wrap execution in a
+    #   surrounding block (e.g. for Application Performance Monitoring (APM) spans).
+    # @see #around_request=
+    attr_writer :instrumentation_callback
+
+    def initialize(exception_reporter: nil, around_request: nil, instrumentation_callback: nil, protocol_version: nil,
       validate_tool_call_arguments: true)
       @exception_reporter = exception_reporter
+      @around_request = around_request
       @instrumentation_callback = instrumentation_callback
       @protocol_version = protocol_version
       if protocol_version
@@ -50,10 +57,24 @@ module MCP
       !@exception_reporter.nil?
     end
 
+    def around_request
+      @around_request || default_around_request
+    end
+
+    def around_request?
+      !@around_request.nil?
+    end
+
+    # @deprecated Use {#around_request} instead. `instrumentation_callback`
+    #   fires only after a request completes and cannot wrap execution in a
+    #   surrounding block (e.g. for Application Performance Monitoring (APM) spans).
+    # @see #around_request
     def instrumentation_callback
       @instrumentation_callback || default_instrumentation_callback
     end
 
+    # @deprecated Use {#around_request?} instead.
+    # @see #around_request?
     def instrumentation_callback?
       !@instrumentation_callback.nil?
     end
@@ -72,20 +93,30 @@ module MCP
       else
         @exception_reporter
       end
+
+      around_request = if other.around_request?
+        other.around_request
+      else
+        @around_request
+      end
+
       instrumentation_callback = if other.instrumentation_callback?
         other.instrumentation_callback
       else
         @instrumentation_callback
       end
+
       protocol_version = if other.protocol_version?
         other.protocol_version
       else
         @protocol_version
       end
+
       validate_tool_call_arguments = other.validate_tool_call_arguments
 
       Configuration.new(
         exception_reporter: exception_reporter,
+        around_request: around_request,
         instrumentation_callback: instrumentation_callback,
         protocol_version: protocol_version,
         validate_tool_call_arguments: validate_tool_call_arguments,
@@ -111,6 +142,11 @@ module MCP
       @default_exception_reporter ||= ->(exception, server_context) {}
     end
 
+    def default_around_request
+      @default_around_request ||= ->(_data, &request_handler) { request_handler.call }
+    end
+
+    # @deprecated Use {#default_around_request} instead.
     def default_instrumentation_callback
       @default_instrumentation_callback ||= ->(data) {}
     end

data/lib/mcp/content.rb

@@ -3,56 +3,60 @@
 module MCP
   module Content
     class Text
-      attr_reader :text, :annotations
+      attr_reader :text, :annotations, :meta
 
-      def initialize(text, annotations: nil)
+      def initialize(text, annotations: nil, meta: nil)
         @text = text
         @annotations = annotations
+        @meta = meta
       end
 
       def to_h
-        { text: text, annotations: annotations, type: "text" }.compact
+        { text: text, annotations: annotations, _meta: meta, type: "text" }.compact
       end
     end
 
     class Image
-      attr_reader :data, :mime_type, :annotations
+      attr_reader :data, :mime_type, :annotations, :meta
 
-      def initialize(data, mime_type, annotations: nil)
+      def initialize(data, mime_type, annotations: nil, meta: nil)
         @data = data
         @mime_type = mime_type
         @annotations = annotations
+        @meta = meta
       end
 
       def to_h
-        { data: data, mimeType: mime_type, annotations: annotations, type: "image" }.compact
+        { data: data, mimeType: mime_type, annotations: annotations, _meta: meta, type: "image" }.compact
       end
     end
 
     class Audio
-      attr_reader :data, :mime_type, :annotations
+      attr_reader :data, :mime_type, :annotations, :meta
 
-      def initialize(data, mime_type, annotations: nil)
+      def initialize(data, mime_type, annotations: nil, meta: nil)
         @data = data
         @mime_type = mime_type
         @annotations = annotations
+        @meta = meta
       end
 
       def to_h
-        { data: data, mimeType: mime_type, annotations: annotations, type: "audio" }.compact
+        { data: data, mimeType: mime_type, annotations: annotations, _meta: meta, type: "audio" }.compact
       end
     end
 
     class EmbeddedResource
-      attr_reader :resource, :annotations
+      attr_reader :resource, :annotations, :meta
 
-      def initialize(resource, annotations: nil)
+      def initialize(resource, annotations: nil, meta: nil)
         @resource = resource
         @annotations = annotations
+        @meta = meta
       end
 
       def to_h
-        { resource: resource.to_h, annotations: annotations, type: "resource" }.compact
+        { resource: resource.to_h, annotations: annotations, _meta: meta, type: "resource" }.compact
       end
     end
   end

data/lib/mcp/instrumentation.rb

@@ -2,19 +2,40 @@
 
 module MCP
   module Instrumentation
-    def instrument_call(method, &block)
+    def instrument_call(method, server_context: {}, exception_already_reported: nil, &block)
       start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       begin
         @instrumentation_data = {}
         add_instrumentation_data(method: method)
 
-        result = yield block
+        result = configuration.around_request.call(@instrumentation_data, &block)
 
         result
+      rescue => e
+        already_reported = begin
+          !!exception_already_reported&.call(e)
+        # rubocop:disable Lint/RescueException
+        rescue Exception
+          # rubocop:enable Lint/RescueException
+          # The predicate is expected to be side-effect-free and return a boolean.
+          # Any exception raised from it (including non-StandardError such as SystemExit)
+          # must not shadow the original exception.
+          false
+        end
+
+        unless already_reported
+          add_instrumentation_data(error: :internal_error) unless @instrumentation_data.key?(:error)
+          configuration.exception_reporter.call(e, server_context)
+        end
+
+        raise
       ensure
         end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         add_instrumentation_data(duration: end_time - start_time)
 
+        # Backward compatibility: `instrumentation_callback` is soft-deprecated
+        # in favor of `around_request`, but existing callers still expect it
+        # to fire after every request until it is removed in a future version.
         configuration.instrumentation_callback.call(@instrumentation_data)
       end
     end

data/lib/mcp/methods.rb

@@ -33,6 +33,7 @@ module MCP
     NOTIFICATIONS_MESSAGE = "notifications/message"
     NOTIFICATIONS_PROGRESS = "notifications/progress"
     NOTIFICATIONS_CANCELLED = "notifications/cancelled"
+    NOTIFICATIONS_ELICITATION_COMPLETE = "notifications/elicitation/complete"
 
     class MissingRequiredCapabilityError < StandardError
       attr_reader :method
@@ -79,8 +80,8 @@ module MCP
           require_capability!(method, capabilities, :sampling)
         when ELICITATION_CREATE
           require_capability!(method, capabilities, :elicitation)
-        when INITIALIZE, PING, NOTIFICATIONS_INITIALIZED, NOTIFICATIONS_PROGRESS, NOTIFICATIONS_CANCELLED
-          # No specific capability required for initialize, ping, progress or cancelled
+        when INITIALIZE, PING, NOTIFICATIONS_INITIALIZED, NOTIFICATIONS_PROGRESS, NOTIFICATIONS_CANCELLED, NOTIFICATIONS_ELICITATION_COMPLETE
+          # No specific capability required.
         end
       end
 

data/lib/mcp/prompt/result.rb

@@ -3,15 +3,16 @@
 module MCP
   class Prompt
     class Result
-      attr_reader :description, :messages
+      attr_reader :description, :messages, :meta
 
-      def initialize(description: nil, messages: [])
+      def initialize(description: nil, messages: [], meta: nil)
         @description = description
         @messages = messages
+        @meta = meta
       end
 
       def to_h
-        { description: description, messages: messages.map(&:to_h) }.compact
+        { description: description, messages: messages.map(&:to_h), _meta: meta }.compact
       end
     end
   end

data/lib/mcp/resource/contents.rb

@@ -3,23 +3,24 @@
 module MCP
   class Resource
     class Contents
-      attr_reader :uri, :mime_type
+      attr_reader :uri, :mime_type, :meta
 
-      def initialize(uri:, mime_type: nil)
+      def initialize(uri:, mime_type: nil, meta: nil)
         @uri = uri
         @mime_type = mime_type
+        @meta = meta
       end
 
       def to_h
-        { uri: uri, mimeType: mime_type }.compact
+        { uri: uri, mimeType: mime_type, _meta: meta }.compact
       end
     end
 
     class TextContents < Contents
       attr_reader :text
 
-      def initialize(text:, uri:, mime_type:)
-        super(uri: uri, mime_type: mime_type)
+      def initialize(text:, uri:, mime_type:, meta: nil)
+        super(uri: uri, mime_type: mime_type, meta: meta)
         @text = text
       end
 
@@ -31,8 +32,8 @@ module MCP
     class BlobContents < Contents
       attr_reader :data
 
-      def initialize(data:, uri:, mime_type:)
-        super(uri: uri, mime_type: mime_type)
+      def initialize(data:, uri:, mime_type:, meta: nil)
+        super(uri: uri, mime_type: mime_type, meta: meta)
         @data = data
       end
 

data/lib/mcp/resource.rb

@@ -5,15 +5,16 @@ require_relative "resource/embedded"
 
 module MCP
   class Resource
-    attr_reader :uri, :name, :title, :description, :icons, :mime_type
+    attr_reader :uri, :name, :title, :description, :icons, :mime_type, :meta
 
-    def initialize(uri:, name:, title: nil, description: nil, icons: [], mime_type: nil)
+    def initialize(uri:, name:, title: nil, description: nil, icons: [], mime_type: nil, meta: nil)
       @uri = uri
       @name = name
       @title = title
       @description = description
       @icons = icons
       @mime_type = mime_type
+      @meta = meta
     end
 
     def to_h
@@ -24,6 +25,7 @@ module MCP
         description: description,
         icons: icons&.then { |icons| icons.empty? ? nil : icons.map(&:to_h) },
         mimeType: mime_type,
+        _meta: meta,
       }.compact
     end
   end

data/lib/mcp/resource_template.rb

@@ -2,15 +2,16 @@
 
 module MCP
   class ResourceTemplate
-    attr_reader :uri_template, :name, :title, :description, :icons, :mime_type
+    attr_reader :uri_template, :name, :title, :description, :icons, :mime_type, :meta
 
-    def initialize(uri_template:, name:, title: nil, description: nil, icons: [], mime_type: nil)
+    def initialize(uri_template:, name:, title: nil, description: nil, icons: [], mime_type: nil, meta: nil)
       @uri_template = uri_template
       @name = name
       @title = title
       @description = description
       @icons = icons
       @mime_type = mime_type
+      @meta = meta
     end
 
     def to_h
@@ -21,6 +22,7 @@ module MCP
         description: description,
         icons: icons&.then { |icons| icons.empty? ? nil : icons.map(&:to_h) },
         mimeType: mime_type,
+        _meta: meta,
       }.compact
     end
   end

data/lib/mcp/server/transports/streamable_http_transport.rb

@@ -3,6 +3,15 @@
 require "json"
 require_relative "../../transport"
 
+# This file is autoloaded only when `StreamableHTTPTransport` is referenced,
+# so the `rack` dependency does not affect `StdioTransport` users.
+begin
+  require "rack"
+rescue LoadError
+  raise LoadError, "The 'rack' gem is required to use the StreamableHTTPTransport. " \
+    "Add it to your Gemfile: gem 'rack'"
+end
+
 module MCP
   class Server
     module Transports
@@ -15,7 +24,7 @@ module MCP
 
         def initialize(server, stateless: false, session_idle_timeout: nil)
           super(server)
-          # Maps `session_id` to `{ stream: stream_object, server_session: ServerSession, last_active_at: float_from_monotonic_clock }`.
+          # Maps `session_id` to `{ get_sse_stream: stream_object, server_session: ServerSession, last_active_at: float_from_monotonic_clock }`.
           @sessions = {}
           @mutex = Mutex.new
 
@@ -39,6 +48,11 @@ module MCP
         STREAM_WRITE_ERRORS = [IOError, Errno::EPIPE, Errno::ECONNRESET].freeze
         SESSION_REAP_INTERVAL = 60
 
+        # Rack app interface. This transport can be mounted as a Rack app.
+        def call(env)
+          handle_request(Rack::Request.new(env))
+        end
+
         def handle_request(request)
           case request.env["REQUEST_METHOD"]
           when "POST"
@@ -61,7 +75,7 @@ module MCP
           end
 
           removed_sessions.each do |session|
-            close_stream_safely(session[:stream])
+            close_stream_safely(session[:get_sse_stream])
             close_post_request_streams(session)
           end
         end
@@ -113,7 +127,7 @@ module MCP
               failed_sessions = []
 
               @sessions.each do |sid, session|
-                next unless (stream = session[:stream])
+                next unless (stream = session[:get_sse_stream])
 
                 if session_expired?(session)
                   failed_sessions << sid
@@ -247,7 +261,7 @@ module MCP
           end
 
           removed_sessions.each do |session|
-            close_stream_safely(session[:stream])
+            close_stream_safely(session[:get_sse_stream])
             close_post_request_streams(session)
           end
         end
@@ -267,6 +281,9 @@ module MCP
           accept_error = validate_accept_header(request, REQUIRED_POST_ACCEPT_TYPES)
           return accept_error if accept_error
 
+          content_type_error = validate_content_type(request)
+          return content_type_error if content_type_error
+
           body_string = request.body.read
           session_id = extract_session_id(request)
 
@@ -334,7 +351,7 @@ module MCP
           end
 
           if session
-            close_stream_safely(session[:stream])
+            close_stream_safely(session[:get_sse_stream])
             close_post_request_streams(session)
           end
         end
@@ -358,7 +375,7 @@ module MCP
         def cleanup_and_collect_stream(session_id, streams_to_close)
           return unless (removed = cleanup_session_unsafe(session_id))
 
-          streams_to_close << removed[:stream]
+          streams_to_close << removed[:get_sse_stream]
           removed[:post_request_streams]&.each_value { |stream| streams_to_close << stream }
         end
 
@@ -399,6 +416,18 @@ module MCP
           end
         end
 
+        def validate_content_type(request)
+          content_type = request.env["CONTENT_TYPE"]
+          media_type = content_type&.split(";")&.first&.strip&.downcase
+          return if media_type == "application/json"
+
+          [
+            415,
+            { "Content-Type" => "application/json" },
+            [{ error: "Unsupported Media Type: Content-Type must be application/json" }.to_json],
+          ]
+        end
+
         def not_acceptable_response(required_types)
           [
             406,
@@ -449,7 +478,7 @@ module MCP
 
             @mutex.synchronize do
               @sessions[session_id] = {
-                stream: nil,
+                get_sse_stream: nil,
                 server_session: server_session,
                 last_active_at: Process.clock_gettime(Process::CLOCK_MONOTONIC),
               }
@@ -531,7 +560,7 @@ module MCP
             end
           end
 
-          [200, SSE_HEADERS, body]
+          [200, SSE_HEADERS.dup, body]
         end
 
         # Returns the SSE stream available for server-to-client messages.
@@ -543,7 +572,7 @@ module MCP
           if related_request_id
             session.dig(:post_request_streams, related_request_id)
           else
-            session[:stream]
+            session[:get_sse_stream]
           end
         end
 
@@ -572,7 +601,7 @@ module MCP
           end
 
           if removed
-            close_stream_safely(removed[:stream])
+            close_stream_safely(removed[:get_sse_stream])
 
             removed[:post_request_streams]&.each_value do |stream|
               close_stream_safely(stream)
@@ -583,7 +612,7 @@ module MCP
         end
 
         def get_session_stream(session_id)
-          @mutex.synchronize { @sessions[session_id]&.fetch(:stream, nil) }
+          @mutex.synchronize { @sessions[session_id]&.fetch(:get_sse_stream, nil) }
         end
 
         def session_exists?(session_id)
@@ -613,7 +642,7 @@ module MCP
         def setup_sse_stream(session_id)
           body = create_sse_body(session_id)
 
-          [200, SSE_HEADERS, body]
+          [200, SSE_HEADERS.dup, body]
         end
 
         def create_sse_body(session_id)
@@ -626,8 +655,8 @@ module MCP
         def store_stream_for_session(session_id, stream)
           @mutex.synchronize do
             session = @sessions[session_id]
-            if session && !session[:stream]
-              session[:stream] = stream
+            if session && !session[:get_sse_stream]
+              session[:get_sse_stream] = stream
             else
               # Either session was removed, or another request already established a stream.
               stream.close
@@ -652,13 +681,13 @@ module MCP
         end
 
         def session_active_with_stream?(session_id)
-          @mutex.synchronize { @sessions.key?(session_id) && @sessions[session_id][:stream] }
+          @mutex.synchronize { @sessions.key?(session_id) && @sessions[session_id][:get_sse_stream] }
         end
 
         def send_keepalive_ping(session_id)
           @mutex.synchronize do
-            if @sessions[session_id] && @sessions[session_id][:stream]
-              send_ping_to_stream(@sessions[session_id][:stream])
+            if @sessions[session_id] && @sessions[session_id][:get_sse_stream]
+              send_ping_to_stream(@sessions[session_id][:get_sse_stream])
             end
           end
         rescue *STREAM_WRITE_ERRORS => e