mcp 0.1.0 → 0.3.0

data/examples/streamable_http_client.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "logger"
+
+# Logger for client operations
+logger = Logger.new($stdout)
+logger.formatter = proc do |severity, datetime, _progname, msg|
+  "[CLIENT] #{severity} #{datetime.strftime("%H:%M:%S.%L")} - #{msg}\n"
+end
+
+# Server configuration
+SERVER_URL = "http://localhost:9393/mcp"
+PROTOCOL_VERSION = "2024-11-05"
+
+# Helper method to make JSON-RPC requests
+def make_request(session_id, method, params = {}, id = nil)
+  uri = URI(SERVER_URL)
+  http = Net::HTTP.new(uri.host, uri.port)
+
+  request = Net::HTTP::Post.new(uri)
+  request["Content-Type"] = "application/json"
+  request["Mcp-Session-Id"] = session_id if session_id
+
+  body = {
+    jsonrpc: "2.0",
+    method: method,
+    params: params,
+    id: id || SecureRandom.uuid,
+  }
+
+  request.body = body.to_json
+  response = http.request(request)
+
+  {
+    status: response.code,
+    headers: response.to_hash,
+    body: JSON.parse(response.body),
+  }
+rescue => e
+  { error: e.message }
+end
+
+# Connect to SSE stream
+def connect_sse(session_id, logger)
+  uri = URI(SERVER_URL)
+
+  logger.info("Connecting to SSE stream...")
+
+  Net::HTTP.start(uri.host, uri.port) do |http|
+    request = Net::HTTP::Get.new(uri)
+    request["Mcp-Session-Id"] = session_id
+    request["Accept"] = "text/event-stream"
+    request["Cache-Control"] = "no-cache"
+
+    http.request(request) do |response|
+      if response.code == "200"
+        logger.info("SSE stream connected successfully")
+
+        response.read_body do |chunk|
+          chunk.split("\n").each do |line|
+            if line.start_with?("data: ")
+              data = line[6..-1]
+              begin
+                logger.info("SSE data: #{data}")
+              rescue JSON::ParserError
+                logger.debug("Non-JSON SSE data: #{data}")
+              end
+            elsif line.start_with?(": ")
+              logger.debug("SSE keepalive received: #{line}")
+            end
+          end
+        end
+      else
+        logger.error("Failed to connect to SSE: #{response.code} #{response.message}")
+      end
+    end
+  end
+rescue Interrupt
+  logger.info("SSE connection interrupted by user")
+rescue => e
+  logger.error("SSE connection error: #{e.message}")
+end
+
+# Main client flow
+def main
+  logger = Logger.new($stdout)
+  logger.formatter = proc do |severity, datetime, _progname, msg|
+    "[CLIENT] #{severity} #{datetime.strftime("%H:%M:%S.%L")} - #{msg}\n"
+  end
+
+  puts "=== MCP SSE Test Client ==="
+
+  # Step 1: Initialize session
+  logger.info("Initializing session...")
+
+  init_response = make_request(
+    nil,
+    "initialize",
+    {
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: {},
+      clientInfo: {
+        name: "sse-test-client",
+        version: "1.0",
+      },
+    },
+    "init-1",
+  )
+
+  if init_response[:error]
+    logger.error("Failed to initialize: #{init_response[:error]}")
+    exit(1)
+  end
+
+  session_id = init_response[:headers]["mcp-session-id"]&.first
+
+  if session_id.nil?
+    logger.error("No session ID received")
+    exit(1)
+  end
+
+  logger.info("Session initialized: #{session_id}")
+  logger.info("Server info: #{init_response[:body]["result"]["serverInfo"]}")
+
+  # Step 2: Start SSE connection in a separate thread
+  sse_thread = Thread.new { connect_sse(session_id, logger) }
+
+  # Give SSE time to connect
+  sleep(1)
+
+  # Step 3: Interactive menu
+  loop do
+    puts <<~MESSAGE.chomp
+
+      === Available Actions ===
+      1. Send custom notification
+      2. Test echo
+      3. List tools
+      0. Exit
+
+      Choose an action:#{" "}
+    MESSAGE
+
+    choice = gets.chomp
+
+    case choice
+    when "1"
+      print("Enter notification message: ")
+      message = gets.chomp
+      print("Enter delay in seconds (0 for immediate): ")
+      delay = gets.chomp.to_f
+
+      response = make_request(
+        session_id,
+        "tools/call",
+        {
+          name: "notification_tool",
+          arguments: {
+            message: message,
+            delay: delay,
+          },
+        },
+      )
+      if response[:body]["accepted"]
+        logger.info("Notification sent successfully")
+      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
+  end
+
+  # Clean up
+  sse_thread.kill if sse_thread.alive?
+
+  # Close session
+  logger.info("Closing session...")
+  make_request(session_id, "close")
+  logger.info("Session closed")
+rescue Interrupt
+  logger.info("Client interrupted by user")
+rescue => e
+  logger.error("Client error: #{e.message}")
+  logger.error(e.backtrace.join("\n"))
+end
+
+# Run the client
+if __FILE__ == $PROGRAM_NAME
+  main
+end

