Merge pull request #99 from patvice/rpc-message-refactor

RPC Message Refactor + JSON RPC Error Codes

Author: patvice

.rubocop.yml

@@ -37,25 +37,27 @@ Naming/AccessorMethodName:
 Layout/LineLength:
   Max: 120
 
-Metrics/MethodLength:
-  Max: 35
-
 Metrics/AbcSize:
   Enabled: false
 
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+
 Metrics/ClassLength:
   Enabled: false
 
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-Metrics/PerceivedComplexity:
-  Enabled: false
+Metrics/MethodLength:
+  Max: 35
 
-Metrics/BlockLength:
-  Exclude:
-    - 'spec/**/*'
+Metrics/ModuleLength:
+  Enabled: false
 
+Metrics/PerceivedComplexity:
+  Enabled: false
 
 RSpec/DescribedClass:
   Enabled: false

Gemfile

@@ -14,6 +14,7 @@ group :development do
   gem "bundler", ">= 2.0"
   gem "debug"
   gem "dotenv", ">= 3.0"
+  gem "json_schemer"
   gem "rake", ">= 13.0"
   gem "rdoc", "~> 6.15"
   gem "reline"

lib/ruby_llm/mcp/adapters/base_adapter.rb

@@ -38,7 +38,6 @@ def initialize(client, transport_type:, config: {})
           @config = config
         end
 
-        # Instance methods
         def supports?(feature)
           self.class.support?(feature)
         end
@@ -54,7 +53,6 @@ def validate_transport!(transport_type)
           end
         end
 
-        # Lifecycle methods
         def start
           raise NotImplementedError, "#{self.class.name} must implement #start"
         end
@@ -75,7 +73,6 @@ def ping
           raise NotImplementedError, "#{self.class.name} must implement #ping"
         end
 
-        # Capabilities
         def capabilities
           raise NotImplementedError, "#{self.class.name} must implement #capabilities"
         end
@@ -84,7 +81,6 @@ def client_capabilities
           raise NotImplementedError, "#{self.class.name} must implement #client_capabilities"
         end
 
-        # Core MCP methods - Tools
         def tool_list(cursor: nil)
           raise NotImplementedError, "#{self.class.name} must implement #tool_list"
         end
@@ -93,7 +89,6 @@ def execute_tool(name:, parameters:)
           raise NotImplementedError, "#{self.class.name} must implement #execute_tool"
         end
 
-        # Core MCP methods - Resources
         def resource_list(cursor: nil)
           raise NotImplementedError, "#{self.class.name} must implement #resource_list"
         end
@@ -102,7 +97,6 @@ def resource_read(uri:)
           raise NotImplementedError, "#{self.class.name} must implement #resource_read"
         end
 
-        # Core MCP methods - Prompts
         def prompt_list(cursor: nil)
           raise NotImplementedError, "#{self.class.name} must implement #prompt_list"
         end
@@ -111,12 +105,10 @@ def execute_prompt(name:, arguments:)
           raise NotImplementedError, "#{self.class.name} must implement #execute_prompt"
         end
 
-        # Optional features - Resource Templates
         def resource_template_list(cursor: nil) # rubocop:disable Lint/UnusedMethodArgument
           raise_unsupported_feature(:resource_templates)
         end
 
-        # Optional features - Completions
         def completion_resource(uri:, argument:, value:, context: nil) # rubocop:disable Lint/UnusedMethodArgument
           raise_unsupported_feature(:completions)
         end
@@ -125,17 +117,14 @@ def completion_prompt(name:, argument:, value:, context: nil) # rubocop:disable
           raise_unsupported_feature(:completions)
         end
 
-        # Optional features - Logging
         def set_logging(level:) # rubocop:disable Lint/UnusedMethodArgument
           raise_unsupported_feature(:logging)
         end
 
-        # Optional features - Subscriptions
         def resources_subscribe(uri:) # rubocop:disable Lint/UnusedMethodArgument
           raise_unsupported_feature(:subscriptions)
         end
 
-        # Optional features - Notifications
         def initialize_notification
           raise_unsupported_feature(:notifications)
         end
@@ -148,7 +137,6 @@ def roots_list_change_notification
           raise_unsupported_feature(:notifications)
         end
 
-        # Optional features - Responses
         def ping_response(id:) # rubocop:disable Lint/UnusedMethodArgument
           raise_unsupported_feature(:responses)
         end
