ruby-mcp-client 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0fd821eaf2b01a8628e7d54f2b39826b3d980d9e0d183ac0d81d5fb2ae135a36
-  data.tar.gz: 0d2afee24c1ebbb49f597056b9257546256e3152a4d789b7bc2789b3afc40a4f
+  metadata.gz: 233c83227145cb76167e75784b7eaecef56828743f65f6256c84062bb2290b1e
+  data.tar.gz: 4fb49b0cc82f5bd2b07d15ec200da4f9dced0fce52ddfacd4860a5a689152328
 SHA512:
-  metadata.gz: b21d59cb475b4202442658dd81b3ee394f317b767fb0a1bacba3c575dc96ac4004a0849a4fc59b2d7481c75ae55181cca21f11a5ebbe2d15179eeb2a30aba242
-  data.tar.gz: 6a06a38dd0066331efcd1ec3a1eb5d6178dd12091a7f217199a314c891aef4b0100d3d7da9d12e3f69ac01da42d3eee60135f68ac43bf79cebf14f9fd43308e4
+  metadata.gz: bdd2b7223f25e4e8516f9bad648854a8e935b823d269762d769a545571960041041082f861a85e559a637e00bb9357541548bd87155bbe9df490c501fb755ade
+  data.tar.gz: 3aef9c1fd10b846e46cc183c072443946a5aa39bfae43245949204e15e89a132df676af927cdabd4cae9c65e4052d220d4012bf0dadaffeb988cddf2a5ab7cfc

data/README.md

@@ -29,7 +29,7 @@ MCP enables AI assistants and other services to discover and invoke external too
 via different transport mechanisms:
 
 - **Standard I/O**: Local processes implementing the MCP protocol
-- **Server-Sent Events (SSE)**: Remote MCP servers over HTTP
+- **Server-Sent Events (SSE)**: Remote MCP servers over HTTP with streaming support
 
 The core client resides in `MCPClient::Client` and provides helper methods for integrating
 with popular AI services with built-in conversions:
@@ -48,11 +48,13 @@ client = MCPClient.create_client(
   mcp_server_configs: [
     # Local stdio server
     MCPClient.stdio_config(command: 'npx -y @modelcontextprotocol/server-filesystem /home/user'),
-    # Remote HTTP SSE server
+    # Remote HTTP SSE server (with streaming support)
     MCPClient.sse_config(
       base_url: 'https://api.example.com/sse',
       headers: { 'Authorization' => 'Bearer YOUR_TOKEN' },
-      read_timeout: 30 # Optional timeout in seconds (default: 30)
+      read_timeout: 30, # Optional timeout in seconds (default: 30)
+      retries: 3,       # Optional number of retry attempts (default: 0)
+      retry_backoff: 1  # Optional backoff delay in seconds (default: 1)
     )
   ]
 )
