ruby-mcp-client 0.5.3 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ec468ae4d2033287bfc89a788e87acc878ab833552e98bef88c95176fa6a906
-  data.tar.gz: d6f2f676be6932d8dbe641df40674aa77ef64d1296d9fdf4eb7c892537f2fa0c
+  metadata.gz: a6607aff3aa197734ac1b5fd4c2f51bb994df18ffcb0f18928c4f75197aaa8ed
+  data.tar.gz: 6921d74355c4497ca944374795469a767873ff8716e54fedbe3438104a4e5b79
 SHA512:
-  metadata.gz: 49f5427d6ffc9bc5632bed9b56e4c03e70ce4894d087331f12fd340b60ce82a539b9b2a362c1ce8d0b9686d9d9a4dae4bea3d11ec732b8a0ae34a3e898ff43b2
-  data.tar.gz: 3e32823ef422661fbcf507caf141d0ce65aedd0661ecb54f3b2a287565b630049d2acdfc4bb7b9a93a965e75403b635e43eb21259f035d8b82810f58e0fff304
+  metadata.gz: cea51f3ff6046ac619197413ccbe50a18fc3aeef6f881180d9cc5b0ad49b67d1cbe93459005f93f3063ad2dfe699c06bb1556180dc3bd1437d67e38b89549c9a
+  data.tar.gz: 8de670f6d7f3fd5a3c9786365e19034ee6d8734ef8d938769818acb606c8f7c13529b8777cdff2a54483398d52dd7847ccddc957a8a4517c16ad31a1b35700b0

data/README.md

@@ -48,23 +48,31 @@ require 'mcp_client'
 client = MCPClient.create_client(
   mcp_server_configs: [
     # Local stdio server
-    MCPClient.stdio_config(command: 'npx -y @modelcontextprotocol/server-filesystem /home/user'),
+    MCPClient.stdio_config(
+      command: 'npx -y @modelcontextprotocol/server-filesystem /home/user',
+      name: 'filesystem' # Optional name for this server
+    ),
     # Remote HTTP SSE server (with streaming support)
     MCPClient.sse_config(
       base_url: 'https://api.example.com/sse',
       headers: { 'Authorization' => 'Bearer YOUR_TOKEN' },
+      name: 'api',      # Optional name for this server
       read_timeout: 30, # Optional timeout in seconds (default: 30)
       ping: 10,         # Optional ping interval in seconds of inactivity (default: 10)
                         # Connection closes automatically after inactivity (2.5x ping interval)
       retries: 3,       # Optional number of retry attempts (default: 0)
-      retry_backoff: 1  # Optional backoff delay in seconds (default: 1)
+      retry_backoff: 1, # Optional backoff delay in seconds (default: 1)
       # Native support for tool streaming via call_tool_streaming method
-)  ]
+      logger: Logger.new($stdout, level: Logger::INFO) # Optional logger for this server
+)  ],
+  # Optional logger for the client and all servers without explicit loggers
+  logger: Logger.new($stdout, level: Logger::WARN)
 )
 
 # Or load server definitions from a JSON file
 client = MCPClient.create_client(
-  server_definition_file: 'path/to/server_definition.json'
+  server_definition_file: 'path/to/server_definition.json',
+  logger: Logger.new($stdout, level: Logger::WARN) # Optional logger for client and servers
 )
 
 # MCP server configuration JSON format can be:
@@ -74,10 +82,14 @@ client = MCPClient.create_client(
 #    [{ "type": "stdio", "command": "npx server" }, { "type": "sse", "url": "http://..." }]
 # 3. An object with "mcpServers" key containing named servers:
 #    { "mcpServers": { "server1": { "type": "sse", "url": "http://..." } } }
+#    Note: When using this format, server1 will be accessible by name
 
 # List available tools
 tools = client.list_tools
 
+# Find a server by name
+filesystem_server = client.find_server('filesystem')
+
 # Find tools by name pattern (string or regex)
 file_tools = client.find_tools('file')
 first_tool = client.find_tool(/^file_/)
@@ -85,15 +97,20 @@ first_tool = client.find_tool(/^file_/)
 # Call a specific tool by name
 result = client.call_tool('example_tool', { param1: 'value1', param2: 42 })
 
+# Call a tool on a specific server by name
+result = client.call_tool('example_tool', { param1: 'value1' }, server: 'filesystem')
+# You can also call a tool on a server directly
+result = filesystem_server.call_tool('example_tool', { param1: 'value1' })
+
 # Call multiple tools in batch
 results = client.call_tools([
   { name: 'tool1', parameters: { key1: 'value1' } },
-  { name: 'tool2', parameters: { key2: 'value2' } }
+  { name: 'tool2', parameters: { key2: 'value2' }, server: 'filesystem' } # Specify server for a specific tool
 ])
 
 # Stream results (supported by the SSE transport)
 # Returns an Enumerator that yields results as they become available
-client.call_tool_streaming('streaming_tool', { param: 'value' }).each do |chunk|
+client.call_tool_streaming('streaming_tool', { param: 'value' }, server: 'api').each do |chunk|
   # Process each chunk as it arrives
   puts chunk
 end
@@ -105,13 +122,14 @@ google_tools = client.to_google_tools
 
 # Register for server notifications
 client.on_notification do |server, method, params|
-  puts "Server notification: #{server.class} - #{method} - #{params}"
+  puts "Server notification: #{server.class}[#{server.name}] - #{method} - #{params}"
   # Handle specific notifications based on method name
   # 'notifications/tools/list_changed' is handled automatically by the client
 end
 
 # Send custom JSON-RPC requests or notifications
-client.send_rpc('custom_method', params: { key: 'value' }, server: :sse) # Uses specific server
+client.send_rpc('custom_method', params: { key: 'value' }, server: :sse) # Uses specific server by type
+client.send_rpc('custom_method', params: { key: 'value' }, server: 'filesystem') # Uses specific server by name
 result = client.send_rpc('another_method', params: { data: 123 }) # Uses first available server
 client.send_notification('status_update', params: { status: 'ready' })
 
@@ -146,7 +164,8 @@ sse_client = MCPClient.create_client(
       read_timeout: 30,  # Timeout in seconds for request fulfillment
       ping: 10,          # Send ping after 10 seconds of inactivity
                          # Connection closes automatically after inactivity (2.5x ping interval)
-      retries: 2         # Number of retry attempts on transient errors
+      retries: 2,        # Number of retry attempts on transient errors
+      logger: logger     # Optional logger for debugging connection issues
     )
   ]
 )
@@ -342,15 +361,19 @@ Special configuration options:
 
 - **Multiple transports** - Support for both stdio and SSE transports
 - **Multiple servers** - Connect to multiple MCP servers simultaneously
+- **Named servers** - Associate names with servers and find/reference them by name
+- **Server lookup** - Find servers by name using `find_server`
+- **Tool association** - Each tool knows which server it belongs to
 - **Tool discovery** - Find tools by name or pattern
+- **Server disambiguation** - Specify which server to use when tools with same name exist in multiple servers
 - **Atomic tool calls** - Simple API for invoking tools with parameters
 - **Batch support** - Call multiple tools in a single operation
-- **API conversions** - Built-in format conversion for OpenAI and Anthropic APIs
+- **API conversions** - Built-in format conversion for OpenAI, Anthropic, and Google Vertex AI APIs
 - **Thread safety** - Synchronized access for thread-safe operation
 - **Server notifications** - Support for JSON-RPC notifications
 - **Custom RPC methods** - Send any custom JSON-RPC method
 - **Consistent error handling** - Rich error types for better exception handling
-- **JSON configuration** - Support for server definition files in JSON format
+- **JSON configuration** - Support for server definition files in JSON format with name retention
 
 ### Server-Sent Events (SSE) Implementation
 
@@ -362,6 +385,13 @@ The SSE client implementation provides these key features:
   - **Automatic ping**: Sends ping requests after a configurable period of inactivity (default: 10 seconds)
   - **Automatic disconnection**: Closes idle connections after inactivity (2.5× ping interval)
   - **MCP compliant**: Any server communication resets the inactivity timer per specification
