mcp 0.12.0 → 0.14.0

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
@@ -72,15 +73,13 @@ module MCP
           require_capability!(method, capabilities, :completions)
         when ROOTS_LIST
           require_capability!(method, capabilities, :roots)
-        when NOTIFICATIONS_ROOTS_LIST_CHANGED
-          require_capability!(method, capabilities, :roots)
-          require_capability!(method, capabilities, :roots, :listChanged)
         when SAMPLING_CREATE_MESSAGE
           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_ROOTS_LIST_CHANGED,
+             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/pagination.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module MCP
+  class Server
+    module Pagination
+      private
+
+      def cursor_from(request)
+        return if request.nil?
+
+        unless request.is_a?(Hash)
+          raise RequestHandlerError.new("Invalid params", request, error_type: :invalid_params)
+        end
+
+        request[:cursor]
+      end
+
+      def paginate(items, cursor:, page_size:, request:, &block)
+        start_index = 0
+
+        if cursor
+          unless cursor.is_a?(String)
+            raise RequestHandlerError.new("Invalid cursor", request, error_type: :invalid_params)
+          end
+
+          start_index = Integer(cursor, exception: false)
+          if start_index.nil? || start_index < 0 || start_index >= items.size
+            raise RequestHandlerError.new("Invalid cursor", request, error_type: :invalid_params)
+          end
+        end
+
+        end_index = page_size ? start_index + page_size : items.size
+        page = items[start_index...end_index]
+        page = page.map(&block) if block
+
+        result = { items: page }
+        result[:next_cursor] = end_index.to_s if end_index < items.size
+        result
+      end
+    end
+  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
@@ -13,13 +22,14 @@ module MCP
           "Connection" => "keep-alive",
         }.freeze
 
-        def initialize(server, stateless: false, session_idle_timeout: nil)
+        def initialize(server, stateless: false, enable_json_response: false, session_idle_timeout: nil)
           super(server)
           # Maps `session_id` to `{ get_sse_stream: stream_object, server_session: ServerSession, last_active_at: float_from_monotonic_clock }`.
           @sessions = {}
           @mutex = Mutex.new
 
           @stateless = stateless
+          @enable_json_response = enable_json_response
           @session_idle_timeout = session_idle_timeout
           @pending_responses = {}
 
@@ -34,11 +44,17 @@ module MCP
           start_reaper_thread if @session_idle_timeout
         end
 
-        REQUIRED_POST_ACCEPT_TYPES = ["application/json", "text/event-stream"].freeze
+        REQUIRED_POST_ACCEPT_TYPES_SSE = ["application/json", "text/event-stream"].freeze
+        REQUIRED_POST_ACCEPT_TYPES_JSON = ["application/json"].freeze
         REQUIRED_GET_ACCEPT_TYPES = ["text/event-stream"].freeze
         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"
@@ -80,6 +96,12 @@ module MCP
 
           result = @mutex.synchronize do
             if session_id
+              # JSON response mode returns a single JSON object as the POST response,
+              # so request-scoped notifications (e.g. progress, log) cannot be delivered
+              # alongside it. Session-scoped standalone notifications
+              # (e.g. `resources/updated`, `elicitation/complete`) still flow via GET SSE.
+              next false if @enable_json_response && related_request_id
+
               # Send to specific session
               if (session = @sessions[session_id])
                 stream = active_stream(session, related_request_id: related_request_id)
@@ -158,6 +180,10 @@ module MCP
             raise "Stateless mode does not support server-to-client requests."
           end
 
+          if @enable_json_response
+            raise "JSON response mode does not support server-to-client requests."
+          end
+
           unless session_id
             raise "session_id is required for server-to-client requests."
           end
@@ -255,16 +281,17 @@ module MCP
         def send_to_stream(stream, data)
           message = data.is_a?(String) ? data : data.to_json
           stream.write("data: #{message}\n\n")