@@ -60,13 +62,31 @@ client = MCPClient.create_client(
 # List available tools
 tools = client.list_tools
 
+# Find tools by name pattern (string or regex)
+file_tools = client.find_tools('file')
+first_tool = client.find_tool(/^file_/)
+
 # Call a specific tool by name
 result = client.call_tool('example_tool', { param1: 'value1', param2: 42 })
 
+# Call multiple tools in batch
+results = client.call_tools([
+  { name: 'tool1', parameters: { key1: 'value1' } },
+  { name: 'tool2', parameters: { key2: 'value2' } }
+])
+
+# Stream results (for supported transports like SSE)
+client.call_tool_streaming('streaming_tool', { param: 'value' }).each do |chunk|
+  # Process each chunk as it arrives
+  puts chunk
+end
+
 # Format tools for specific AI services
 openai_tools = client.to_openai_tools
 anthropic_tools = client.to_anthropic_tools
 
+# Clear cached tools to force fresh fetch on next list
+client.clear_cache
 # Clean up connections
 client.cleanup
 ```
@@ -166,6 +186,8 @@ This client works with any MCP-compatible server, including:
 - [@playwright/mcp](https://www.npmjs.com/package/@playwright/mcp) - Browser automation
 - Custom servers implementing the MCP protocol
 
+### Server Implementation Features
+
 ### Server-Sent Events (SSE) Implementation
 
 The SSE client implementation provides these key features:
@@ -174,6 +196,7 @@ The SSE client implementation provides these key features:
 - **Thread safety**: All operations are thread-safe using monitors and synchronized access
 - **Reliable error handling**: Comprehensive error handling for network issues, timeouts, and malformed responses
 - **JSON-RPC over SSE**: Full implementation of JSON-RPC 2.0 over SSE transport
+- **Streaming support**: Native streaming for real-time updates
 
 ## Requirements
 

data/lib/mcp_client/client.rb

@@ -1,13 +1,28 @@
 # frozen_string_literal: true
 
+require 'logger'
+
 module MCPClient
   # MCP Client for integrating with the Model Context Protocol
   # This is the main entry point for using MCP tools
   class Client
-    attr_reader :servers, :tool_cache
+    # @!attribute [r] servers
+    #   @return [Array<MCPClient::ServerBase>] list of servers
+    # @!attribute [r] tool_cache
+    #   @return [Hash<String, MCPClient::Tool>] cache of tools by name
+    # @!attribute [r] logger
+    #   @return [Logger] logger for client operations
+    attr_reader :servers, :tool_cache, :logger
 
-    def initialize(mcp_server_configs: [])
-      @servers = mcp_server_configs.map { |config| MCPClient::ServerFactory.create(config) }
+    # Initialize a new MCPClient::Client
+    # @param mcp_server_configs [Array<Hash>] configurations for MCP servers
+    # @param logger [Logger, nil] optional logger, defaults to STDOUT
+    def initialize(mcp_server_configs: [], logger: nil)
+      @logger = logger || Logger.new($stdout, level: Logger::WARN)
+      @servers = mcp_server_configs.map do |config|
+        @logger.debug("Creating server with config: #{config.inspect}")
+        MCPClient::ServerFactory.create(config)
+      end
       @tool_cache = {}
     end
 
@@ -38,6 +53,9 @@ module MCPClient
 
       raise MCPClient::Errors::ToolNotFound, "Tool '#{tool_name}' not found" unless tool
 
+      # Validate parameters against tool schema
+      validate_params!(tool, parameters)
+
       # Find the server that owns this tool
       server = find_server_for_tool(tool)
       raise MCPClient::Errors::ServerNotFound, "No server found for tool '#{tool_name}'" unless server
@@ -46,15 +64,21 @@ module MCPClient
     end
 
     # Convert MCP tools to OpenAI function specifications
+    # @param tool_names [Array<String>, nil] optional list of tool names to include, nil means all tools
     # @return [Array<Hash>] OpenAI function specifications
-    def to_openai_tools
-      list_tools.map(&:to_openai_tool)
+    def to_openai_tools(tool_names: nil)
+      tools = list_tools
+      tools = tools.select { |t| tool_names.include?(t.name) } if tool_names
+      tools.map(&:to_openai_tool)
     end
 
     # Convert MCP tools to Anthropic Claude tool specifications
+    # @param tool_names [Array<String>, nil] optional list of tool names to include, nil means all tools
     # @return [Array<Hash>] Anthropic Claude tool specifications
-    def to_anthropic_tools
-      list_tools.map(&:to_anthropic_tool)
+    def to_anthropic_tools(tool_names: nil)
+      tools = list_tools
+      tools = tools.select { |t| tool_names.include?(t.name) } if tool_names
+      tools.map(&:to_anthropic_tool)
     end
 
     # Clean up all server connections
@@ -62,8 +86,82 @@ module MCPClient
       servers.each(&:cleanup)
     end
 
+    # Clear the cached tools so that next list_tools will fetch fresh data
+    # @return [void]
+    def clear_cache
+      @tool_cache.clear
+    end
+
+    # Find all tools whose name matches the given pattern (String or Regexp)
+    # @param pattern [String, Regexp] pattern to match tool names
+    # @return [Array<MCPClient::Tool>] matching tools
+    def find_tools(pattern)
+      rx = pattern.is_a?(Regexp) ? pattern : /#{Regexp.escape(pattern)}/
+      list_tools.select { |t| t.name.match(rx) }
+    end
+
+    # Find the first tool whose name matches the given pattern
+    # @param pattern [String, Regexp] pattern to match tool names
+    # @return [MCPClient::Tool, nil]
+    def find_tool(pattern)
+      find_tools(pattern).first
+    end
+
+    # Call multiple tools in batch
+    # @param calls [Array<Hash>] array of calls in the form { name: tool_name, parameters: {...} }
+    # @return [Array<Object>] array of results for each tool invocation
+    def call_tools(calls)
+      calls.map do |call|
+        name = call[:name] || call['name']
+        params = call[:parameters] || call['parameters'] || {}
+        call_tool(name, params)
+      end
+    end
+
+    # Stream call of a specific tool by name with the given parameters.
+    # Returns an Enumerator yielding streaming updates if supported.
+    # @param tool_name [String] the name of the tool to call
+    # @param parameters [Hash] the parameters to pass to the tool
+    # @return [Enumerator] streaming enumerator or single-value enumerator
+    def call_tool_streaming(tool_name, parameters)
+      tools = list_tools
+      tool = tools.find { |t| t.name == tool_name }
+      raise MCPClient::Errors::ToolNotFound, "Tool '#{tool_name}' not found" unless tool
+
+      # Validate parameters against tool schema
+      validate_params!(tool, parameters)
+      # Find the server that owns this tool
+      server = find_server_for_tool(tool)
+      raise MCPClient::Errors::ServerNotFound, "No server found for tool '#{tool_name}'" unless server
+
+      if server.respond_to?(:call_tool_streaming)
+        server.call_tool_streaming(tool_name, parameters)
+      else
+        Enumerator.new do |yielder|
+          yielder << server.call_tool(tool_name, parameters)
+        end
+      end
+    end
+
     private
 
+    # Validate parameters against tool JSON schema (checks required properties)
+    # @param tool [MCPClient::Tool] tool definition with schema
+    # @param parameters [Hash] parameters to validate
+    # @raise [MCPClient::Errors::ValidationError] when required params are missing
+    def validate_params!(tool, parameters)
+      schema = tool.schema
+      return unless schema.is_a?(Hash)
+
+      required = schema['required'] || schema[:required]
+      return unless required.is_a?(Array)
+
+      missing = required.map(&:to_s) - parameters.keys.map(&:to_s)
+      return unless missing.any?
+
+      raise MCPClient::Errors::ValidationError, "Missing required parameters: #{missing.join(', ')}"
+    end
+
     def find_server_for_tool(tool)
       servers.find do |server|
         server.list_tools.any? { |t| t.name == tool.name }

data/lib/mcp_client/errors.rb

@@ -23,5 +23,7 @@ module MCPClient
 
     # Raised when there's an error in the MCP server transport
     class TransportError < MCPError; end
+    # Raised when tool parameters fail validation against JSON schema
+    class ValidationError < MCPError; end
   end
 end

data/lib/mcp_client/server_factory.rb

@@ -14,7 +14,10 @@ module MCPClient
         MCPClient::ServerSSE.new(
           base_url: config[:base_url],
           headers: config[:headers] || {},
-          read_timeout: config[:read_timeout] || 30
+          read_timeout: config[:read_timeout] || 30,
+          retries: config[:retries] || 0,
+          retry_backoff: config[:retry_backoff] || 1,
+          logger: config[:logger]
         )
       else
         raise ArgumentError, "Unknown server type: #{config[:type]}"

data/lib/mcp_client/server_sse.rb

@@ -5,6 +5,7 @@ require 'net/http'
 require 'json'
 require 'openssl'
 require 'monitor'
+require 'logger'
 
 module MCPClient
   # Implementation of MCP server that communicates via Server-Sent Events (SSE)
@@ -15,8 +16,14 @@ module MCPClient
     # @param base_url [String] The base URL of the MCP server
     # @param headers [Hash] Additional headers to include in requests
     # @param read_timeout [Integer] Read timeout in seconds (default: 30)
-    def initialize(base_url:, headers: {}, read_timeout: 30)
+    # @param retries [Integer] number of retry attempts on transient errors
+    # @param retry_backoff [Numeric] base delay in seconds for exponential backoff
+    # @param logger [Logger, nil] optional logger
+    def initialize(base_url:, headers: {}, read_timeout: 30, retries: 0, retry_backoff: 1, logger: nil)
       super()
+      @logger = logger || Logger.new($stdout, level: Logger::WARN)
+      @max_retries = retries
+      @retry_backoff = retry_backoff
       @base_url = base_url.end_with?('/') ? base_url : "#{base_url}/"
       @headers = headers.merge({
                                  'Accept' => 'text/event-stream',
@@ -37,6 +44,16 @@ module MCPClient
       @connection_cv = @mutex.new_cond
     end
 
+    # Stream tool call fallback for SSE transport (yields single result)
+    # @param tool_name [String]
+    # @param parameters [Hash]
+    # @return [Enumerator]
+    def call_tool_streaming(tool_name, parameters)
+      Enumerator.new do |yielder|
+        yielder << call_tool(tool_name, parameters)
+      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
@@ -201,6 +218,7 @@ module MCPClient
               end
 
               response.read_body do |chunk|
+                @logger.debug("SSE chunk received: #{chunk.inspect}")
                 process_sse_chunk(chunk.dup)
               end
             end
@@ -219,6 +237,7 @@ module MCPClient
     # Process an SSE chunk from the server
     # @param chunk [String] the chunk to process
     def process_sse_chunk(chunk)
+      @logger.debug("Processing SSE chunk: #{chunk.inspect}")
       local_buffer = nil
 
       @mutex.synchronize do
@@ -278,6 +297,7 @@ module MCPClient
     # @param event_data [String] the event data to parse
     # @return [Hash, nil] the parsed event, or nil if the event is invalid
     def parse_sse_event(event_data)
+      @logger.debug("Parsing SSE event data: #{event_data.inspect}")
       event = { event: 'message', data: '', id: nil }
       data_lines = []
 
@@ -295,6 +315,7 @@ module MCPClient
       end
 
       event[:data] = data_lines.join("\n")
+      @logger.debug("Parsed SSE event: #{event.inspect}")
       event[:data].empty? ? nil : event
     end
 
@@ -331,10 +352,31 @@ module MCPClient
       raise MCPClient::Errors::ToolCallError, 'Failed to get tools list from JSON-RPC request'
     end
 
+    # Helper: execute block with retry/backoff for transient errors
+    # @yield block to execute
+    # @return result of block
+    def with_retry
+      attempts = 0
+      begin
+        yield
+      rescue MCPClient::Errors::TransportError, MCPClient::Errors::ServerError, IOError, Errno::ETIMEDOUT,
+             Errno::ECONNRESET => e
+        attempts += 1
+        if attempts <= @max_retries
+          delay = @retry_backoff * (2**(attempts - 1))
+          @logger.debug("Retry attempt #{attempts} after error: #{e.message}, sleeping #{delay}s")
+          sleep(delay)
+          retry
+        end
+        raise
+      end
+    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
     def send_jsonrpc_request(request)
+      @logger.debug("Sending JSON-RPC request: #{request.to_json}")
       uri = URI.parse(@base_url)
       rpc_http = Net::HTTP.new(uri.host, uri.port)
 
@@ -367,6 +409,7 @@ module MCPClient
                  .each { |k, v| http_request[k] = v }
 
           response = http.request(http_request)
+          @logger.debug("Received JSON-RPC response: #{response.code} #{response.body}")
 
           unless response.is_a?(Net::HTTPSuccess)
             raise MCPClient::Errors::ServerError, "Server returned error: #{response.code} #{response.message}"

data/lib/mcp_client/server_stdio.rb

@@ -3,6 +3,7 @@
 require 'open3'
 require 'json'
 require_relative 'version'
+require 'logger'
 
 module MCPClient
   # JSON-RPC implementation of MCP server over stdio.
@@ -13,7 +14,10 @@ module MCPClient
     READ_TIMEOUT = 15
 
     # @param command [String, Array] the stdio command to launch the MCP JSON-RPC server
-    def initialize(command:)
+    # @param retries [Integer] number of retry attempts on transient errors
+    # @param retry_backoff [Numeric] base delay in seconds for exponential backoff
+    # @param logger [Logger, nil] optional logger
+    def initialize(command:, retries: 0, retry_backoff: 1, logger: nil)
       super()
       @command = command.is_a?(Array) ? command.join(' ') : command
       @mutex = Mutex.new
@@ -21,6 +25,9 @@ module MCPClient
       @next_id = 1
       @pending = {}
       @initialized = false
+      @logger = logger || Logger.new($stdout, level: Logger::WARN)
+      @max_retries = retries
+      @retry_backoff = retry_backoff
     end
 
     # Connect to the MCP server by launching the command process via stdout/stdin
@@ -49,6 +56,7 @@ module MCPClient
     # @param line [String] line of output to parse
     def handle_line(line)
       msg = JSON.parse(line)
+      @logger.debug("Received line: #{line.chomp}")
       id = msg['id']
       return unless id
 
@@ -173,6 +181,7 @@ module MCPClient
     end
 
     def send_request(req)
+      @logger.debug("Sending JSONRPC request: #{req.to_json}")
       @stdin.puts(req.to_json)
     rescue StandardError => e
       raise MCPClient::Errors::TransportError, "Failed to send JSONRPC request: #{e.message}"
@@ -194,5 +203,15 @@ module MCPClient
         msg
       end
     end
+
+    # Stream tool call fallback for stdio transport (yields single result)
+    # @param tool_name [String]
+    # @param parameters [Hash]
+    # @return [Enumerator]
+    def call_tool_streaming(tool_name, parameters)
+      Enumerator.new do |yielder|
+        yielder << call_tool(tool_name, parameters)
+      end
+    end
   end
 end

data/lib/mcp_client/version.rb

@@ -2,5 +2,5 @@
 
 module MCPClient
   # Current version of the MCP client gem
-  VERSION = '0.1.0'
+  VERSION = '0.3.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-mcp-client
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Szymon Kurcab