mcp 0.4.0 → 0.5.0

data/lib/json_rpc_handler.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "json"
+
+module JsonRpcHandler
+  class Version
+    V1_0 = "1.0"
+    V2_0 = "2.0"
+  end
+
+  class ErrorCode
+    INVALID_REQUEST = -32600
+    METHOD_NOT_FOUND = -32601
+    INVALID_PARAMS = -32602
+    INTERNAL_ERROR = -32603
+    PARSE_ERROR = -32700
+  end
+
+  DEFAULT_ALLOWED_ID_CHARACTERS = /\A[a-zA-Z0-9_-]+\z/
+
+  extend self
+
+  def handle(request, id_validation_pattern: DEFAULT_ALLOWED_ID_CHARACTERS, &method_finder)
+    if request.is_a?(Array)
+      return error_response(id: :unknown_id, id_validation_pattern: id_validation_pattern, error: {
+        code: ErrorCode::INVALID_REQUEST,
+        message: "Invalid Request",
+        data: "Request is an empty array",
+      }) if request.empty?
+
+      # Handle batch requests
+      responses = request.map { |req| process_request(req, id_validation_pattern: id_validation_pattern, &method_finder) }.compact
+
+      # A single item is hoisted out of the array
+      return responses.first if responses.one?
+
+      # An empty array yields nil
+      responses if responses.any?
+    elsif request.is_a?(Hash)
+      # Handle single request
+      process_request(request, id_validation_pattern: id_validation_pattern, &method_finder)
+    else
+      error_response(id: :unknown_id, id_validation_pattern: id_validation_pattern, error: {
+        code: ErrorCode::INVALID_REQUEST,
+        message: "Invalid Request",
+        data: "Request must be an array or a hash",
+      })
+    end
+  end
+
+  def handle_json(request_json, id_validation_pattern: DEFAULT_ALLOWED_ID_CHARACTERS, &method_finder)
+    begin
+      request = JSON.parse(request_json, symbolize_names: true)
+      response = handle(request, id_validation_pattern: id_validation_pattern, &method_finder)
+    rescue JSON::ParserError
+      response = error_response(id: :unknown_id, id_validation_pattern: id_validation_pattern, error: {
+        code: ErrorCode::PARSE_ERROR,
+        message: "Parse error",
+        data: "Invalid JSON",
+      })
+    end
+
+    response&.to_json
+  end
+
+  def process_request(request, id_validation_pattern:, &method_finder)
+    id = request[:id]
+
+    error = if !valid_version?(request[:jsonrpc])
+      "JSON-RPC version must be 2.0"
+    elsif !valid_id?(request[:id], id_validation_pattern)
+      "Request ID must match validation pattern, or be an integer or null"
+    elsif !valid_method_name?(request[:method])
+      'Method name must be a string and not start with "rpc."'
+    end
+
+    return error_response(id: :unknown_id, id_validation_pattern: id_validation_pattern, error: {
+      code: ErrorCode::INVALID_REQUEST,
+      message: "Invalid Request",
+      data: error,
+    }) if error
+
+    method_name = request[:method]
+    params = request[:params]
+
+    unless valid_params?(params)
+      return error_response(id: id, id_validation_pattern: id_validation_pattern, error: {
+        code: ErrorCode::INVALID_PARAMS,
+        message: "Invalid params",
+        data: "Method parameters must be an array or an object or null",
+      })
+    end
+
+    begin
+      method = method_finder.call(method_name)
+
+      if method.nil?
+        return error_response(id: id, id_validation_pattern: id_validation_pattern, error: {
+          code: ErrorCode::METHOD_NOT_FOUND,
+          message: "Method not found",
+          data: method_name,
+        })
+      end
+
+      result = method.call(params)
+
+      success_response(id: id, result: result)
+    rescue StandardError => e
+      error_response(id: id, id_validation_pattern: id_validation_pattern, error: {
+        code: ErrorCode::INTERNAL_ERROR,
+        message: "Internal error",
+        data: e.message,
+      })
+    end
+  end
+
+  def valid_version?(version)
+    version == Version::V2_0
+  end
+
+  def valid_id?(id, pattern = nil)
+    return true if id.nil? || id.is_a?(Integer)
+    return false unless id.is_a?(String)
+
+    pattern ? id.match?(pattern) : true
+  end
+
+  def valid_method_name?(method)
+    method.is_a?(String) && !method.start_with?("rpc.")
+  end
+
+  def valid_params?(params)
+    params.nil? || params.is_a?(Array) || params.is_a?(Hash)
+  end
+
+  def success_response(id:, result:)
+    {
+      jsonrpc: Version::V2_0,
+      id: id,
+      result: result,
+    } unless id.nil?
+  end
+
+  def error_response(id:, id_validation_pattern:, error:)
+    {
+      jsonrpc: Version::V2_0,
+      id: valid_id?(id, id_validation_pattern) ? id : nil,
+      error: error.compact,
+    } unless id.nil?
+  end
+end

