mcp 0.1.0 → 0.3.0

data/lib/mcp/methods.rb

@@ -19,8 +19,20 @@ module MCP
     TOOLS_CALL = "tools/call"
     TOOLS_LIST = "tools/list"
 
+    ROOTS_LIST = "roots/list"
     SAMPLING_CREATE_MESSAGE = "sampling/createMessage"
 
+    # Notification methods
+    NOTIFICATIONS_INITIALIZED = "notifications/initialized"
+    NOTIFICATIONS_TOOLS_LIST_CHANGED = "notifications/tools/list_changed"
+    NOTIFICATIONS_PROMPTS_LIST_CHANGED = "notifications/prompts/list_changed"
+    NOTIFICATIONS_RESOURCES_LIST_CHANGED = "notifications/resources/list_changed"
+    NOTIFICATIONS_RESOURCES_UPDATED = "notifications/resources/updated"
+    NOTIFICATIONS_ROOTS_LIST_CHANGED = "notifications/roots/list_changed"
+    NOTIFICATIONS_MESSAGE = "notifications/message"
+    NOTIFICATIONS_PROGRESS = "notifications/progress"
+    NOTIFICATIONS_CANCELLED = "notifications/cancelled"
+
     class MissingRequiredCapabilityError < StandardError
       attr_reader :method
       attr_reader :capability
@@ -32,41 +44,51 @@ module MCP
       end
     end
 
-    extend self
-
-    def ensure_capability!(method, capabilities)
-      case method
-      when PROMPTS_GET, PROMPTS_LIST
-        unless capabilities[:prompts]
-          raise MissingRequiredCapabilityError.new(method, :prompts)
-        end
-      when RESOURCES_LIST, RESOURCES_TEMPLATES_LIST, RESOURCES_READ, RESOURCES_SUBSCRIBE, RESOURCES_UNSUBSCRIBE
-        unless capabilities[:resources]
-          raise MissingRequiredCapabilityError.new(method, :resources)
+    class << self
+      def ensure_capability!(method, capabilities)
+        case method
+        when PROMPTS_GET, PROMPTS_LIST
+          require_capability!(method, capabilities, :prompts)
+        when NOTIFICATIONS_PROMPTS_LIST_CHANGED
+          require_capability!(method, capabilities, :prompts)
+          require_capability!(method, capabilities, :prompts, :listChanged)
+        when RESOURCES_LIST, RESOURCES_TEMPLATES_LIST, RESOURCES_READ
+          require_capability!(method, capabilities, :resources)
+        when NOTIFICATIONS_RESOURCES_LIST_CHANGED
+          require_capability!(method, capabilities, :resources)
+          require_capability!(method, capabilities, :resources, :listChanged)
+        when RESOURCES_SUBSCRIBE, RESOURCES_UNSUBSCRIBE, NOTIFICATIONS_RESOURCES_UPDATED
+          require_capability!(method, capabilities, :resources)
+          require_capability!(method, capabilities, :resources, :subscribe)
+        when TOOLS_CALL, TOOLS_LIST
+          require_capability!(method, capabilities, :tools)
+        when NOTIFICATIONS_TOOLS_LIST_CHANGED
+          require_capability!(method, capabilities, :tools)
+          require_capability!(method, capabilities, :tools, :listChanged)
+        when LOGGING_SET_LEVEL, NOTIFICATIONS_MESSAGE
+          require_capability!(method, capabilities, :logging)
+        when COMPLETION_COMPLETE
+          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 INITIALIZE, PING, NOTIFICATIONS_INITIALIZED, NOTIFICATIONS_PROGRESS, NOTIFICATIONS_CANCELLED
+          # No specific capability required for initialize, ping, progress or cancelled
         end
+      end
 
