mcp 0.1.0 → 0.2.0

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

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+require_relative "../../transport"
+require "json"
+require "securerandom"
+
+module MCP
+  class Server
+    module Transports
+      class StreamableHTTPTransport < Transport
+        def initialize(server)
+          super
+          # { session_id => { stream: stream_object }
+          @sessions = {}
+          @mutex = Mutex.new
+        end
+
+        def handle_request(request)
+          case request.env["REQUEST_METHOD"]
+          when "POST"
+            handle_post(request)
+          when "GET"
+            handle_get(request)
+          when "DELETE"
+            handle_delete(request)
+          else
+            [405, { "Content-Type" => "application/json" }, [{ error: "Method not allowed" }.to_json]]
+          end
+        end
+
+        def close
+          @mutex.synchronize do
+            @sessions.each_key { |session_id| cleanup_session_unsafe(session_id) }
+          end
+        end
+
+        def send_notification(notification, session_id: nil)
+          @mutex.synchronize do
+            if session_id
+              # Send to specific session
+              session = @sessions[session_id]
+              return false unless session && session[:stream]
+
+              begin
+                send_to_stream(session[:stream], notification)
+                true
+              rescue IOError, Errno::EPIPE => e
+                MCP.configuration.exception_reporter.call(
+                  e,
+                  { session_id: session_id, error: "Failed to send notification" },
+                )
+                cleanup_session_unsafe(session_id)
+                false
+              end
+            else
+              # Broadcast to all connected SSE sessions
+              sent_count = 0
+              failed_sessions = []
+
+              @sessions.each do |sid, session|
+                next unless session[:stream]
+
+                begin
+                  send_to_stream(session[:stream], notification)
+                  sent_count += 1
+                rescue IOError, Errno::EPIPE => e
+                  MCP.configuration.exception_reporter.call(
+                    e,
+                    { session_id: sid, error: "Failed to send notification" },
+                  )
+                  failed_sessions << sid
+                end
+              end
+
+              # Clean up failed sessions
+              failed_sessions.each { |sid| cleanup_session_unsafe(sid) }
+
+              sent_count
+            end
+          end
+        end
+
+        private
+
+        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)
+        end
+
+        def send_ping_to_stream(stream)
+          stream.write(": ping #{Time.now.iso8601}\n\n")
+          stream.flush if stream.respond_to?(:flush)
+        end
+
+        def handle_post(request)
+          body_string = request.body.read
+          session_id = extract_session_id(request)
+
+          body = parse_request_body(body_string)
+          return body unless body.is_a?(Hash) # Error response
+
+          if body["method"] == "initialize"
+            handle_initialization(body_string, body)
+          else
+            handle_regular_request(body_string, session_id)
+          end
+        rescue StandardError => e
+          MCP.configuration.exception_reporter.call(e, { request: body_string })
+          [500, { "Content-Type" => "application/json" }, [{ error: "Internal server error" }.to_json]]
+        end
+
+        def handle_get(request)
+          session_id = extract_session_id(request)
+
+          return missing_session_id_response unless session_id
+          return session_not_found_response unless session_exists?(session_id)
+
+          setup_sse_stream(session_id)
+        end
+
+        def handle_delete(request)
+          session_id = request.env["HTTP_MCP_SESSION_ID"]
+
+          return [
+            400,
+            { "Content-Type" => "application/json" },
+            [{ error: "Missing session ID" }.to_json],
+          ] unless session_id
+
+          cleanup_session(session_id)
+          [200, { "Content-Type" => "application/json" }, [{ success: true }.to_json]]
+        end
+
+        def cleanup_session(session_id)
+          @mutex.synchronize do
+            cleanup_session_unsafe(session_id)
+          end
+        end
+
+        def cleanup_session_unsafe(session_id)
+          session = @sessions[session_id]
+          return unless session
+
+          begin
+            session[:stream]&.close
+          rescue
+            nil
+          end
+          @sessions.delete(session_id)
+        end
+
+        def extract_session_id(request)
+          request.env["HTTP_MCP_SESSION_ID"]
+        end
+
+        def parse_request_body(body_string)
+          JSON.parse(body_string)
+        rescue JSON::ParserError, TypeError
+          [400, { "Content-Type" => "application/json" }, [{ error: "Invalid JSON" }.to_json]]
+        end
+
+        def handle_initialization(body_string, body)
+          session_id = SecureRandom.uuid
+
+          @mutex.synchronize do
+            @sessions[session_id] = {
+              stream: nil,
+            }
+          end
+
+          response = @server.handle_json(body_string)
+
+          headers = {
+            "Content-Type" => "application/json",
+            "Mcp-Session-Id" => session_id,
+          }
+
+          [200, headers, [response]]
+        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)
+            return [400, { "Content-Type" => "application/json" }, [{ error: "Invalid session ID" }.to_json]]
+          end
+
+          response = @server.handle_json(body_string)
+          stream = get_session_stream(session_id) if session_id
+
+          if stream
+            send_response_to_stream(stream, response, session_id)
+          else
+            [200, { "Content-Type" => "application/json" }, [response]]
+          end
+        end
+
+        def get_session_stream(session_id)
+          @mutex.synchronize { @sessions[session_id]&.fetch(:stream, nil) }
+        end
+
+        def send_response_to_stream(stream, response, session_id)
+          message = JSON.parse(response)
+          send_to_stream(stream, message)
+          [200, { "Content-Type" => "application/json" }, [{ accepted: true }.to_json]]
+        rescue IOError, Errno::EPIPE => e
+          MCP.configuration.exception_reporter.call(
+            e,
+            { session_id: session_id, error: "Stream closed during response" },
+          )
+          cleanup_session(session_id)
+          [200, { "Content-Type" => "application/json" }, [response]]
+        end
+
+        def session_exists?(session_id)
+          @mutex.synchronize { @sessions.key?(session_id) }
+        end
+
+        def missing_session_id_response
+          [400, { "Content-Type" => "application/json" }, [{ error: "Missing session ID" }.to_json]]
+        end
+
+        def session_not_found_response
+          [404, { "Content-Type" => "application/json" }, [{ error: "Session not found" }.to_json]]
+        end
+
+        def setup_sse_stream(session_id)
+          body = create_sse_body(session_id)
+
+          headers = {
+            "Content-Type" => "text/event-stream",
+            "Cache-Control" => "no-cache",
+            "Connection" => "keep-alive",
+          }
+
+          [200, headers, body]
+        end
+
+        def create_sse_body(session_id)
+          proc do |stream|
+            store_stream_for_session(session_id, stream)
+            start_keepalive_thread(session_id)
+          end
+        end
+
+        def store_stream_for_session(session_id, stream)
+          @mutex.synchronize do
+            if @sessions[session_id]
+              @sessions[session_id][:stream] = stream
+            else
+              stream.close
+            end
+          end
+        end
+
+        def start_keepalive_thread(session_id)
+          Thread.new do
+            while session_active_with_stream?(session_id)
+              sleep(30)
+              send_keepalive_ping(session_id)
+            end
+          rescue StandardError => e
+            MCP.configuration.exception_reporter.call(e, { session_id: session_id })
+          ensure
+            cleanup_session(session_id)
+          end
+        end
+
+        def session_active_with_stream?(session_id)
+          @mutex.synchronize { @sessions.key?(session_id) && @sessions[session_id][: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])
+            end
+          end
+        rescue IOError, Errno::EPIPE => e
+          MCP.configuration.exception_reporter.call(
+            e,
+            { session_id: session_id, error: "Stream closed" },
+          )
+          raise # Re-raise to exit the keepalive loop
+        end
+      end
+    end
+  end
+end

