ruby-mcp-client 0.6.1 → 0.7.0

data/lib/mcp_client/http_transport_base.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require_relative 'json_rpc_common'
+
+module MCPClient
+  # Base module for HTTP-based JSON-RPC transports
+  # Contains common functionality shared between HTTP and Streamable HTTP transports
+  module HttpTransportBase
+    include JsonRpcCommon
+
+    # Generic JSON-RPC request: send method with params and return result
+    # @param method [String] JSON-RPC method name
+    # @param params [Hash] parameters for the request
+    # @return [Object] result from JSON-RPC response
+    # @raise [MCPClient::Errors::ConnectionError] if connection is not active
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    # @raise [MCPClient::Errors::TransportError] if response isn't valid JSON
+    # @raise [MCPClient::Errors::ToolCallError] for other errors during request execution
+    def rpc_request(method, params = {})
+      ensure_connected
+
+      with_retry do
+        request_id = @mutex.synchronize { @request_id += 1 }
+        request = build_jsonrpc_request(method, params, request_id)
+        send_jsonrpc_request(request)
+      end
+    end
+
+    # Send a JSON-RPC notification (no response expected)
+    # @param method [String] JSON-RPC method name
+    # @param params [Hash] parameters for the notification
+    # @return [void]
+    def rpc_notify(method, params = {})
+      ensure_connected
+
+      notif = build_jsonrpc_notification(method, params)
+
+      begin
+        send_http_request(notif)
+      rescue MCPClient::Errors::ServerError, MCPClient::Errors::ConnectionError, Faraday::ConnectionFailed => e
+        raise MCPClient::Errors::TransportError, "Failed to send notification: #{e.message}"
+      end
+    end
+
+    # Terminate the current session with the server
+    # Sends an HTTP DELETE request with the session ID to properly close the session
+    # @return [Boolean] true if termination was successful
+    # @raise [MCPClient::Errors::ConnectionError] if termination fails
+    def terminate_session
+      return true unless @session_id
+
+      conn = http_connection
+
+      begin
+        @logger.debug("Terminating session: #{@session_id}")
+        response = conn.delete(@endpoint) do |req|
+          # Apply base headers but prioritize session termination headers
+          @headers.each { |k, v| req.headers[k] = v }
+          req.headers['Mcp-Session-Id'] = @session_id
+        end
+
+        if response.success?
+          @logger.debug("Session terminated successfully: #{@session_id}")
+          @session_id = nil
+          true
+        else
+          @logger.warn("Session termination failed with HTTP #{response.status}")
+          @session_id = nil # Clear session ID even on HTTP error
+          false
+        end
+      rescue Faraday::Error => e
+        @logger.warn("Session termination request failed: #{e.message}")
+        # Clear session ID even if termination request failed
+        @session_id = nil
+        false
+      end
+    end
+
+    # Validate session ID format for security
+    # @param session_id [String] the session ID to validate
+    # @return [Boolean] true if session ID is valid
+    def valid_session_id?(session_id)
+      return false unless session_id.is_a?(String)
+      return false if session_id.empty?
+
+      # Session ID should be alphanumeric with optional hyphens and underscores
+      # Length should be reasonable (8-128 characters)
+      session_id.match?(/\A[a-zA-Z0-9\-_]{8,128}\z/)
+    end
+
+    # Validate the server's base URL for security
+    # @param url [String] the URL to validate
+    # @return [Boolean] true if URL is considered safe
+    def valid_server_url?(url)
+      return false unless url.is_a?(String)
+
+      uri = URI.parse(url)
+
+      # Only allow HTTP and HTTPS protocols
+      return false unless %w[http https].include?(uri.scheme)
+
+      # Must have a host
+      return false if uri.host.nil? || uri.host.empty?
+
+      # Don't allow localhost binding to all interfaces in production
+      if uri.host == '0.0.0.0'
+        @logger.warn('Server URL uses 0.0.0.0 which may be insecure. Consider using 127.0.0.1 for localhost.')
+      end
+
+      true
+    rescue URI::InvalidURIError
+      false
+    end
+
+    private
+
+    # Generate initialization parameters for HTTP MCP protocol
+    # @return [Hash] the initialization parameters
+    def initialization_params
+      {
+        'protocolVersion' => MCPClient::HTTP_PROTOCOL_VERSION,
+        'capabilities' => {},
+        'clientInfo' => { 'name' => 'ruby-mcp-client', 'version' => MCPClient::VERSION }
+      }
+    end
+
+    # Perform JSON-RPC initialize handshake with the MCP server
+    # @return [void]
+    # @raise [MCPClient::Errors::ConnectionError] if initialization fails
+    def perform_initialize
+      request_id = @mutex.synchronize { @request_id += 1 }
+      json_rpc_request = build_jsonrpc_request('initialize', initialization_params, request_id)
+      @logger.debug("Performing initialize RPC: #{json_rpc_request}")
+
+      result = send_jsonrpc_request(json_rpc_request)
+      return unless result.is_a?(Hash)
+
+      @server_info = result['serverInfo']
+      @capabilities = result['capabilities']
+    end
+
+    # Send a JSON-RPC request to the server and wait for result
+    # @param request [Hash] the JSON-RPC request
+    # @return [Hash] the result of the request
+    # @raise [MCPClient::Errors::ConnectionError] if connection fails
+    # @raise [MCPClient::Errors::TransportError] if response isn't valid JSON
+    # @raise [MCPClient::Errors::ToolCallError] for other errors during request execution
+    def send_jsonrpc_request(request)
+      @logger.debug("Sending JSON-RPC request: #{request.to_json}")
+
+      begin
+        response = send_http_request(request)
+        parse_response(response)
+      rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+        raise
+      rescue JSON::ParserError => e
+        raise MCPClient::Errors::TransportError, "Invalid JSON response from server: #{e.message}"
+      rescue Errno::ECONNREFUSED => e
+        raise MCPClient::Errors::ConnectionError, "Server connection lost: #{e.message}"
+      rescue StandardError => e
+        method_name = request['method']
+        raise MCPClient::Errors::ToolCallError, "Error executing request '#{method_name}': #{e.message}"
+      end
+    end
+
+    # Send an HTTP request to the server
+    # @param request [Hash] the JSON-RPC request
+    # @return [Faraday::Response] the HTTP response
+    # @raise [MCPClient::Errors::ConnectionError] if connection fails
+    def send_http_request(request)
+      conn = http_connection
+
+      begin
+        response = conn.post(@endpoint) do |req|
+          # Apply all headers including custom ones
+          @headers.each { |k, v| req.headers[k] = v }
+          req.body = request.to_json
+        end
+
+        handle_http_error_response(response) unless response.success?
+
+        log_response(response)
+        response
+      rescue Faraday::UnauthorizedError, Faraday::ForbiddenError => e
+        error_status = e.response ? e.response[:status] : 'unknown'
+        raise MCPClient::Errors::ConnectionError, "Authorization failed: HTTP #{error_status}"
+      rescue Faraday::ConnectionFailed => e
+        raise MCPClient::Errors::ConnectionError, "Server connection lost: #{e.message}"
+      rescue Faraday::Error => e
+        raise MCPClient::Errors::TransportError, "HTTP request failed: #{e.message}"
+      end
+    end
+
+    # Handle HTTP error responses
+    # @param response [Faraday::Response] the error response
+    # @raise [MCPClient::Errors::ConnectionError] for auth errors
+    # @raise [MCPClient::Errors::ServerError] for server errors
+    def handle_http_error_response(response)
+      reason = response.respond_to?(:reason_phrase) ? response.reason_phrase : ''
+      reason = reason.to_s.strip
+      reason_text = reason.empty? ? '' : " #{reason}"
+
+      case response.status
+      when 401, 403
+        raise MCPClient::Errors::ConnectionError, "Authorization failed: HTTP #{response.status}"
+      when 400..499
+        raise MCPClient::Errors::ServerError, "Client error: HTTP #{response.status}#{reason_text}"
+      when 500..599
+        raise MCPClient::Errors::ServerError, "Server error: HTTP #{response.status}#{reason_text}"
+      else
+        raise MCPClient::Errors::ServerError, "HTTP error: #{response.status}#{reason_text}"
+      end
+    end
+
+    # Get or create HTTP connection
+    # @return [Faraday::Connection] the HTTP connection
+    def http_connection
+      @http_connection ||= create_http_connection
+    end
+
+    # Create a Faraday connection for HTTP requests
+    # @return [Faraday::Connection] the configured connection
+    def create_http_connection
+      Faraday.new(url: @base_url) do |f|
+        f.request :retry, max: @max_retries, interval: @retry_backoff, backoff_factor: 2
+        f.options.open_timeout = @read_timeout
+        f.options.timeout = @read_timeout
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    # Log HTTP response (to be overridden by specific transports)
+    # @param response [Faraday::Response] the HTTP response
+    def log_response(response)
+      @logger.debug("Received HTTP response: #{response.status} #{response.body}")
+    end
+
+    # Parse HTTP response (to be implemented by specific transports)
+    # @param response [Faraday::Response] the HTTP response
+    # @return [Hash] the parsed result
+    # @raise [NotImplementedError] if not implemented by concrete transport
+    def parse_response(response)
+      raise NotImplementedError, 'Subclass must implement parse_response'
+    end
+  end
+end