data/lib/mcp/client/http.rb

@@ -3,6 +3,8 @@
 module MCP
   class Client
     class HTTP
+      ACCEPT_HEADER = "application/json, text/event-stream"
+
       attr_reader :url
 
       def initialize(url:, headers: {})
@@ -14,46 +16,48 @@ module MCP
         method = request[:method] || request["method"]
         params = request[:params] || request["params"]
 
-        client.post("", request).body
+        response = client.post("", request)
+        validate_response_content_type!(response, method, params)
+        response.body
       rescue Faraday::BadRequestError => e
         raise RequestHandlerError.new(
           "The #{method} request is invalid",
-          { method:, params: },
+          { method: method, params: params },
           error_type: :bad_request,
           original_error: e,
         )
       rescue Faraday::UnauthorizedError => e
         raise RequestHandlerError.new(
           "You are unauthorized to make #{method} requests",
-          { method:, params: },
+          { method: method, params: params },
           error_type: :unauthorized,
           original_error: e,
         )
       rescue Faraday::ForbiddenError => e
         raise RequestHandlerError.new(
           "You are forbidden to make #{method} requests",
-          { method:, params: },
+          { method: method, params: params },
           error_type: :forbidden,
           original_error: e,
         )
       rescue Faraday::ResourceNotFound => e
         raise RequestHandlerError.new(
           "The #{method} request is not found",
-          { method:, params: },
+          { method: method, params: params },
           error_type: :not_found,
           original_error: e,
         )
       rescue Faraday::UnprocessableEntityError => e
         raise RequestHandlerError.new(
           "The #{method} request is unprocessable",
-          { method:, params: },
+          { method: method, params: params },
           error_type: :unprocessable_entity,
           original_error: e,
         )
       rescue Faraday::Error => e # Catch-all
         raise RequestHandlerError.new(
           "Internal error handling #{method} request",
-          { method:, params: },
+          { method: method, params: params },
           error_type: :internal_error,
           original_error: e,
         )
@@ -70,6 +74,7 @@ module MCP
           faraday.response(:json)
           faraday.response(:raise_error)
 
+          faraday.headers["Accept"] = ACCEPT_HEADER
           headers.each do |key, value|
             faraday.headers[key] = value
           end
@@ -83,6 +88,17 @@ module MCP
           "Add it to your Gemfile: gem 'faraday', '>= 2.0'" \
           "See https://rubygems.org/gems/faraday for more details."
       end
+
+      def validate_response_content_type!(response, method, params)
+        content_type = response.headers["Content-Type"]
+        return if content_type&.include?("application/json")
+
+        raise RequestHandlerError.new(
+          "Unsupported Content-Type: #{content_type.inspect}. This client only supports JSON responses.",
+          { method: method, params: params },
+          error_type: :unsupported_media_type,
+        )
+      end
     end
   end
 end

data/lib/mcp/client.rb

@@ -58,6 +58,20 @@ module MCP
       response.dig("result", "resources") || []
     end
 
+    # Returns the list of prompts available from the server.
+    # Each call will make a new request – the result is not cached.
+    #
+    # @return [Array<Hash>] An array of available prompts.
+    def prompts
+      response = transport.send_request(request: {
+        jsonrpc: JsonRpcHandler::Version::V2_0,
+        id: request_id,
+        method: "prompts/list",
+      })
+
+      response.dig("result", "prompts") || []
+    end
+
     # Calls a tool via the transport layer and returns the full response from the server.
     #
     # @param tool [MCP::Client::Tool] The tool to be called.
@@ -96,6 +110,21 @@ module MCP
       response.dig("result", "contents") || []
     end
 