data/lib/mcp/server.rb

@@ -20,10 +20,18 @@ module MCP
       end
     end
 
+    class MethodAlreadyDefinedError < StandardError
+      attr_reader :method_name
+
+      def initialize(method_name)
+        super("Method #{method_name} already defined")
+        @method_name = method_name
+      end
+    end
+
     include Instrumentation
 
-    attr_writer :capabilities
-    attr_accessor :name, :version, :tools, :prompts, :resources, :server_context, :configuration
+    attr_accessor :name, :version, :tools, :prompts, :resources, :server_context, :configuration, :capabilities, :transport
 
     def initialize(
       name: "model_context_protocol",
@@ -34,7 +42,8 @@ module MCP
       resource_templates: [],
       server_context: nil,
       configuration: nil,
-      capabilities: nil
+      capabilities: nil,
+      transport: nil
     )
       @name = name
       @version = version
@@ -45,6 +54,7 @@ module MCP
       @resource_index = index_resources_by_uri(resources)
       @server_context = server_context
       @configuration = MCP.configuration.merge(configuration)
+      @capabilities = capabilities || default_capabilities
 
       @handlers = {
         Methods::RESOURCES_LIST => method(:list_resources),
@@ -63,10 +73,7 @@ module MCP
         Methods::COMPLETION_COMPLETE => ->(_) {},
         Methods::LOGGING_SET_LEVEL => ->(_) {},
       }
