mcp 0.2.0 → 0.3.0

data/examples/http_client.rb

@@ -50,7 +50,7 @@ class MCPHTTPClient
       },
     })
     puts "Response: #{JSON.pretty_generate(result)}"
-    puts
+
     result
   end
 
@@ -58,7 +58,7 @@ class MCPHTTPClient
     puts "=== Sending ping ==="
     result = send_request("ping")
     puts "Response: #{JSON.pretty_generate(result)}"
-    puts
+
     result
   end
 
@@ -66,7 +66,7 @@ class MCPHTTPClient
     puts "=== Listing tools ==="
     result = send_request("tools/list")
     puts "Response: #{JSON.pretty_generate(result)}"
-    puts
+
     result
   end
 
@@ -77,7 +77,7 @@ class MCPHTTPClient
       arguments: arguments,
     })
     puts "Response: #{JSON.pretty_generate(result)}"
-    puts
+
     result
   end
 
@@ -85,7 +85,7 @@ class MCPHTTPClient
     puts "=== Listing prompts ==="
     result = send_request("prompts/list")
     puts "Response: #{JSON.pretty_generate(result)}"
-    puts
+
     result
   end
 
@@ -96,7 +96,7 @@ class MCPHTTPClient
       arguments: arguments,
     })
     puts "Response: #{JSON.pretty_generate(result)}"
-    puts
+
     result
   end
 
@@ -104,7 +104,7 @@ class MCPHTTPClient
     puts "=== Listing resources ==="
     result = send_request("resources/list")
     puts "Response: #{JSON.pretty_generate(result)}"
-    puts
+
     result
   end
 
@@ -114,7 +114,7 @@ class MCPHTTPClient
       uri: uri,
     })
     puts "Response: #{JSON.pretty_generate(result)}"
-    puts
+
     result
   end
 
@@ -131,7 +131,6 @@ class MCPHTTPClient
     response = http.request(request)
     result = JSON.parse(response.body)
     puts "Response: #{JSON.pretty_generate(result)}"
-    puts
 
     @session_id = nil
     result
@@ -140,10 +139,11 @@ end
 
 # Main script
 if __FILE__ == $PROGRAM_NAME
-  puts "MCP HTTP Client Example"
-  puts "Make sure the HTTP server is running (ruby examples/http_server.rb)"
-  puts "=" * 50
-  puts
+  puts <<~MESSAGE
+    MCP HTTP Client Example
+    Make sure the HTTP server is running (ruby examples/http_server.rb)
+    #{"=" * 50}
+  MESSAGE
 
   client = MCPHTTPClient.new
 

data/examples/http_server.rb