+    # Gets a prompt from the server by name and returns its details.
+    #
+    # @param name [String] The name of the prompt to get.
+    # @return [Hash] A hash containing the prompt details.
+    def get_prompt(name:)
+      response = transport.send_request(request: {
+        jsonrpc: JsonRpcHandler::Version::V2_0,
+        id: request_id,
+        method: "prompts/get",
+        params: { name: name },
+      })
+
+      response.fetch("result", {})
+    end
+
     private
 
     def request_id

data/lib/mcp/configuration.rb

@@ -2,8 +2,10 @@
 
 module MCP
   class Configuration
-    DEFAULT_PROTOCOL_VERSION = "2025-06-18"
-    SUPPORTED_PROTOCOL_VERSIONS = [DEFAULT_PROTOCOL_VERSION, "2025-03-26", "2024-11-05"]
+    LATEST_STABLE_PROTOCOL_VERSION = "2025-11-25"
+    SUPPORTED_STABLE_PROTOCOL_VERSIONS = [
+      LATEST_STABLE_PROTOCOL_VERSION, "2025-06-18", "2025-03-26", "2024-11-05",
+    ]
 
     attr_writer :exception_reporter, :instrumentation_callback
 
@@ -33,7 +35,7 @@ module MCP
     end
 
     def protocol_version
-      @protocol_version || DEFAULT_PROTOCOL_VERSION
+      @protocol_version || LATEST_STABLE_PROTOCOL_VERSION
     end
 
     def protocol_version?
@@ -83,18 +85,18 @@ module MCP
       validate_tool_call_arguments = other.validate_tool_call_arguments
 
       Configuration.new(
-        exception_reporter:,
-        instrumentation_callback:,
-        protocol_version:,
-        validate_tool_call_arguments:,
+        exception_reporter: exception_reporter,
+        instrumentation_callback: instrumentation_callback,
+        protocol_version: protocol_version,
+        validate_tool_call_arguments: validate_tool_call_arguments,
       )
     end
 
     private
 
     def validate_protocol_version!(protocol_version)
-      unless SUPPORTED_PROTOCOL_VERSIONS.include?(protocol_version)
-        message = "protocol_version must be #{SUPPORTED_PROTOCOL_VERSIONS[0...-1].join(", ")}, or #{SUPPORTED_PROTOCOL_VERSIONS[-1]}"
+      unless SUPPORTED_STABLE_PROTOCOL_VERSIONS.include?(protocol_version)
+        message = "protocol_version must be #{SUPPORTED_STABLE_PROTOCOL_VERSIONS[0...-1].join(", ")}, or #{SUPPORTED_STABLE_PROTOCOL_VERSIONS[-1]}"
         raise ArgumentError, message
       end
     end

data/lib/mcp/content.rb

@@ -11,7 +11,7 @@ module MCP
       end
 
       def to_h
-        { text:, annotations:, type: "text" }.compact
+        { text: text, annotations: annotations, type: "text" }.compact
       end
     end
 
@@ -25,7 +25,7 @@ module MCP
       end
 
       def to_h
-        { data:, mime_type:, annotations:, type: "image" }.compact
+        { data: data, mime_type: mime_type, annotations: annotations, type: "image" }.compact
       end
     end
   end

data/lib/mcp/icon.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module MCP
+  class Icon
+    SUPPORTED_THEMES = ["light", "dark"]
+
+    attr_reader :mime_type, :sizes, :src, :theme
+
+    def initialize(mime_type: nil, sizes: nil, src: nil, theme: nil)
+      raise ArgumentError, 'The value of theme must specify "light" or "dark".' if theme && !SUPPORTED_THEMES.include?(theme)
+
+      @mime_type = mime_type
+      @sizes = sizes
+      @src = src
+      @theme = theme
+    end
+
+    def to_h
+      { mimeType: mime_type, sizes: sizes, src: src, theme: theme }.compact
+    end
+  end
+end

data/lib/mcp/instrumentation.rb

@@ -6,7 +6,7 @@ module MCP
       start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       begin
         @instrumentation_data = {}
-        add_instrumentation_data(method:)
+        add_instrumentation_data(method: method)
 
         result = yield block
 

data/lib/mcp/methods.rb

@@ -21,6 +21,7 @@ module MCP
 
     ROOTS_LIST = "roots/list"
     SAMPLING_CREATE_MESSAGE = "sampling/createMessage"
+    ELICITATION_CREATE = "elicitation/create"
 
     # Notification methods
     NOTIFICATIONS_INITIALIZED = "notifications/initialized"
@@ -76,6 +77,8 @@ module MCP
           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
         end