-    end
-
-    def capabilities
-      @capabilities ||= determine_capabilities
+      @transport = transport
     end
 
     def handle(request)
@@ -91,6 +98,38 @@ module MCP
       @prompts[prompt.name_value] = prompt
     end
 
+    def define_custom_method(method_name:, &block)
+      if @handlers.key?(method_name)
+        raise MethodAlreadyDefinedError, method_name
+      end
+
+      @handlers[method_name] = block
+    end
+
+    def notify_tools_list_changed
+      return unless @transport
+
+      @transport.send_notification(Methods::NOTIFICATIONS_TOOLS_LIST_CHANGED)
+    rescue => e
+      report_exception(e, { notification: "tools_list_changed" })
+    end
+
+    def notify_prompts_list_changed
+      return unless @transport
+
+      @transport.send_notification(Methods::NOTIFICATIONS_PROMPTS_LIST_CHANGED)
+    rescue => e
+      report_exception(e, { notification: "prompts_list_changed" })
+    end
+
+    def notify_resources_list_changed
+      return unless @transport
+
+      @transport.send_notification(Methods::NOTIFICATIONS_RESOURCES_LIST_CHANGED)
+    rescue => e
+      report_exception(e, { notification: "resources_list_changed" })
+    end
+
     def resources_list_handler(&block)
       @handlers[Methods::RESOURCES_LIST] = block
     end
@@ -159,16 +198,12 @@ module MCP
       }
     end
 
-    def determine_capabilities
-      defines_prompts = @prompts.any? || @handlers[Methods::PROMPTS_LIST] != method(:list_prompts)
-      defines_tools = @tools.any? || @handlers[Methods::TOOLS_LIST] != method(:list_tools)
-      defines_resources = @resources.any? || @handlers[Methods::RESOURCES_LIST] != method(:list_resources)
-      defines_resource_templates = @resource_templates.any? || @handlers[Methods::RESOURCES_TEMPLATES_LIST] != method(:list_resource_templates)
+    def default_capabilities
       {
-        prompts: defines_prompts ? {} : nil,
-        resources: defines_resources || defines_resource_templates ? {} : nil,
-        tools: defines_tools ? {} : nil,
-      }.compact
+        tools: { listChanged: true },
+        prompts: { listChanged: true },
+        resources: { listChanged: true },
+      }
     end
 
     def server_info
@@ -179,7 +214,6 @@ module MCP
     end
 
     def init(request)
-      add_instrumentation_data(method: Methods::INITIALIZE)
       {
         protocolVersion: configuration.protocol_version,
         capabilities: capabilities,
@@ -188,12 +222,10 @@ module MCP
     end
 
     def list_tools(request)
-      add_instrumentation_data(method: Methods::TOOLS_LIST)
       @tools.map { |_, tool| tool.to_h }
     end
 
     def call_tool(request)
-      add_instrumentation_data(method: Methods::TOOLS_CALL)
       tool_name = request[:name]
       tool = tools[tool_name]
       unless tool
@@ -213,26 +245,27 @@ module MCP
         )
       end
 