data/examples/streamable_http_server.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "mcp"
+require "mcp/server/transports/streamable_http_transport"
+require "rack"
+require "rackup"
+require "json"
+require "logger"
+
+# Create a logger for SSE-specific logging
+sse_logger = Logger.new($stdout)
+sse_logger.formatter = proc do |severity, datetime, _progname, msg|
+  "[SSE] #{severity} #{datetime.strftime("%H:%M:%S.%L")} - #{msg}\n"
+end
+
+# Tool that returns a response that will be sent via SSE if a stream is active
+class NotificationTool < MCP::Tool
+  tool_name "notification_tool"
+  description "Returns a notification message that will be sent via SSE if stream is active"
+  input_schema(
+    properties: {
+      message: { type: "string", description: "Message to send via SSE" },
+      delay: { type: "number", description: "Delay in seconds before returning (optional)" },
+    },
+    required: ["message"],
+  )
+
+  class << self
+    attr_accessor :logger
+
+    def call(message:, delay: 0)
+      sleep(delay) if delay > 0
+
+      logger&.info("Returning notification message: #{message}")
+
+      MCP::Tool::Response.new([{
+        type: "text",
+        text: "Notification: #{message} (timestamp: #{Time.now.iso8601})",
+      }])
+    end
+  end
+end
+
+# Create the server
+server = MCP::Server.new(
+  name: "sse_test_server",
+  tools: [NotificationTool],
+  prompts: [],
+  resources: [],
+)
+
+# Set logger for tools
+NotificationTool.logger = sse_logger
+
+# Add a simple echo tool for basic testing
+server.define_tool(
+  name: "echo",
+  description: "Simple echo tool",
+  input_schema: { properties: { message: { type: "string" } }, required: ["message"] },
+) do |message:|
+  MCP::Tool::Response.new([{ type: "text", text: "Echo: #{message}" }])
+end
+
+# Create the Streamable HTTP transport
+transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)
+server.transport = transport
+
+# Create a logger for MCP request/response logging
+mcp_logger = Logger.new($stdout)
+mcp_logger.formatter = proc do |_severity, _datetime, _progname, msg|
+  "[MCP] #{msg}\n"
+end
+
+# Create the Rack application
+app = proc do |env|
+  request = Rack::Request.new(env)
+
+  # Log request details
+  if request.post?
+    body = request.body.read
+    request.body.rewind
+    begin
+      parsed_body = JSON.parse(body)
+      mcp_logger.info("Request: #{parsed_body["method"]} (id: #{parsed_body["id"]})")
+
+      # Log SSE-specific setup
+      if parsed_body["method"] == "initialize"
+        sse_logger.info("New client initializing session")
+      end
+    rescue JSON::ParserError
+      mcp_logger.warn("Invalid JSON in request")
+    end
+  elsif request.get?
+    session_id = request.env["HTTP_MCP_SESSION_ID"] ||
+      Rack::Utils.parse_query(request.env["QUERY_STRING"])["sessionId"]
+    sse_logger.info("SSE connection request for session: #{session_id}")
+  end
+
+  # Handle the request
+  response = transport.handle_request(request)
+
+  # Log response details
+  status, headers, body = response
+  if body.is_a?(Array) && !body.empty? && request.post?
+    begin
+      parsed_response = JSON.parse(body.first)
+      if parsed_response["error"]
+        mcp_logger.error("Response error: #{parsed_response["error"]["message"]}")
+      elsif parsed_response["accepted"]
+        # Response was sent via SSE
+        sse_logger.info("Response sent via SSE stream")
+      else
+        mcp_logger.info("Response: success (id: #{parsed_response["id"]})")
+
+        # Log session ID for initialization
+        if headers["Mcp-Session-Id"]
+          sse_logger.info("Session created: #{headers["Mcp-Session-Id"]}")
+        end
+      end
+    rescue JSON::ParserError
+      mcp_logger.warn("Invalid JSON in response")
+    end
+  elsif request.get? && status == 200
+    sse_logger.info("SSE stream established")
+  end
+
+  response
+end
+
+# Build the Rack application with middleware
+rack_app = Rack::Builder.new do
+  use(Rack::CommonLogger, Logger.new($stdout))
+  use(Rack::ShowExceptions)
+  run(app)
+end
+
+# Print usage instructions
+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,14 +2,25 @@
 
 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
+    attr_writer :exception_reporter, :instrumentation_callback, :protocol_version, :validate_tool_call_arguments
 
-    def initialize(exception_reporter: nil, instrumentation_callback: nil, protocol_version: nil)
+    def initialize(exception_reporter: nil, instrumentation_callback: nil, protocol_version: nil,
+      validate_tool_call_arguments: true)
       @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
+
+      @validate_tool_call_arguments = validate_tool_call_arguments
     end
 
     def protocol_version
@@ -36,6 +47,12 @@ module MCP
       !@instrumentation_callback.nil?
     end
 
+    attr_reader :validate_tool_call_arguments
+
+    def validate_tool_call_arguments?
+      !!@validate_tool_call_arguments
+    end
+
     def merge(other)
       return self if other.nil?
 
@@ -54,11 +71,13 @@ module MCP
       else
         @protocol_version
       end
+      validate_tool_call_arguments = other.validate_tool_call_arguments
 
       Configuration.new(
         exception_reporter:,
         instrumentation_callback:,
         protocol_version:,
+        validate_tool_call_arguments:,
       )
     end