-          stream.flush if stream.respond_to?(:flush)
+          stream.flush
         end
 
         def send_ping_to_stream(stream)
           stream.write(": ping #{Time.now.iso8601}\n\n")
-          stream.flush if stream.respond_to?(:flush)
+          stream.flush
         end
 
         def handle_post(request)
-          accept_error = validate_accept_header(request, REQUIRED_POST_ACCEPT_TYPES)
+          required_types = @enable_json_response ? REQUIRED_POST_ACCEPT_TYPES_JSON : REQUIRED_POST_ACCEPT_TYPES_SSE
+          accept_error = validate_accept_header(request, required_types)
           return accept_error if accept_error
 
           content_type_error = validate_content_type(request)
@@ -505,7 +532,7 @@ module MCP
             end
           end
 
-          if session_id && !@stateless
+          if session_id && !@stateless && !@enable_json_response
             handle_request_with_sse_response(body_string, session_id, server_session, related_request_id: related_request_id)
           else
             response = dispatch_handle_json(body_string, server_session)
@@ -546,7 +573,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.
@@ -628,7 +655,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)

data/lib/mcp/server.rb

@@ -6,6 +6,7 @@ require_relative "methods"
 require_relative "logging_message_notification"
 require_relative "progress"
 require_relative "server_context"
+require_relative "server/pagination"
 require_relative "server/transports"
 
 module MCP
@@ -31,14 +32,27 @@ module MCP
     MAX_COMPLETION_VALUES = 100
 
     class RequestHandlerError < StandardError
-      attr_reader :error_type
-      attr_reader :original_error
+      attr_reader :error_type, :original_error, :error_code, :error_data
 
-      def initialize(message, request, error_type: :internal_error, original_error: nil)
+      def initialize(message, request, error_type: :internal_error, original_error: nil, error_code: nil, error_data: nil)
         super(message)
         @request = request
         @error_type = error_type
         @original_error = original_error
+        @error_code = error_code
+        @error_data = error_data
+      end
+    end
+
+    class URLElicitationRequiredError < RequestHandlerError
+      def initialize(elicitations)
+        super(
+          "URL elicitation required",
+          nil,
+          error_type: :url_elicitation_required,
+          error_code: -32042,
+          error_data: { elicitations: elicitations },
+        )
       end
     end
 
@@ -52,9 +66,10 @@ module MCP
     end
 
     include Instrumentation
+    include Pagination
 
     attr_accessor :description, :icons, :name, :title, :version, :website_url, :instructions, :tools, :prompts, :resources, :server_context, :configuration, :capabilities, :transport, :logging_message_notification
-    attr_reader :client_capabilities
+    attr_reader :page_size, :client_capabilities
 
     def initialize(
       description: nil,
@@ -71,6 +86,7 @@ module MCP
       server_context: nil,
       configuration: nil,
       capabilities: nil,
+      page_size: nil,
       transport: nil
     )
       @description = description
@@ -87,6 +103,7 @@ module MCP
       @resource_templates = resource_templates
       @resource_index = index_resources_by_uri(resources)
       @server_context = server_context
+      self.page_size = page_size
       @configuration = MCP.configuration.merge(configuration)
       @client = nil
 
@@ -100,6 +117,8 @@ module MCP
         Methods::RESOURCES_LIST => method(:list_resources),
         Methods::RESOURCES_READ => method(:read_resource_no_content),
         Methods::RESOURCES_TEMPLATES_LIST => method(:list_resource_templates),
+        Methods::RESOURCES_SUBSCRIBE => ->(_) { {} },
+        Methods::RESOURCES_UNSUBSCRIBE => ->(_) { {} },
         Methods::TOOLS_LIST => method(:list_tools),
         Methods::TOOLS_CALL => method(:call_tool),
         Methods::PROMPTS_LIST => method(:list_prompts),