data/lib/mcp_client/json_rpc_common.rb

@@ -40,10 +40,10 @@ module MCPClient
     # @return [Hash] the JSON-RPC request object
     def build_jsonrpc_request(method, params, id)
       {
-        jsonrpc: '2.0',
-        id: id,
-        method: method,
-        params: params
+        'jsonrpc' => '2.0',
+        'id' => id,
+        'method' => method,
+        'params' => params
       }
     end
 
@@ -53,9 +53,9 @@ module MCPClient
     # @return [Hash] the JSON-RPC notification object
     def build_jsonrpc_notification(method, params)
       {
-        jsonrpc: '2.0',
-        method: method,
-        params: params
+        'jsonrpc' => '2.0',
+        'method' => method,
+        'params' => params
       }
     end
 
@@ -74,9 +74,7 @@ module MCPClient
     # @return [Object] the result field from the response
     # @raise [MCPClient::Errors::ServerError] if the response contains an error
     def process_jsonrpc_response(response)
-      if (err = response['error'])
-        raise MCPClient::Errors::ServerError, err['message']
-      end
+      raise MCPClient::Errors::ServerError, response['error']['message'] if response['error']
 
       response['result']
     end

data/lib/mcp_client/server_factory.rb

@@ -15,6 +15,10 @@ module MCPClient
         create_stdio_server(config, logger_to_use)
       when 'sse'
         create_sse_server(config, logger_to_use)