-      begin
-        call_params = tool_call_parameters(tool)
-
-        if call_params.include?(:server_context)
-          tool.call(**arguments.transform_keys(&:to_sym), server_context:).to_h
-        else
-          tool.call(**arguments.transform_keys(&:to_sym)).to_h
+      if configuration.validate_tool_call_arguments && tool.input_schema
+        begin
+          tool.input_schema.validate_arguments(arguments)
+        rescue Tool::InputSchema::ValidationError => e
+          add_instrumentation_data(error: :invalid_schema)
+          raise RequestHandlerError.new(e.message, request, error_type: :invalid_schema)
         end
+      end
+
+      begin
+        call_tool_with_args(tool, arguments)
       rescue => e
         raise RequestHandlerError.new("Internal error calling tool #{tool_name}", request, original_error: e)
       end
     end
 
     def list_prompts(request)
-      add_instrumentation_data(method: Methods::PROMPTS_LIST)
       @prompts.map { |_, prompt| prompt.to_h }
     end
 
     def get_prompt(request)
-      add_instrumentation_data(method: Methods::PROMPTS_GET)
       prompt_name = request[:name]
       prompt = @prompts[prompt_name]
       unless prompt
@@ -245,25 +278,20 @@ module MCP
       prompt_args = request[:arguments]
       prompt.validate_arguments!(prompt_args)
 
-      prompt.template(prompt_args, server_context:).to_h
+      call_prompt_template_with_args(prompt, prompt_args)
     end
 
     def list_resources(request)
-      add_instrumentation_data(method: Methods::RESOURCES_LIST)
-
       @resources.map(&:to_h)
     end
 
     # Server implementation should set `resources_read_handler` to override no-op default
     def read_resource_no_content(request)
-      add_instrumentation_data(method: Methods::RESOURCES_READ)
       add_instrumentation_data(resource_uri: request[:uri])
       []
     end
 
     def list_resource_templates(request)
-      add_instrumentation_data(method: Methods::RESOURCES_TEMPLATES_LIST)
-
       @resource_templates.map(&:to_h)
     end
 
@@ -277,22 +305,29 @@ module MCP
       end
     end
 
-    def tool_call_parameters(tool)
-      method_def = tool_call_method_def(tool)
-      method_def.parameters.flatten
+    def accepts_server_context?(method_object)
+      parameters = method_object.parameters
+      accepts_server_context = parameters.any? { |_type, name| name == :server_context }
+      has_kwargs = parameters.any? { |type, _| type == :keyrest }
+
+      accepts_server_context || has_kwargs
     end
 
-    def tool_call_method_def(tool)
-      method = tool.method(:call)
+    def call_tool_with_args(tool, arguments)
+      args = arguments.transform_keys(&:to_sym)
 
-      if defined?(T::Utils) && T::Utils.respond_to?(:signature_for_method)
-        sorbet_typed_method_definition = T::Utils.signature_for_method(method)&.method
+      if accepts_server_context?(tool.method(:call))
+        tool.call(**args, server_context: server_context).to_h
+      else
+        tool.call(**args).to_h
+      end
+    end
 
-        # Return the Sorbet typed method definition if it exists, otherwise fallback to original method
-        # definition if Sorbet is defined but not used by this tool.
-        sorbet_typed_method_definition || method
+    def call_prompt_template_with_args(prompt, args)
+      if accepts_server_context?(prompt.method(:template))
+        prompt.template(args, server_context: server_context).to_h
       else
-        method
+        prompt.template(args).to_h
       end
     end
   end

data/lib/mcp/tool/input_schema.rb

@@ -1,17 +1,24 @@
 # frozen_string_literal: true
 
+require "json-schema"
+
 module MCP
   class Tool
     class InputSchema
+      class ValidationError < StandardError; end
+
       attr_reader :properties, :required
 
       def initialize(properties: {}, required: [])
         @properties = properties
         @required = required.map(&:to_sym)
+        validate_schema!
       end
 
       def to_h
-        { type: "object", properties:, required: }
+        { type: "object", properties: }.tap do |hsh|
+          hsh[:required] = required if required.any?
+        end
       end
 
       def missing_required_arguments?(arguments)
@@ -21,6 +28,42 @@ module MCP
       def missing_required_arguments(arguments)
         (required - arguments.keys.map(&:to_sym))
       end