-        if method == RESOURCES_SUBSCRIBE && !capabilities[:resources][:subscribe]
-          raise MissingRequiredCapabilityError.new(method, :resources_subscribe)
-        end
-      when TOOLS_CALL, TOOLS_LIST
-        unless capabilities[:tools]
-          raise MissingRequiredCapabilityError.new(method, :tools)
-        end
-      when SAMPLING_CREATE_MESSAGE
-        unless capabilities[:sampling]
-          raise MissingRequiredCapabilityError.new(method, :sampling)
-        end
-      when COMPLETION_COMPLETE
-        unless capabilities[:completions]
-          raise MissingRequiredCapabilityError.new(method, :completions)
-        end
-      when LOGGING_SET_LEVEL
-        # Logging is unsupported by the Server
-        unless capabilities[:logging]
-          raise MissingRequiredCapabilityError.new(method, :logging)
-        end
-      when INITIALIZE, PING
-        # No specific capability required for initialize or ping
+      private
+
+      def require_capability!(method, capabilities, *keys)
+        name = keys.join(".") # :resources, :subscribe -> "resources.subscribe"
+        has_capability = capabilities.dig(*keys)
+        return if has_capability
+
+        raise MissingRequiredCapabilityError.new(method, name)
       end
     end
   end

data/lib/mcp/prompt.rb

@@ -6,20 +6,22 @@ module MCP
     class << self
       NOT_SET = Object.new
 
+      attr_reader :title_value
       attr_reader :description_value
       attr_reader :arguments_value
 
-      def template(args, server_context:)
+      def template(args, server_context: nil)
         raise NotImplementedError, "Subclasses must implement template"
       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,12 +62,13 @@ 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:|
+          define_singleton_method(:template) do |args, server_context: nil|
             instance_exec(args, server_context:, &block)
           end
         end

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:, mime_type:)
+    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/capabilities.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module MCP
+  class Server
+    class Capabilities
+      def initialize(capabilities_hash = nil)
+        @completions = nil
+        @experimental = nil
+        @logging = nil
+        @prompts = nil
+        @resources = nil
+        @tools = nil
+
+        if capabilities_hash
+          support_completions if capabilities_hash.key?(:completions)
+          support_experimental(capabilities_hash[:experimental]) if capabilities_hash.key?(:experimental)
+          support_logging if capabilities_hash.key?(:logging)
+
+          if capabilities_hash.key?(:prompts)
+            support_prompts
+            prompts_config = capabilities_hash[:prompts] || {}
+            support_prompts_list_changed if prompts_config[:listChanged]
+          end
+
+          if capabilities_hash.key?(:resources)
+            support_resources
+            resources_config = capabilities_hash[:resources] || {}
+            support_resources_list_changed if resources_config[:listChanged]
+            support_resources_subscribe if resources_config[:subscribe]
+          end
+
+          if capabilities_hash.key?(:tools)
+            support_tools
+            tools_config = capabilities_hash[:tools] || {}
+            support_tools_list_changed if tools_config[:listChanged]
+          end
+        end
+      end
+
+      def support_completions
+        @completions ||= {}
+      end
+
+      def support_experimental(config = {})
+        @experimental = config || {}
+      end
+
+      def support_logging
+        @logging ||= {}
+      end
+
+      def support_prompts
+        @prompts ||= {}
+      end
+
+      def support_prompts_list_changed
+        support_prompts
+        @prompts[:listChanged] = true
+      end
+
+      def support_resources
+        @resources ||= {}
+      end
+
+      def support_resources_list_changed
+        support_resources
+        @resources[:listChanged] = true
+      end
+
+      def support_resources_subscribe
+        support_resources
+        @resources[:subscribe] = true
+      end
+
+      def support_tools
+        @tools ||= {}
+      end
+
+      def support_tools_list_changed
+        support_tools
+        @tools[:listChanged] = true
+      end
+
+      def to_h
+        {
+          completions: @completions,
+          experimental: @experimental,
+          logging: @logging,
+          prompts: @prompts,
+          resources: @resources,
+          tools: @tools,
+        }.compact
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "../../transport"
+require "json"
+
+module MCP
+  class Server
+    module Transports
+      class StdioTransport < Transport
+        STATUS_INTERRUPTED = Signal.list["INT"] + 128
+
+        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
+        rescue Interrupt
+          warn("\nExiting...")
+
+          exit(STATUS_INTERRUPTED)
+        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
+
+        def send_notification(method, params = nil)
+          notification = {
+            jsonrpc: "2.0",
+            method: method,
+          }
+          notification[:params] = params if params
+
+          send_response(notification)
+          true
+        rescue => e
+          MCP.configuration.exception_reporter.call(e, { error: "Failed to send notification" })
+          false
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,301 @@
+# 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(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
+              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)
+          elsif body["method"] == MCP::Methods::NOTIFICATIONS_INITIALIZED
+            handle_notification_initialized
+          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_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)
+            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