+      when 'http'
+        create_http_server(config, logger_to_use)
+      when 'streamable_http'
+        create_streamable_http_server(config, logger_to_use)
       else
         raise ArgumentError, "Unknown server type: #{config[:type]}"
       end
@@ -57,6 +61,44 @@ module MCPClient
       )
     end
 
+    # Create an HTTP-based server
+    # @param config [Hash] server configuration
+    # @param logger [Logger, nil] logger to use
+    # @return [MCPClient::ServerHTTP] server instance
+    def self.create_http_server(config, logger)
+      # Handle both :url and :base_url (config parser uses :url)
+      base_url = config[:base_url] || config[:url]
+      MCPClient::ServerHTTP.new(
+        base_url: base_url,
+        endpoint: config[:endpoint] || '/rpc',
+        headers: config[:headers] || {},
+        read_timeout: config[:read_timeout] || 30,
+        retries: config[:retries] || 3,
+        retry_backoff: config[:retry_backoff] || 1,
+        name: config[:name],
+        logger: logger
+      )
+    end
+
+    # Create a Streamable HTTP-based server
+    # @param config [Hash] server configuration
+    # @param logger [Logger, nil] logger to use
+    # @return [MCPClient::ServerStreamableHTTP] server instance
+    def self.create_streamable_http_server(config, logger)
+      # Handle both :url and :base_url (config parser uses :url)
+      base_url = config[:base_url] || config[:url]
+      MCPClient::ServerStreamableHTTP.new(
+        base_url: base_url,
+        endpoint: config[:endpoint] || '/rpc',
+        headers: config[:headers] || {},
+        read_timeout: config[:read_timeout] || 30,
+        retries: config[:retries] || 3,
+        retry_backoff: config[:retry_backoff] || 1,
+        name: config[:name],
+        logger: logger
+      )
+    end
+
     # Prepare command by combining command and args
     # @param config [Hash] server configuration
     # @return [String, Array] prepared command