@@ -108,13 +127,9 @@ module MCP
         Methods::PING => ->(_) { {} },
         Methods::NOTIFICATIONS_INITIALIZED => ->(_) {},
         Methods::NOTIFICATIONS_PROGRESS => ->(_) {},
+        Methods::NOTIFICATIONS_ROOTS_LIST_CHANGED => ->(_) {},
         Methods::COMPLETION_COMPLETE => ->(_) { DEFAULT_COMPLETION_RESULT },
         Methods::LOGGING_SET_LEVEL => method(:configure_logging_level),
-
-        # No op handlers for currently unsupported methods
-        Methods::RESOURCES_SUBSCRIBE => ->(_) { {} },
-        Methods::RESOURCES_UNSUBSCRIBE => ->(_) { {} },
-        Methods::ELICITATION_CREATE => ->(_) {},
       }
       @transport = transport
     end
@@ -170,6 +185,14 @@ module MCP
       @handlers[method_name] = block
     end
 
+    def page_size=(page_size)
+      unless page_size.nil? || (page_size.is_a?(Integer) && page_size > 0)
+        raise ArgumentError, "page_size must be nil or a positive integer"
+      end
+
+      @page_size = page_size
+    end
+
     def notify_tools_list_changed
       return unless @transport
 
@@ -206,42 +229,12 @@ module MCP
       report_exception(e, { notification: "log_message" })
     end
 
-    # Sends a `sampling/createMessage` request to the client.
-    # For single-client transports (e.g., `StdioTransport`). For multi-client transports
-    # (e.g., `StreamableHTTPTransport`), use `ServerSession#create_sampling_message` instead
-    # to ensure the request is routed to the correct client.
-    def create_sampling_message(
-      messages:,
-      max_tokens:,
-      system_prompt: nil,
-      model_preferences: nil,
-      include_context: nil,
-      temperature: nil,
-      stop_sequences: nil,
-      metadata: nil,
-      tools: nil,
-      tool_choice: nil,
-      related_request_id: nil
-    )
-      unless @transport
-        raise "Cannot send sampling request without a transport."
-      end
-
-      params = build_sampling_params(
-        @client_capabilities,
-        messages: messages,
-        max_tokens: max_tokens,
-        system_prompt: system_prompt,
-        model_preferences: model_preferences,
-        include_context: include_context,
-        temperature: temperature,
-        stop_sequences: stop_sequences,
-        metadata: metadata,
-        tools: tools,
-        tool_choice: tool_choice,
-      )
-
-      @transport.send_request(Methods::SAMPLING_CREATE_MESSAGE, params)
+    # Sets a handler for `notifications/roots/list_changed` notifications.
+    # Called when a client notifies the server that its filesystem roots have changed.
+    #
+    # @yield [params] The notification params (typically `nil`).
+    def roots_list_changed_handler(&block)
+      @handlers[Methods::NOTIFICATIONS_ROOTS_LIST_CHANGED] = block
     end
 
     # Sets a custom handler for `resources/read` requests.
@@ -263,6 +256,24 @@ module MCP
       @handlers[Methods::COMPLETION_COMPLETE] = block
     end
 
