mcp 0.1.0 → 0.2.0

data/examples/streamable_http_server.rb

@@ -0,0 +1,172 @@
+# 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 "=== 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 ""
+
+# Start the server
+Rackup::Handler.get("puma").run(rack_app, Port: 9393, Host: "localhost")

data/lib/mcp/configuration.rb

@@ -4,12 +4,18 @@ module MCP
   class Configuration
     DEFAULT_PROTOCOL_VERSION = "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
+      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 +42,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 +66,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
 

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

@@ -9,7 +9,7 @@ module MCP
       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
 
@@ -57,7 +57,7 @@ module MCP
           prompt_name name
           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

@@ -5,7 +5,7 @@ module MCP
   class Resource
     attr_reader :uri, :name, :description, :mime_type
 
-    def initialize(uri:, name:, description:, mime_type:)
+    def initialize(uri:, name:, description: nil, mime_type: nil)
       @uri = uri
       @name = name
       @description = description

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