data/lib/mcp_client/server_http/json_rpc_transport.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative '../http_transport_base'
+
+module MCPClient
+  class ServerHTTP
+    # JSON-RPC request/notification plumbing for HTTP transport
+    module JsonRpcTransport
+      include HttpTransportBase
+
+      private
+
+      # Parse an HTTP JSON-RPC response
+      # @param response [Faraday::Response] the HTTP response
+      # @return [Hash] the parsed result
+      # @raise [MCPClient::Errors::TransportError] if parsing fails
+      # @raise [MCPClient::Errors::ServerError] if the response contains an error
+      def parse_response(response)
+        body = response.body.strip
+        data = JSON.parse(body)
+        process_jsonrpc_response(data)
+      rescue JSON::ParserError => e
+        raise MCPClient::Errors::TransportError, "Invalid JSON response from server: #{e.message}"
+      end
+    end
+  end
+end

data/lib/mcp_client/server_http.rb

@@ -0,0 +1,329 @@
+# frozen_string_literal: true
+
+require 'uri'
+require 'json'
+require 'monitor'
+require 'logger'
+require 'faraday'
+require 'faraday/retry'
+
+module MCPClient
+  # Implementation of MCP server that communicates via HTTP requests/responses
+  # Useful for communicating with MCP servers that support HTTP-based transport
+  # without Server-Sent Events streaming
+  class ServerHTTP < ServerBase
+    require_relative 'server_http/json_rpc_transport'
+
+    include JsonRpcTransport
+
+    # Default values for connection settings
+    DEFAULT_READ_TIMEOUT = 30
+    DEFAULT_MAX_RETRIES = 3
+
+    # @!attribute [r] base_url
+    #   @return [String] The base URL of the MCP server
+    # @!attribute [r] endpoint
+    #   @return [String] The JSON-RPC endpoint path
+    # @!attribute [r] tools
+    #   @return [Array<MCPClient::Tool>, nil] List of available tools (nil if not fetched yet)
+    attr_reader :base_url, :endpoint, :tools
+
+    # Server information from initialize response
+    # @return [Hash, nil] Server information
+    attr_reader :server_info
+
+    # Server capabilities from initialize response
+    # @return [Hash, nil] Server capabilities
+    attr_reader :capabilities
+
+    # @param base_url [String] The base URL of the MCP server
+    # @param endpoint [String] The JSON-RPC endpoint path (default: '/rpc')
+    # @param headers [Hash] Additional headers to include in requests
+    # @param read_timeout [Integer] Read timeout in seconds (default: 30)
+    # @param retries [Integer] number of retry attempts on transient errors (default: 3)
+    # @param retry_backoff [Numeric] base delay in seconds for exponential backoff (default: 1)
+    # @param name [String, nil] optional name for this server
+    # @param logger [Logger, nil] optional logger
+    def initialize(base_url:, endpoint: '/rpc', headers: {}, read_timeout: DEFAULT_READ_TIMEOUT,
+                   retries: DEFAULT_MAX_RETRIES, retry_backoff: 1, name: nil, logger: nil)
+      super(name: name)
+      @logger = logger || Logger.new($stdout, level: Logger::WARN)
+      @logger.progname = self.class.name
+      @logger.formatter = proc { |severity, _datetime, progname, msg| "#{severity} [#{progname}] #{msg}\n" }
+
+      @max_retries = retries
+      @retry_backoff = retry_backoff
+
+      # Validate and normalize base_url
+      raise ArgumentError, "Invalid or insecure server URL: #{base_url}" unless valid_server_url?(base_url)
+
+      # Normalize base_url and handle cases where full endpoint is provided in base_url
+      uri = URI.parse(base_url.chomp('/'))
+
+      # Helper to build base URL without default ports
+      build_base_url = lambda do |parsed_uri|
+        port_part = if parsed_uri.port &&
+                       !((parsed_uri.scheme == 'http' && parsed_uri.port == 80) ||
+                         (parsed_uri.scheme == 'https' && parsed_uri.port == 443))
+                      ":#{parsed_uri.port}"
+                    else
+                      ''
+                    end
+        "#{parsed_uri.scheme}://#{parsed_uri.host}#{port_part}"
+      end
+
+      @base_url = build_base_url.call(uri)
+      @endpoint = if uri.path && !uri.path.empty? && uri.path != '/' && endpoint == '/rpc'
+                    # If base_url contains a path and we're using default endpoint,
+                    # treat the path as the endpoint and use the base URL without path
+                    uri.path
+                  else
+                    # Standard case: base_url is just scheme://host:port, endpoint is separate
+                    endpoint
+                  end
+
+      # Set up headers for HTTP requests
+      @headers = headers.merge({
+                                 'Content-Type' => 'application/json',
+                                 'Accept' => 'application/json',
+                                 'User-Agent' => "ruby-mcp-client/#{MCPClient::VERSION}"
+                               })
+
+      @read_timeout = read_timeout
+      @tools = nil
+      @tools_data = nil
+      @request_id = 0
+      @mutex = Monitor.new
+      @connection_established = false
+      @initialized = false
+      @http_conn = nil
+      @session_id = nil
+    end
+
+    # Connect to the MCP server over HTTP
+    # @return [Boolean] true if connection was successful
+    # @raise [MCPClient::Errors::ConnectionError] if connection fails
+    def connect
+      return true if @mutex.synchronize { @connection_established }
+
+      begin
+        @mutex.synchronize do
+          @connection_established = false
+          @initialized = false
+        end
+
+        # Test connectivity with a simple HTTP request
+        test_connection
+
+        # Perform MCP initialization handshake
+        perform_initialize
+
+        @mutex.synchronize do
+          @connection_established = true
+          @initialized = true
+        end
+
+        true
+      rescue MCPClient::Errors::ConnectionError => e
+        cleanup
+        raise e
+      rescue StandardError => e
+        cleanup
+        raise MCPClient::Errors::ConnectionError, "Failed to connect to MCP server at #{@base_url}: #{e.message}"
+      end
+    end
+
+    # List all tools available from the MCP server
+    # @return [Array<MCPClient::Tool>] list of available tools
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    # @raise [MCPClient::Errors::TransportError] if response isn't valid JSON
+    # @raise [MCPClient::Errors::ToolCallError] for other errors during tool listing
+    def list_tools
+      @mutex.synchronize do
+        return @tools if @tools
+      end
+
+      begin
+        ensure_connected
+
+        tools_data = request_tools_list
+        @mutex.synchronize do
+          @tools = tools_data.map do |tool_data|
+            MCPClient::Tool.from_json(tool_data, server: self)
+          end
+        end
+
+        @mutex.synchronize { @tools }
+      rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+        # Re-raise these errors directly
+        raise
+      rescue StandardError => e
+        raise MCPClient::Errors::ToolCallError, "Error listing tools: #{e.message}"
+      end
+    end
+
+    # Call a tool with the given parameters
+    # @param tool_name [String] the name of the tool to call
+    # @param parameters [Hash] the parameters to pass to the tool
+    # @return [Object] the result of the tool invocation
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    # @raise [MCPClient::Errors::TransportError] if response isn't valid JSON
+    # @raise [MCPClient::Errors::ToolCallError] for other errors during tool execution
+    # @raise [MCPClient::Errors::ConnectionError] if server is disconnected
+    def call_tool(tool_name, parameters)
+      rpc_request('tools/call', {
+                    name: tool_name,
+                    arguments: parameters
+                  })
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
+      # Re-raise connection/transport errors directly to match test expectations
+      raise
+    rescue StandardError => e
+      # For all other errors, wrap in ToolCallError
+      raise MCPClient::Errors::ToolCallError, "Error calling tool '#{tool_name}': #{e.message}"
+    end
+
+    # Override send_http_request to handle session headers for MCP protocol
+    def send_http_request(request)
+      conn = http_connection
+
+      begin
+        response = conn.post(@endpoint) do |req|
+          # Apply all headers including custom ones
+          @headers.each { |k, v| req.headers[k] = v }
+
+          # Add session header if we have one (for non-initialize requests)
+          if @session_id && request['method'] != 'initialize'
+            req.headers['Mcp-Session-Id'] = @session_id
+            @logger.debug("Adding session header: Mcp-Session-Id: #{@session_id}")
+          end
+
+          req.body = request.to_json
+        end
+
+        handle_http_error_response(response) unless response.success?
+
+        # Capture session ID from initialize response with validation
+        if request['method'] == 'initialize' && response.success?
+          session_id = response.headers['mcp-session-id'] || response.headers['Mcp-Session-Id']
+          if session_id
+            if valid_session_id?(session_id)
+              @session_id = session_id
+              @logger.debug("Captured session ID: #{@session_id}")
+            else
+              @logger.warn("Invalid session ID format received: #{session_id.inspect}")
+            end
+          else
+            @logger.warn('No session ID found in initialize response headers')
+          end
+        end
+
+        log_response(response)
+        response
+      rescue Faraday::UnauthorizedError, Faraday::ForbiddenError => e
+        error_status = e.response ? e.response[:status] : 'unknown'
+        raise MCPClient::Errors::ConnectionError, "Authorization failed: HTTP #{error_status}"
+      rescue Faraday::ConnectionFailed => e
+        raise MCPClient::Errors::ConnectionError, "Server connection lost: #{e.message}"
+      rescue Faraday::Error => e
+        raise MCPClient::Errors::TransportError, "HTTP request failed: #{e.message}"
+      end
+    end
+
+    # Stream tool call (default implementation returns single-value stream)
+    # @param tool_name [String] the name of the tool to call
+    # @param parameters [Hash] the parameters to pass to the tool
+    # @return [Enumerator] stream of results
+    def call_tool_streaming(tool_name, parameters)
+      Enumerator.new do |yielder|
+        yielder << call_tool(tool_name, parameters)
+      end
+    end
+
+    # Terminate the current session (if any)
+    # @return [Boolean] true if termination was successful or no session exists
+    def terminate_session
+      @mutex.synchronize do
+        return true unless @session_id
+
+        super
+      end
+    end
+
+    # Clean up the server connection
+    # Properly closes HTTP connections and clears cached state
+    def cleanup
+      @mutex.synchronize do
+        # Attempt to terminate session before cleanup
+        terminate_session if @session_id
+
+        @connection_established = false
+        @initialized = false
+
+        @logger.debug('Cleaning up HTTP connection')
+
+        # Close HTTP connection if it exists
+        @http_conn = nil
+        @session_id = nil
+
+        @tools = nil
+        @tools_data = nil
+      end
+    end
+
+    private
+
+    # Test basic connectivity to the HTTP endpoint
+    # @return [void]
+    # @raise [MCPClient::Errors::ConnectionError] if connection test fails
+    def test_connection
+      create_http_connection
+
+      # Simple connectivity test - we'll use the actual initialize call
+      # since there's no standard HTTP health check endpoint
+    rescue Faraday::ConnectionFailed => e
+      raise MCPClient::Errors::ConnectionError, "Cannot connect to server at #{@base_url}: #{e.message}"
+    rescue Faraday::UnauthorizedError, Faraday::ForbiddenError => e
+      error_status = e.response ? e.response[:status] : 'unknown'
+      raise MCPClient::Errors::ConnectionError, "Authorization failed: HTTP #{error_status}"
+    rescue Faraday::Error => e
+      raise MCPClient::Errors::ConnectionError, "HTTP connection error: #{e.message}"
+    end
+
+    # Ensure connection is established
+    # @return [void]
+    # @raise [MCPClient::Errors::ConnectionError] if connection is not established
+    def ensure_connected
+      return if @mutex.synchronize { @connection_established && @initialized }
+
+      @logger.debug('Connection not active, attempting to reconnect before request')
+      cleanup
+      connect
+    end
+
+    # Request the tools list using JSON-RPC
+    # @return [Array<Hash>] the tools data
+    # @raise [MCPClient::Errors::ToolCallError] if tools list retrieval fails
+    def request_tools_list
+      @mutex.synchronize do
+        return @tools_data if @tools_data
+      end
+
+      result = rpc_request('tools/list')
+
+      if result && result['tools']
+        @mutex.synchronize do
+          @tools_data = result['tools']
+        end
+        return @mutex.synchronize { @tools_data.dup }
+      elsif result
+        @mutex.synchronize do
+          @tools_data = result
+        end
+        return @mutex.synchronize { @tools_data.dup }
+      end
+
+      raise MCPClient::Errors::ToolCallError, 'Failed to get tools list from JSON-RPC request'
+    end
+  end
+end