+- **Intelligent reconnection**:
+  - **Ping failure detection**: Tracks consecutive ping failures (when server isn't responding)
+  - **Automatic reconnection**: Attempts to reconnect after 3 consecutive ping failures
+  - **Exponential backoff**: Uses increasing delays between reconnection attempts
+  - **Smart retry limits**: Caps reconnection attempts (default: 5) to avoid infinite loops
+  - **Connection state monitoring**: Properly detects and handles closed connections to prevent errors
+  - **Failure transparency**: Handles reconnection in the background without disrupting client code
 - **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 with initialize handshake

data/lib/mcp_client/client.rb

@@ -23,7 +23,7 @@ module MCPClient
       @logger.formatter = proc { |severity, _datetime, progname, msg| "#{severity} [#{progname}] #{msg}\n" }
       @servers = mcp_server_configs.map do |config|
         @logger.debug("Creating server with config: #{config.inspect}")
-        MCPClient::ServerFactory.create(config)
+        MCPClient::ServerFactory.create(config, logger: @logger)
       end
       @tool_cache = {}
       # JSON-RPC notification listeners
@@ -42,15 +42,35 @@ module MCPClient
     # Lists all available tools from all connected MCP servers
     # @param cache [Boolean] whether to use cached tools or fetch fresh
     # @return [Array<MCPClient::Tool>] list of available tools
+    # @raise [MCPClient::Errors::ConnectionError] on authorization failures
+    # @raise [MCPClient::Errors::ToolCallError] if no tools could be retrieved from any server
     def list_tools(cache: true)
       return @tool_cache.values if cache && !@tool_cache.empty?
 
       tools = []
+      connection_errors = []
+
       servers.each do |server|
         server.list_tools.each do |tool|
           @tool_cache[tool.name] = tool
           tools << tool
         end
+      rescue MCPClient::Errors::ConnectionError => e
+        # Fast-fail on authorization errors for better user experience
+        # If this is the first server or we haven't collected any tools yet,
+        # raise the auth error directly to avoid cascading error messages
+        raise e if e.message.include?('Authorization failed') && tools.empty?
+
+        # Store the error and try other servers
+        connection_errors << e
+        @logger.error("Server error: #{e.message}")
+      end
+
+      # If we didn't get any tools from any server but have servers configured, report failure
+      if tools.empty? && !servers.empty?
+        raise connection_errors.first if connection_errors.any?
+
+        raise MCPClient::Errors::ToolCallError, 'Failed to retrieve tools from any server'
       end
 
       tools
@@ -59,21 +79,51 @@ module MCPClient
     # Calls a specific tool by name 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
+    # @param server [String, Symbol, Integer, MCPClient::ServerBase, nil] optional server to use
     # @return [Object] the result of the tool invocation
-    def call_tool(tool_name, parameters)
+    def call_tool(tool_name, parameters, server: nil)
       tools = list_tools
-      tool = tools.find { |t| t.name == tool_name }
 
-      raise MCPClient::Errors::ToolNotFound, "Tool '#{tool_name}' not found" unless tool
+      if server
+        # Use the specified server
+        srv = select_server(server)
+        # Find the tool on this specific server
+        tool = tools.find { |t| t.name == tool_name && t.server == srv }
+        unless tool
+          raise MCPClient::Errors::ToolNotFound,
+                "Tool '#{tool_name}' not found on server '#{srv.name || srv.class.name}'"
+        end
+      else
+        # Find the tool across all servers
+        matching_tools = tools.select { |t| t.name == tool_name }
+
+        if matching_tools.empty?
+          raise MCPClient::Errors::ToolNotFound, "Tool '#{tool_name}' not found"
+        elsif matching_tools.size > 1
+          # If multiple matches, disambiguate with server names
+          server_names = matching_tools.map { |t| t.server&.name || 'unnamed' }
+          raise MCPClient::Errors::AmbiguousToolName,
+                "Multiple tools named '#{tool_name}' found across servers (#{server_names.join(', ')}). " \
+                "Please specify a server using the 'server' parameter."
+        end
+
+        tool = matching_tools.first
+      end
 
       # Validate parameters against tool schema
       validate_params!(tool, parameters)
 
-      # Find the server that owns this tool
-      server = find_server_for_tool(tool)
+      # Use the tool's associated server
+      server = tool.server
       raise MCPClient::Errors::ServerNotFound, "No server found for tool '#{tool_name}'" unless server
 
-      server.call_tool(tool_name, parameters)
+      begin
+        server.call_tool(tool_name, parameters)
+      rescue MCPClient::Errors::ConnectionError => e
+        # Add server identity information to the error for better context
+        server_id = server.name ? "#{server.class}[#{server.name}]" : server.class.name
+        raise MCPClient::Errors::ToolCallError, "Error calling tool '#{tool_name}': #{e.message} (Server: #{server_id})"
+      end
     end
 
     # Convert MCP tools to OpenAI function specifications
@@ -94,6 +144,9 @@ module MCPClient
       tools.map(&:to_anthropic_tool)
     end
 
+    # Convert MCP tools to Google Vertex AI tool specifications
+    # @param tool_names [Array<String>, nil] optional list of tool names to include, nil means all tools
+    # @return [Array<Hash>] Google Vertex AI tool specifications with cleaned schemas
     def to_google_tools(tool_names: nil)
       tools = list_tools
       tools = tools.select { |t| tool_names.include?(t.name) } if tool_names
@@ -118,6 +171,13 @@ module MCPClient
       @notification_listeners << block
     end
 
+    # Find a server by name
+    # @param name [String] the name of the server to find
+    # @return [MCPClient::ServerBase, nil] the server with the given name, or nil if not found
+    def find_server(name)
+      @servers.find { |s| s.name == name }
+    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
@@ -134,13 +194,15 @@ module MCPClient
     end
 
     # Call multiple tools in batch
-    # @param calls [Array<Hash>] array of calls in the form { name: tool_name, parameters: {...} }
+    # @param calls [Array<Hash>] array of calls in the form:
+    #   { name: tool_name, parameters: {...}, server: optional_server_name }
     # @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)
+        server = call[:server] || call['server']
+        call_tool(name, params, server: server)
       end
     end
 
@@ -148,24 +210,52 @@ module MCPClient
     # 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
+    # @param server [String, Symbol, Integer, MCPClient::ServerBase, nil] optional server to use
     # @return [Enumerator] streaming enumerator or single-value enumerator
-    def call_tool_streaming(tool_name, parameters)
+    def call_tool_streaming(tool_name, parameters, server: nil)
       tools = list_tools
-      tool = tools.find { |t| t.name == tool_name }
-      raise MCPClient::Errors::ToolNotFound, "Tool '#{tool_name}' not found" unless tool
+
+      if server
+        # Use the specified server
+        srv = select_server(server)
+        # Find the tool on this specific server
+        tool = tools.find { |t| t.name == tool_name && t.server == srv }
+        unless tool
+          raise MCPClient::Errors::ToolNotFound,
+                "Tool '#{tool_name}' not found on server '#{srv.name || srv.class.name}'"
+        end
+      else
+        # Find the tool across all servers
+        matching_tools = tools.select { |t| t.name == tool_name }
+
+        if matching_tools.empty?
+          raise MCPClient::Errors::ToolNotFound, "Tool '#{tool_name}' not found"
+        elsif matching_tools.size > 1
+          # If multiple matches, disambiguate with server names
+          server_names = matching_tools.map { |t| t.server&.name || 'unnamed' }
+          raise MCPClient::Errors::AmbiguousToolName,
+                "Multiple tools named '#{tool_name}' found across servers (#{server_names.join(', ')}). " \
+                "Please specify a server using the 'server' parameter."
+        end
+
+        tool = matching_tools.first
+      end
 
       # Validate parameters against tool schema
       validate_params!(tool, parameters)
-      # Find the server that owns this tool
-      server = find_server_for_tool(tool)
+
+      # Use the tool's associated server
+      server = tool.server
       raise MCPClient::Errors::ServerNotFound, "No server found for tool '#{tool_name}'" unless server
 
-      if server.respond_to?(:call_tool_streaming)
+      begin
+        # Use the streaming API if it's available
         server.call_tool_streaming(tool_name, parameters)
-      else
-        Enumerator.new do |yielder|
-          yielder << server.call_tool(tool_name, parameters)
-        end
+      rescue MCPClient::Errors::ConnectionError => e
+        # Add server identity information to the error for better context
+        server_id = server.name ? "#{server.class}[#{server.name}]" : server.class.name
+        msg = "Error calling streaming tool '#{tool_name}': #{e.message} (Server: #{server_id})"
+        raise MCPClient::Errors::ToolCallError, msg
       end
     end
 
@@ -218,20 +308,24 @@ module MCPClient
     # @param params [Hash] parameters for the notification
     # @return [void]
     def process_notification(server, method, params)
+      server_id = server.name ? "#{server.class}[#{server.name}]" : server.class
       case method
       when 'notifications/tools/list_changed'
-        logger.warn("[#{server.class}] Tool list has changed, clearing tool cache")
+        logger.warn("[#{server_id}] Tool list has changed, clearing tool cache")
         clear_cache
       when 'notifications/resources/updated'
-        logger.warn("[#{server.class}] Resource #{params['uri']} updated")
+        logger.warn("[#{server_id}] Resource #{params['uri']} updated")
       when 'notifications/prompts/list_changed'
-        logger.warn("[#{server.class}] Prompt list has changed")
+        logger.warn("[#{server_id}] Prompt list has changed")
       when 'notifications/resources/list_changed'
-        logger.warn("[#{server.class}] Resource list has changed")
+        logger.warn("[#{server_id}] Resource list has changed")
+      else
+        # Log unknown notification types for debugging purposes
+        logger.debug("[#{server_id}] Received unknown notification: #{method} - #{params}")
       end
     end
 
-    # Select a server based on index, type, or instance
+    # Select a server based on index, name, type, or instance
     # @param server_arg [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
     # @return [MCPClient::ServerBase]
     def select_server(server_arg)
@@ -246,15 +340,20 @@ module MCPClient
         end
       when String, Symbol
         key = server_arg.to_s.downcase
+
+        # First check if it's a server name match
+        srv = @servers.find { |s| s.name && s.name.downcase == key }
+        return srv if srv
+
+        # Then check if it's a server type match
         srv = @servers.find { |s| s.class.name.split('::').last.downcase.end_with?(key) }
-        raise MCPClient::Errors::ServerNotFound, "Server of type #{server_arg} not found" unless srv
+        raise MCPClient::Errors::ServerNotFound, "Server with name or type '#{server_arg}' not found" unless srv
 
         srv
       else
         raise ArgumentError, "Invalid server argument: #{server_arg.inspect}" unless @servers.include?(server_arg)
 
         server_arg
-
       end
     end
 

data/lib/mcp_client/config_parser.rb

@@ -30,7 +30,11 @@ module MCPClient
         next unless validate_server_config(config, server_name)
 
         server_config = process_server_config(config, server_name)
-        result[server_name] = server_config if server_config
+        next unless server_config
+
+        # Add server name to the config
+        server_config[:name] = server_name
+        result[server_name] = server_config
       end
 
       result

data/lib/mcp_client/errors.rb

@@ -23,7 +23,11 @@ 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
+
+    # Raised when multiple tools with the same name exist across different servers
+    class AmbiguousToolName < MCPError; end
   end
 end

data/lib/mcp_client/server_base.rb

@@ -3,6 +3,16 @@
 module MCPClient
   # Base class for MCP servers - serves as the interface for different server implementations
   class ServerBase
+    # @!attribute [r] name
+    #   @return [String] the name of the server
+    attr_reader :name
+
+    # Initialize the server with a name
+    # @param name [String, nil] server name
+    def initialize(name: nil)
+      @name = name
+    end
+
     # Initialize a connection to the MCP server
     # @return [Boolean] true if connection successful
     def connect
@@ -45,6 +55,16 @@ module MCPClient
       raise NotImplementedError, 'Subclasses must implement rpc_notify'
     end
 
+    # Stream a tool call result (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
+
     # Ping the MCP server to check connectivity (zero-parameter heartbeat call)
     # @return [Object] result from the ping request
     def ping

data/lib/mcp_client/server_factory.rb

@@ -5,8 +5,9 @@ module MCPClient
   class ServerFactory
     # Create a server instance based on configuration
     # @param config [Hash] server configuration
+    # @param logger [Logger, nil] optional logger to use for the server
     # @return [MCPClient::ServerBase] server instance
-    def self.create(config)
+    def self.create(config, logger: nil)
       case config[:type]
       when 'stdio'
         MCPClient::ServerStdio.new(
@@ -14,7 +15,8 @@ module MCPClient
           retries: config[:retries] || 0,
           retry_backoff: config[:retry_backoff] || 1,
           read_timeout: config[:read_timeout] || MCPClient::ServerStdio::READ_TIMEOUT,
-          logger: config[:logger]
+          name: config[:name],
+          logger: config[:logger] || logger
         )
       when 'sse'
         MCPClient::ServerSSE.new(
@@ -24,7 +26,8 @@ module MCPClient
           ping: config[:ping] || 10,
           retries: config[:retries] || 0,
           retry_backoff: config[:retry_backoff] || 1,
-          logger: config[:logger]
+          name: config[:name],
+          logger: config[:logger] || logger
         )
       else
         raise ArgumentError, "Unknown server type: #{config[:type]}"