@@ -169,7 +157,6 @@ def elicitation_response(id:, elicitation:) # rubocop:disable Lint/UnusedMethodA
           raise_unsupported_feature(:elicitation)
         end
 
-        # Helper for resource registration
         def register_resource(_resource)
           raise_unsupported_feature(:resource_registration)
         end

lib/ruby_llm/mcp/adapters/mcp_sdk_adapter.rb

@@ -33,16 +33,12 @@ def start
           return if @mcp_client
 
           transport = build_transport
-
-          # Explicitly start the transport BEFORE creating the MCP client
-          # This ensures the stdio process is running before the client tries to use it
           transport.start if transport.respond_to?(:start)
 
           @mcp_client = ::MCP::Client.new(transport: transport)
         end
 
         def stop
-          # Close the transport if it has a close method
           if @mcp_client && @mcp_client.transport.respond_to?(:close)
             @mcp_client.transport.close
           end
@@ -59,7 +55,6 @@ def alive?
         end
 
         def ping # rubocop:disable Naming/PredicateMethod
-          # Auto-start if not started
           ensure_started
           alive?
         end
@@ -107,33 +102,28 @@ def resource_read(uri:)
         end
 
         def prompt_list(cursor: nil) # rubocop:disable Lint/UnusedMethodArgument
-          # The MCP gem does not support prompts
           []
         end
 
         def execute_prompt(name:, arguments:)
-          # The MCP gem does not support prompts
           raise NotImplementedError, "Prompts are not supported by the MCP SDK (gem 'mcp')"
         end
 
         def resource_template_list(cursor: nil) # rubocop:disable Lint/UnusedMethodArgument
-          # The MCP gem does not support resource templates
           []
         end
 
-        # Notifications
         def cancelled_notification(reason:, request_id:)
           return unless @mcp_client&.transport.respond_to?(:native_transport)
 
           native_transport = @mcp_client.transport.native_transport
           return unless native_transport
 
-          # Use the Native::Notifications::Cancelled class directly
-          RubyLLM::MCP::Native::Notifications::Cancelled.new(
-            native_transport,
-            reason: reason,
-            request_id: request_id
-          ).call
+          body = RubyLLM::MCP::Native::Messages::Notifications.cancelled(
+            request_id: request_id,
+            reason: reason
+          )
+          native_transport.request(body, wait_for_response: false)
         end
 
         # These methods remain as NotImplementedError from base class:
@@ -198,7 +188,6 @@ def build_transport
               request_timeout: @config[:request_timeout] || 10_000
             )
           when :streamable, :streamable_http
-            # Prepare OAuth provider if OAuth config is present
             config_copy = @config.dup
             oauth_provider = Auth::TransportOauthHelper.create_oauth_provider(config_copy) if Auth::TransportOauthHelper.oauth_config_present?(config_copy)
 
@@ -233,7 +222,6 @@ def transform_tool(tool)
         end
 
         def transform_resource(resource)