@@ -61,8 +61,9 @@ server = MCP::Server.new(
   prompts: [ExamplePrompt],
   resources: [
     MCP::Resource.new(
-      uri: "test_resource",
-      name: "Test resource",
+      uri: "https://test_resource.invalid",
+      name: "test-resource",
+      title: "Test Resource",
       description: "Test resource that echoes back the uri as its content",
       mime_type: "text/plain",
     ),
@@ -153,15 +154,17 @@ rack_app = Rack::Builder.new do
 end
 
 # Start the server
-puts "Starting MCP HTTP server on http://localhost:9292"
-puts "Use POST requests to initialize and send JSON-RPC commands"
-puts "Example initialization:"
-puts '  curl -i http://localhost:9292 --json \'{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}\''
-puts ""
-puts "The server will return a session ID in the Mcp-Session-Id header."
-puts "Use this session ID for subsequent requests."
-puts ""
-puts "Press Ctrl+C to stop the server"
+puts <<~MESSAGE
+  Starting MCP HTTP server on http://localhost:9292
+  Use POST requests to initialize and send JSON-RPC commands
+  Example initialization:
+    curl -i http://localhost:9292 --json '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
+
+  The server will return a session ID in the Mcp-Session-Id header.
+  Use this session ID for subsequent requests.
+
+  Press Ctrl+C to stop the server
+MESSAGE
 
 # Run the server
 # Use Rackup to run the server

data/examples/stdio_server.rb

@@ -58,8 +58,9 @@ server = MCP::Server.new(
   prompts: [ExamplePrompt],
   resources: [
     MCP::Resource.new(
-      uri: "test_resource",
-      name: "Test resource",
+      uri: "https://test_resource.invalid",
+      name: "test-resource",
+      title: "Test Resource",
       description: "Test resource that echoes back the uri as its content",
       mime_type: "text/plain",
     ),
@@ -85,7 +86,7 @@ server.resources_read_handler do |params|
   [{
     uri: params[:uri],
     mimeType: "text/plain",
-    text: "Hello, world!",
+    text: "Hello, world! URI: #{params[:uri]}",
   }]
 end
 

data/examples/streamable_http_client.rb

@@ -92,7 +92,6 @@ def main
   end
 
   puts "=== MCP SSE Test Client ==="
-  puts ""
 
   # Step 1: Initialize session
   logger.info("Initializing session...")
@@ -134,13 +133,16 @@ def main
 
   # Step 3: Interactive menu
   loop do
-    puts "\n=== Available Actions ==="
-    puts "1. Send custom notification"
-    puts "2. Test echo"
-    puts "3. List tools"
-    puts "0. Exit"
-    puts ""
-    print("Choose an action: ")
+    puts <<~MESSAGE.chomp
+
+      === Available Actions ===
+      1. Send custom notification
+      2. Test echo
+      3. List tools
+      0. Exit
+
+      Choose an action:#{" "}
+    MESSAGE
 
     choice = gets.chomp
 
@@ -167,19 +169,15 @@ def main
       else
         logger.error("Error: #{response[:body]["error"]}")
       end
-
     when "2"
       print("Enter message to echo: ")
       message = gets.chomp
       make_request(session_id, "tools/call", { name: "echo", arguments: { message: message } })
-
     when "3"
       make_request(session_id, "tools/list")
-
     when "0"
       logger.info("Exiting...")
       break
-
     else
       puts "Invalid choice"
     end

data/examples/streamable_http_server.rb

@@ -136,37 +136,38 @@ rack_app = Rack::Builder.new do
 end
 
 # Print usage instructions
-puts "=== MCP Streaming HTTP Test Server ==="
-puts ""
-puts "Starting server on http://localhost:9393"
-puts ""
-puts "Available Tools:"
-puts "1. NotificationTool - Returns messages that are sent via SSE when stream is active"
-puts "2. echo - Simple echo tool"
-puts ""
-puts "Testing SSE:"
-puts ""
-puts "1. Initialize session:"
-puts "   curl -i http://localhost:9393 \\"
-puts '     --json \'{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"sse-test","version":"1.0"}}}\''
-puts ""
-puts "2. Connect SSE stream (use the session ID from step 1):"
-puts '   curl -i -N -H "Mcp-Session-Id: YOUR_SESSION_ID" http://localhost:9393'
-puts ""
-puts "3. In another terminal, test tools (responses will be sent via SSE if stream is active):"
-puts ""
-puts "   Echo tool:"
-puts '   curl -i http://localhost:9393 -H "Mcp-Session-Id: YOUR_SESSION_ID" \\'
-puts '     --json \'{"jsonrpc":"2.0","method":"tools/call","id":2,"params":{"name":"echo","arguments":{"message":"Hello SSE!"}}}\''
-puts ""
-puts "   Notification tool (with 2 second delay):"
-puts '   curl -i http://localhost:9393 -H "Mcp-Session-Id: YOUR_SESSION_ID" \\'
-puts '     --json \'{"jsonrpc":"2.0","method":"tools/call","id":3,"params":{"name":"notification_tool","arguments":{"message":"Hello SSE!", "delay": 2}}}\''
-puts ""
-puts "Note: When an SSE stream is active, tool responses will appear in the SSE stream and the POST request will return {\"accepted\": true}"
-puts ""
-puts "Press Ctrl+C to stop the server"
-puts ""
+puts <<~MESSAGE
+  === MCP Streaming HTTP Test Server ===
+
+  Starting server on http://localhost:9393
+
+  Available Tools:
+  1. NotificationTool - Returns messages that are sent via SSE when stream is active"
+  2. echo - Simple echo tool
+
+  Testing SSE:
+
+  1. Initialize session:
+     curl -i http://localhost:9393 \\
+       --json '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"sse-test","version":"1.0"}}}'
+
+  2. Connect SSE stream (use the session ID from step 1):"
+     curl -i -N -H "Mcp-Session-Id: YOUR_SESSION_ID" http://localhost:9393
+
+  3. In another terminal, test tools (responses will be sent via SSE if stream is active):
+
+     Echo tool:
+     curl -i http://localhost:9393 -H "Mcp-Session-Id: YOUR_SESSION_ID" \\
+       --json '{"jsonrpc":"2.0","method":"tools/call","id":2,"params":{"name":"echo","arguments":{"message":"Hello SSE!"}}}'
+
+     Notification tool (with 2 second delay):
+     curl -i http://localhost:9393 -H "Mcp-Session-Id: YOUR_SESSION_ID" \\
+       --json '{"jsonrpc":"2.0","method":"tools/call","id":3,"params":{"name":"notification_tool","arguments":{"message":"Hello SSE!", "delay": 2}}}'
+
+  Note: When an SSE stream is active, tool responses will appear in the SSE stream and the POST request will return {"accepted": true}
+
+  Press Ctrl+C to stop the server
+MESSAGE
 
 # Start the server
 Rackup::Handler.get("puma").run(rack_app, Port: 9393, Host: "localhost")

data/lib/mcp/client/http.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module MCP
+  class Client
+    class HTTP
+      attr_reader :url
+
+      def initialize(url:, headers: {})
+        @url = url
+        @headers = headers
+      end
+
+      def send_request(request:)
+        method = request[:method] || request["method"]
+        params = request[:params] || request["params"]
+
+        client.post("", request).body
+      rescue Faraday::BadRequestError => e
+        raise RequestHandlerError.new(
+          "The #{method} request is invalid",
+          { method:, params: },
+          error_type: :bad_request,
+          original_error: e,
+        )
+      rescue Faraday::UnauthorizedError => e
+        raise RequestHandlerError.new(
+          "You are unauthorized to make #{method} requests",
+          { method:, params: },
+          error_type: :unauthorized,
+          original_error: e,
+        )
+      rescue Faraday::ForbiddenError => e
+        raise RequestHandlerError.new(
+          "You are forbidden to make #{method} requests",
+          { method:, params: },
+          error_type: :forbidden,
+          original_error: e,
+        )
+      rescue Faraday::ResourceNotFound => e
+        raise RequestHandlerError.new(
+          "The #{method} request is not found",
+          { method:, params: },
+          error_type: :not_found,
+          original_error: e,
+        )
+      rescue Faraday::UnprocessableEntityError => e
+        raise RequestHandlerError.new(
+          "The #{method} request is unprocessable",
+          { method:, params: },
+          error_type: :unprocessable_entity,
+          original_error: e,
+        )
+      rescue Faraday::Error => e # Catch-all
+        raise RequestHandlerError.new(
+          "Internal error handling #{method} request",
+          { method:, params: },
+          error_type: :internal_error,
+          original_error: e,
+        )
+      end
+
+      private
+
+      attr_reader :headers
+
+      def client
+        require_faraday!
+        @client ||= Faraday.new(url) do |faraday|
+          faraday.request(:json)
+          faraday.response(:json)
+          faraday.response(:raise_error)
+
+          headers.each do |key, value|
+            faraday.headers[key] = value
+          end
+        end
+      end
+
+      def require_faraday!
+        require "faraday"
+      rescue LoadError
+        raise LoadError, "The 'faraday' gem is required to use the MCP client HTTP transport. " \
+          "Add it to your Gemfile: gem 'faraday', '>= 2.0'" \
+          "See https://rubygems.org/gems/faraday for more details."
+      end
+    end
+  end
+end

data/lib/mcp/client/tool.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module MCP
+  class Client
+    class Tool
+      attr_reader :name, :description, :input_schema, :output_schema
+
+      def initialize(name:, description:, input_schema:, output_schema: nil)
+        @name = name
+        @description = description
+        @input_schema = input_schema
+        @output_schema = output_schema
+      end
+    end
+  end
+end

data/lib/mcp/client.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module MCP
+  class Client
+    # Initializes a new MCP::Client instance.
+    #
+    # @param transport [Object] The transport object to use for communication with the server.
+    #   The transport should be a duck type that responds to `send_request`. See the README for more details.
+    #
+    # @example
+    #   transport = MCP::Client::HTTP.new(url: "http://localhost:3000")
+    #   client = MCP::Client.new(transport: transport)
+    def initialize(transport:)
+      @transport = transport
+    end
+
+    # The user may want to access additional transport-specific methods/attributes
+    # So keeping it public
+    attr_reader :transport
+
+    # Returns the list of tools available from the server.
+    # Each call will make a new request – the result is not cached.
+    #
+    # @return [Array<MCP::Client::Tool>] An array of available tools.
+    #
+    # @example
+    #   tools = client.tools
+    #   tools.each do |tool|
+    #     puts tool.name
+    #   end
+    def tools
+      response = transport.send_request(request: {
+        jsonrpc: JsonRpcHandler::Version::V2_0,
+        id: request_id,
+        method: "tools/list",
+      })
+
+      response.dig("result", "tools")&.map do |tool|
+        Tool.new(
+          name: tool["name"],
+          description: tool["description"],
+          input_schema: tool["inputSchema"],
+        )
+      end || []
+    end
+
+    # Calls a tool via the transport layer.
+    #
+    # @param tool [MCP::Client::Tool] The tool to be called.
+    # @param arguments [Object, nil] The arguments to pass to the tool.
+    # @return [Object] The result of the tool call, as returned by the transport.
+    #
+    # @example
+    #   tool = client.tools.first
+    #   result = client.call_tool(tool: tool, arguments: { foo: "bar" })
+    #
+    # @note
+    #   The exact requirements for `arguments` are determined by the transport layer in use.
+    #   Consult the documentation for your transport (e.g., MCP::Client::HTTP) for details.
+    def call_tool(tool:, arguments: nil)
+      response = transport.send_request(request: {
+        jsonrpc: JsonRpcHandler::Version::V2_0,
+        id: request_id,
+        method: "tools/call",
+        params: { name: tool.name, arguments: arguments },
+      })
+
+      response.dig("result", "content")
+    end
+
+    private
+
+    def request_id
+      SecureRandom.uuid
+    end
+
+    class RequestHandlerError < StandardError
+      attr_reader :error_type, :original_error, :request
+
+      def initialize(message, request, error_type: :internal_error, original_error: nil)
+        super(message)
+        @request = request
+        @error_type = error_type
+        @original_error = original_error
+      end
+    end
+  end
+end

data/lib/mcp/configuration.rb

@@ -2,7 +2,8 @@
 
 module MCP
   class Configuration
-    DEFAULT_PROTOCOL_VERSION = "2024-11-05"
+    DEFAULT_PROTOCOL_VERSION = "2025-06-18"
+    SUPPORTED_PROTOCOL_VERSIONS = [DEFAULT_PROTOCOL_VERSION, "2025-03-26", "2024-11-05"]
 
     attr_writer :exception_reporter, :instrumentation_callback, :protocol_version, :validate_tool_call_arguments
 
@@ -11,6 +12,10 @@ module MCP
       @exception_reporter = exception_reporter
       @instrumentation_callback = instrumentation_callback
       @protocol_version = protocol_version
+      if protocol_version && !SUPPORTED_PROTOCOL_VERSIONS.include?(protocol_version)
+        message = "protocol_version must be #{SUPPORTED_PROTOCOL_VERSIONS[0...-1].join(", ")}, or #{SUPPORTED_PROTOCOL_VERSIONS[-1]}"
+        raise ArgumentError, message
+      end
       unless validate_tool_call_arguments.is_a?(TrueClass) || validate_tool_call_arguments.is_a?(FalseClass)
         raise ArgumentError, "validate_tool_call_arguments must be a boolean"
       end

data/lib/mcp/prompt.rb

@@ -6,6 +6,7 @@ module MCP
     class << self
       NOT_SET = Object.new
 
+      attr_reader :title_value
       attr_reader :description_value
       attr_reader :arguments_value
 
@@ -14,12 +15,13 @@ module MCP
       end
 
       def to_h
-        { name: name_value, description: description_value, arguments: arguments_value.map(&:to_h) }.compact
+        { name: name_value, title: title_value, description: description_value, arguments: arguments_value.map(&:to_h) }.compact
       end
 
       def inherited(subclass)
         super
         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(:@arguments_value, nil)
       end
@@ -36,6 +38,14 @@ module MCP
         @name_value || StringUtils.handle_from_class_name(name)
       end
 
+      def title(value = NOT_SET)
+        if value == NOT_SET
+          @title_value
+        else
+          @title_value = value
+        end
+      end
+
       def description(value = NOT_SET)
         if value == NOT_SET
           @description_value
@@ -52,9 +62,10 @@ module MCP
         end
       end
 
-      def define(name: nil, description: nil, arguments: [], &block)
+      def define(name: nil, title: nil, description: nil, arguments: [], &block)
         Class.new(self) do
           prompt_name name
+          title title
           description description
           arguments arguments
           define_singleton_method(:template) do |args, server_context: nil|

data/lib/mcp/resource.rb

@@ -3,21 +3,23 @@
 
 module MCP
   class Resource
-    attr_reader :uri, :name, :description, :mime_type
+    attr_reader :uri, :name, :title, :description, :mime_type
 
-    def initialize(uri:, name:, description: nil, mime_type: nil)
+    def initialize(uri:, name:, title: nil, description: nil, mime_type: nil)
       @uri = uri
       @name = name
+      @title = title
       @description = description
       @mime_type = mime_type
     end
 
     def to_h
       {
-        uri: @uri,
-        name: @name,
-        description: @description,
-        mimeType: @mime_type,
+        uri: uri,
+        name: name,
+        title: title,
+        description: description,
+        mimeType: mime_type,
       }.compact
     end
   end

data/lib/mcp/resource_template.rb

@@ -3,21 +3,23 @@
 
 module MCP
   class ResourceTemplate
-    attr_reader :uri_template, :name, :description, :mime_type
+    attr_reader :uri_template, :name, :title, :description, :mime_type
 
-    def initialize(uri_template:, name:, description: nil, mime_type: nil)
+    def initialize(uri_template:, name:, title: nil, description: nil, mime_type: nil)
       @uri_template = uri_template
       @name = name
+      @title = title
       @description = description
       @mime_type = mime_type
     end
 
     def to_h
       {
-        uriTemplate: @uri_template,
-        name: @name,
-        description: @description,
-        mimeType: @mime_type,
+        uriTemplate: uri_template,
+        name: name,
+        title: title,
+        description: description,
+        mimeType: mime_type,
       }.compact
     end
   end

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

@@ -34,7 +34,13 @@ module MCP
           end
         end
 
-        def send_notification(notification, session_id: nil)
+        def send_notification(method, params = nil, session_id: nil)
+          notification = {
+            jsonrpc: "2.0",
+            method:,
+          }
+          notification[:params] = params if params
+
           @mutex.synchronize do
             if session_id
               # Send to specific session
@@ -102,6 +108,8 @@ module MCP
 
           if body["method"] == "initialize"
             handle_initialization(body_string, body)
+          elsif body["method"] == MCP::Methods::NOTIFICATIONS_INITIALIZED
+            handle_notification_initialized
           else
             handle_regular_request(body_string, session_id)
           end
@@ -179,6 +187,10 @@ module MCP
           [200, headers, [response]]
         end
 
+        def handle_notification_initialized
+          [202, {}, []]
+        end
+
         def handle_regular_request(body_string, session_id)
           # If session ID is provided, but not in the sessions hash, return an error
           if session_id && !@sessions.key?(session_id)