+
+      def validate_arguments(arguments)
+        errors = JSON::Validator.fully_validate(to_h, arguments)
+        if errors.any?
+          raise ValidationError, "Invalid arguments: #{errors.join(", ")}"
+        end
+      end
+
+      private
+
+      def validate_schema!
+        check_for_refs!
+        schema = to_h
+        schema_reader = JSON::Schema::Reader.new(
+          accept_uri: false,
+          accept_file: ->(path) { path.to_s.start_with?(Gem.loaded_specs["json-schema"].full_gem_path) },
+        )
+        metaschema = JSON::Validator.validator_for_name("draft4").metaschema
+        errors = JSON::Validator.fully_validate(metaschema, schema, schema_reader: schema_reader)
+        if errors.any?
+          raise ArgumentError, "Invalid JSON Schema: #{errors.join(", ")}"
+        end
+      end
+
+      def check_for_refs!(obj = properties)
+        case obj
+        when Hash
+          if obj.key?("$ref") || obj.key?(:$ref)
+            raise ArgumentError, "Invalid JSON Schema: $ref is not allowed in tool input schemas"
+          end
+
+          obj.each_value { |value| check_for_refs!(value) }
+        when Array
+          obj.each { |item| check_for_refs!(item) }
+        end
+      end
     end
   end
 end

data/lib/mcp/tool.rb

@@ -9,7 +9,7 @@ module MCP
       attr_reader :input_schema_value
       attr_reader :annotations_value
 
-      def call(*args, server_context:)
+      def call(*args, server_context: nil)
         raise NotImplementedError, "Subclasses must implement call"
       end
 

data/lib/mcp/transport.rb

@@ -2,32 +2,44 @@
 
 module MCP
   class Transport
+    # Initialize the transport with the server instance
     def initialize(server)
       @server = server
     end
 
+    # Send a response to the client
     def send_response(response)
       raise NotImplementedError, "Subclasses must implement send_response"
     end
 
+    # Open the transport connection
     def open
       raise NotImplementedError, "Subclasses must implement open"
     end
 
+    # Close the transport connection
     def close
       raise NotImplementedError, "Subclasses must implement close"
     end
 
-    private
+    # Handle a JSON request
+    # Returns a response that should be sent back to the client
+    def handle_json_request(request)
+      response = @server.handle_json(request)
+      send_response(response) if response
+    end
 
+    # Handle an incoming request
+    # Returns a response that should be sent back to the client
     def handle_request(request)
       response = @server.handle(request)
       send_response(response) if response
     end
 
-    def handle_json_request(request)
-      response = @server.handle_json(request)
-      send_response(response) if response
+    # Send a notification to the client
+    # Returns true if the notification was sent successfully
+    def send_notification(method, params = nil)
+      raise NotImplementedError, "Subclasses must implement send_notification"
     end
   end
 end

data/lib/mcp/transports/stdio.rb

@@ -1,35 +1,15 @@
 # frozen_string_literal: true
 
-require_relative "../transport"
-require "json"
+require_relative "../server/transports/stdio_transport"
+
+warn <<~MESSAGE, uplevel: 3
+  Use `require "mcp/server/transports/stdio_transport"` instead of `require "mcp/transports/stdio"`.
+  Also use `MCP::Server::Transports::StdioTransport` instead of `MCP::Transports::StdioTransport`.
+  This API is deprecated and will be removed in a future release.
+MESSAGE
 
 module MCP
   module Transports
-    class StdioTransport < Transport
-      def initialize(server)
-        @server = server
-        @open = false
-        $stdin.set_encoding("UTF-8")
-        $stdout.set_encoding("UTF-8")
-        super
-      end
-
-      def open
-        @open = true
-        while @open && (line = $stdin.gets)
-          handle_json_request(line.strip)
-        end
-      end
-
-      def close
-        @open = false
-      end
-
-      def send_response(message)
-        json_message = message.is_a?(String) ? message : JSON.generate(message)
-        $stdout.puts(json_message)
-        $stdout.flush
-      end
-    end
+    StdioTransport = Server::Transports::StdioTransport
   end
 end

data/lib/mcp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MCP
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end