-          # MCP gem returns resources as hashes, not objects
           {
             "name" => resource["name"],
             "uri" => resource["uri"],
@@ -253,12 +241,10 @@ def transform_tool_result(result)
                       [{ "type" => "text", "text" => result.to_s }]
                     end
 
-          # Extract isError flag if present
           is_error = if result.is_a?(Hash) && result["result"]
                        result["result"]["isError"]
                      end
 
-          # Result expects response["result"] to contain the data
           result_data = { "content" => content }
           result_data["isError"] = is_error unless is_error.nil?
 
@@ -279,14 +265,12 @@ def transform_content_item(item)
         end
 
         def transform_resource_content(result)
-          # The MCP gem returns an array of content hashes
           contents = if result.is_a?(Array)
                        result.map { |r| transform_single_resource_content(r) }
                      else
                        [transform_single_resource_content(result)]
                      end
 
-          # Result expects response["result"] to contain the data
           Result.new({
                        "result" => {
                          "contents" => contents
@@ -295,7 +279,6 @@ def transform_resource_content(result)
         end
 
         def transform_single_resource_content(result)
-          # MCP gem returns resource contents as hashes, not objects
           {
             "uri" => result["uri"],
             "mimeType" => result["mimeType"],

lib/ruby_llm/mcp/adapters/mcp_transports/sse.rb

@@ -21,12 +21,10 @@ def initialize(url:, headers: {}, version: :http2, request_timeout: 10_000)
       )
     end
 
-    # Start the SSE connection
     def start
       @native_transport.start
     end
 
-    # Close the SSE connection
     def close
       @native_transport.close
     end
@@ -37,14 +35,13 @@ def close
     # @param request [Hash] A JSON-RPC request object
     # @return [Hash] A JSON-RPC response object
     def send_request(request:)
-      # Ensure transport is started
       start unless @native_transport.alive?
 
-      # The native transport expects the body without "jsonrpc" key added yet
-      # and will add IDs automatically
-      result = @native_transport.request(request, add_id: true, wait_for_response: true)
+      unless request["id"] || request[:id]
+        request["id"] = SecureRandom.uuid
+      end
+      result = @native_transport.request(request, wait_for_response: true)
 
-      # Convert Result object to hash expected by MCP::Client
       if result.is_a?(RubyLLM::MCP::Result)
         result.response
       else

lib/ruby_llm/mcp/adapters/mcp_transports/stdio.rb

@@ -18,16 +18,13 @@ def initialize(command:, args: [], env: {}, request_timeout: 10_000)
         request_timeout: request_timeout
       )
 
-      # Set transport reference so coordinator can send notifications
       @coordinator.transport = @native_transport
     end
 
-    # Start the stdio process
     def start
       @native_transport.start
     end
 
-    # Close the stdio process
     def close
       @native_transport.close
     end
@@ -38,14 +35,13 @@ def close
     # @param request [Hash] A JSON-RPC request object
     # @return [Hash] A JSON-RPC response object
     def send_request(request:)
-      # Ensure transport is started
       start unless @native_transport.alive?
 
-      # The native transport expects the body without "jsonrpc" key added yet
-      # and will add IDs automatically
-      result = @native_transport.request(request, add_id: false, wait_for_response: true)
+      unless request["id"] || request[:id]
+        request["id"] = SecureRandom.uuid
+      end
+      result = @native_transport.request(request, wait_for_response: true)
 
-      # Convert Result object to hash expected by MCP::Client
       if result.is_a?(RubyLLM::MCP::Result)
         result.response
       else

lib/ruby_llm/mcp/adapters/mcp_transports/streamable_http.rb

@@ -24,17 +24,13 @@ def initialize(url:, headers: {}, version: :http2, request_timeout: 10_000, # ru
         session_id: session_id
       )
 
-      # Set the transport reference on the coordinator so it can send requests
       @coordinator.transport = @native_transport
     end
 
-    # Start the streamable HTTP connection
-    # This only initializes the transport layer, not the MCP protocol
     def start
       @native_transport.start
     end
 
-    # Close the streamable HTTP connection
     def close
       @initialized = false
       @native_transport.close
@@ -52,11 +48,11 @@ def send_request(request:)
         perform_initialization
       end
 
-      # Pass the request through to native transport
-      # add_id: true because MCP SDK provides requests without IDs
-      result = @native_transport.request(request, add_id: true, wait_for_response: true)
+      unless request["id"] || request[:id]
+        request["id"] = SecureRandom.uuid
+      end
+      result = @native_transport.request(request, wait_for_response: true)
 
-      # Convert Result object to hash expected by MCP::Client
       if result.is_a?(RubyLLM::MCP::Result)
         result.response
       else
@@ -68,8 +64,11 @@ def send_request(request:)
 
     def perform_initialization
       # Send initialization request
-      init_request = RubyLLM::MCP::Native::Requests::Initialization.new(@coordinator).initialize_body
-      result = @native_transport.request(init_request, add_id: true, wait_for_response: true)
+      init_request = RubyLLM::MCP::Native::Messages::Requests.initialize(
+        protocol_version: @coordinator.protocol_version,
+        capabilities: @coordinator.client_capabilities
+      )
+      result = @native_transport.request(init_request, wait_for_response: true)
 
       if result.is_a?(RubyLLM::MCP::Result) && result.error?
         raise RubyLLM::MCP::Errors::TransportError.new(
@@ -78,11 +77,8 @@ def perform_initialization
         )
       end
 
-      initialized_notification = {
-        "jsonrpc" => "2.0",
-        "method" => "notifications/initialized"
-      }
-      @native_transport.request(initialized_notification, add_id: false, wait_for_response: false)
+      initialized_notification = RubyLLM::MCP::Native::Messages::Notifications.initialized
+      @native_transport.request(initialized_notification, wait_for_response: false)
 
       @initialized = true
     end