+    # Sets a custom handler for `resources/subscribe` requests.
+    # The block receives the parsed request params. The return value is
+    # ignored; the response is always an empty result `{}` per the MCP specification.
+    #
+    # @yield [params] The request params containing `:uri`.
+    def resources_subscribe_handler(&block)
+      @handlers[Methods::RESOURCES_SUBSCRIBE] = block
+    end
+
+    # Sets a custom handler for `resources/unsubscribe` requests.
+    # The block receives the parsed request params. The return value is
+    # ignored; the response is always an empty result `{}` per the MCP specification.
+    #
+    # @yield [params] The request params containing `:uri`.
+    def resources_unsubscribe_handler(&block)
+      @handlers[Methods::RESOURCES_UNSUBSCRIBE] = block
+    end
+
     def build_sampling_params(
       capabilities,
       messages:,
@@ -375,7 +386,7 @@ module MCP
     def handle_request(request, method, session: nil, related_request_id: nil)
       handler = @handlers[method]
       unless handler
-        instrument_call("unsupported_method") do
+        instrument_call("unsupported_method", server_context: { request: request }) do
           client = session&.client || @client
           add_instrumentation_data(client: client) if client
         end
@@ -385,20 +396,20 @@ module MCP
       Methods.ensure_capability!(method, capabilities)
 
       ->(params) {
-        instrument_call(method) do
+        reported_exception = nil
+        instrument_call(
+          method,
+          server_context: { request: request },
+          exception_already_reported: ->(e) { reported_exception.equal?(e) },
+        ) do
           result = case method
           when Methods::INITIALIZE
             init(params, session: session)
-          when Methods::TOOLS_LIST
-            { tools: @handlers[Methods::TOOLS_LIST].call(params) }
-          when Methods::PROMPTS_LIST
-            { prompts: @handlers[Methods::PROMPTS_LIST].call(params) }
-          when Methods::RESOURCES_LIST
-            { resources: @handlers[Methods::RESOURCES_LIST].call(params) }
           when Methods::RESOURCES_READ
             { contents: @handlers[Methods::RESOURCES_READ].call(params) }
-          when Methods::RESOURCES_TEMPLATES_LIST
-            { resourceTemplates: @handlers[Methods::RESOURCES_TEMPLATES_LIST].call(params) }
+          when Methods::RESOURCES_SUBSCRIBE, Methods::RESOURCES_UNSUBSCRIBE
+            @handlers[method].call(params)
+            {}
           when Methods::TOOLS_CALL
             call_tool(params, session: session, related_request_id: related_request_id)
           when Methods::COMPLETION_COMPLETE
@@ -415,11 +426,14 @@ module MCP
         rescue RequestHandlerError => e
           report_exception(e.original_error || e, { request: request })
           add_instrumentation_data(error: e.error_type)
+          reported_exception = e
           raise e
         rescue => e
           report_exception(e, { request: request })
           add_instrumentation_data(error: :internal_error)
-          raise RequestHandlerError.new("Internal error handling #{method} request", request, original_error: e)
+          wrapped = RequestHandlerError.new("Internal error handling #{method} request", request, original_error: e)
+          reported_exception = wrapped
+          raise wrapped
         end
       }
     end
@@ -497,7 +511,9 @@ module MCP
     end
 
     def list_tools(request)
-      @tools.values.map(&:to_h)
+      page = paginate(@tools.values, cursor: cursor_from(request), page_size: @page_size, request: request, &:to_h)
+
+      { tools: page[:items], nextCursor: page[:next_cursor] }.compact
     end
 
     def call_tool(request, session: nil, related_request_id: nil)
@@ -545,7 +561,9 @@ module MCP
     end
 
     def list_prompts(request)
-      @prompts.values.map(&:to_h)
+      page = paginate(@prompts.values, cursor: cursor_from(request), page_size: @page_size, request: request, &:to_h)
+
+      { prompts: page[:items], nextCursor: page[:next_cursor] }.compact
     end
 
     def get_prompt(request)
@@ -565,7 +583,9 @@ module MCP
     end
 
     def list_resources(request)
-      @resources.map(&:to_h)
+      page = paginate(@resources, cursor: cursor_from(request), page_size: @page_size, request: request, &:to_h)
+
+      { resources: page[:items], nextCursor: page[:next_cursor] }.compact
     end
 
     # Server implementation should set `resources_read_handler` to override no-op default
@@ -575,7 +595,9 @@ module MCP
     end
 
     def list_resource_templates(request)
-      @resource_templates.map(&:to_h)
+      page = paginate(@resource_templates, cursor: cursor_from(request), page_size: @page_size, request: request, &:to_h)
+
+      { resourceTemplates: page[:items], nextCursor: page[:next_cursor] }.compact
     end
 
     def complete(params)