data/lib/mcp/prompt/message.rb

@@ -11,7 +11,7 @@ module MCP
       end
 
       def to_h
-        { role:, content: content.to_h }.compact
+        { role: role, content: content.to_h }.compact
       end
     end
   end

data/lib/mcp/prompt/result.rb

@@ -11,7 +11,7 @@ module MCP
       end
 
       def to_h
-        { description:, messages: messages.map(&:to_h) }.compact
+        { description: description, messages: messages.map(&:to_h) }.compact
       end
     end
   end

data/lib/mcp/prompt.rb

@@ -7,6 +7,7 @@ module MCP
 
       attr_reader :title_value
       attr_reader :description_value
+      attr_reader :icons_value
       attr_reader :arguments_value
       attr_reader :meta_value
 
@@ -19,6 +20,7 @@ module MCP
           name: name_value,
           title: title_value,
           description: description_value,
+          icons: icons&.map(&:to_h),
           arguments: arguments_value&.map(&:to_h),
           _meta: meta_value,
         }.compact
@@ -29,6 +31,7 @@ module MCP
         subclass.instance_variable_set(:@name_value, nil)
         subclass.instance_variable_set(:@title_value, nil)
         subclass.instance_variable_set(:@description_value, nil)
+        subclass.instance_variable_set(:@icons_value, nil)
         subclass.instance_variable_set(:@arguments_value, nil)
         subclass.instance_variable_set(:@meta_value, nil)
       end
@@ -61,6 +64,14 @@ module MCP
         end
       end
 
+      def icons(value = NOT_SET)
+        if value == NOT_SET
+          @icons_value
+        else
+          @icons_value = value
+        end
+      end
+
       def arguments(value = NOT_SET)
         if value == NOT_SET
           @arguments_value
@@ -77,14 +88,15 @@ module MCP
         end
       end
 
-      def define(name: nil, title: nil, description: nil, arguments: [], meta: nil, &block)
+      def define(name: nil, title: nil, description: nil, icons: [], arguments: [], meta: nil, &block)
         Class.new(self) do
           prompt_name name
           title title
           description description
+          icons icons
           arguments arguments
           define_singleton_method(:template) do |args, server_context: nil|
-            instance_exec(args, server_context:, &block)
+            instance_exec(args, server_context: server_context, &block)
           end
           meta meta
         end

data/lib/mcp/resource/contents.rb

@@ -11,7 +11,7 @@ module MCP
       end
 
       def to_h
-        { uri:, mime_type: }.compact
+        { uri: uri, mime_type: mime_type }.compact
       end
     end
 

data/lib/mcp/resource/embedded.rb

@@ -10,7 +10,7 @@ module MCP
       end
 
       def to_h
-        { resource: resource.to_h, annotations: }.compact
+        { resource: resource.to_h, annotations: annotations }.compact
       end
     end
   end

data/lib/mcp/resource.rb

@@ -2,13 +2,14 @@
 
 module MCP
   class Resource
-    attr_reader :uri, :name, :title, :description, :mime_type
+    attr_reader :uri, :name, :title, :description, :icons, :mime_type
 
-    def initialize(uri:, name:, title: nil, description: nil, mime_type: nil)
+    def initialize(uri:, name:, title: nil, description: nil, icons: [], mime_type: nil)
       @uri = uri
       @name = name
       @title = title
       @description = description
+      @icons = icons
       @mime_type = mime_type
     end
 
@@ -18,6 +19,7 @@ module MCP
         name: name,
         title: title,
         description: description,
+        icons: icons.map(&:to_h),
         mimeType: mime_type,
       }.compact
     end

data/lib/mcp/resource_template.rb

@@ -2,13 +2,14 @@
 
 module MCP
   class ResourceTemplate
-    attr_reader :uri_template, :name, :title, :description, :mime_type
+    attr_reader :uri_template, :name, :title, :description, :icons, :mime_type
 
-    def initialize(uri_template:, name:, title: nil, description: nil, mime_type: nil)
+    def initialize(uri_template:, name:, title: nil, description: nil, icons: [], mime_type: nil)
       @uri_template = uri_template
       @name = name
       @title = title
       @description = description
+      @icons = icons
       @mime_type = mime_type
     end
 
@@ -18,6 +19,7 @@ module MCP
         name: name,
         title: title,
         description: description,
+        icons: icons.map(&:to_h),
         mimeType: mime_type,
       }.compact
     end