ruby-mcp-client 0.7.3 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd6b4269c644ed783b7d574e5a60b26ef0c749c3fe0a58fc86b4d7d5d8786a0d
-  data.tar.gz: 58eb4935ec413db8478dc29983f5baa68d7c28627968ffb5189d1b9754090a51
+  metadata.gz: 7e0949102c5c22625bef68e2f5b4a0e2aecdfc636495ecba52d16f663c35f2fc
+  data.tar.gz: fbeb7484c1458775b88aa074422913e9d09d8a37b23aac38c7edf82e2111b9cb
 SHA512:
-  metadata.gz: ee86e5f1e58fb98df9a9a7e715049eb8d7ae5f182430060633c9f97d7b2268d1a02859403ace69f6a400344cffad80dd9238169a638e27491a6bc99ce70fb462
-  data.tar.gz: 27e82788b84bc0887c273ab3c1277180e85f4930f413500fab4dbf2a7474dcb151bf510ec2509caf7a95bf53311dee587e65d8826b226e7ef164d9acd640582a
+  metadata.gz: b2e75071c0fceb5061037b1537d9e71fd8f03dc5c94aa6c2bbc2a63ce6f24ae16c1c2c2cdb560f48e12ca4115224561f89043dde2145116d1e4e397c9cb7e409
+  data.tar.gz: d3900ae79aba5d896a1496bc28af3e9ec8f0b7066f30eb0723cd1664845769dd09afd130faa2db0b4b1b67d948f15e3532cfb5abcd3b076d0e7547e7e89671fb

data/README.md

@@ -49,6 +49,8 @@ This Ruby MCP Client implements key features from the latest MCP specification (
 - **Streamable HTTP Transport** - Enhanced transport with Server-Sent Event formatted responses and session management
 - **HTTP Redirect Support** - Automatic redirect handling for both SSE and HTTP transports with configurable limits
 - **FastMCP Compatibility** - Full compatibility with FastMCP servers including proper line ending handling
+- **Prompts Support** - Full implementation of MCP prompts for dynamic content generation
+- **Resources Support** - Full MCP resources specification compliance including templates, subscriptions, pagination, and annotations
 
 ## Usage
 
@@ -87,6 +89,17 @@ client = MCPClient.create_client(
       retries: 3,       # Optional number of retry attempts (default: 3)
       retry_backoff: 1, # Optional backoff delay in seconds (default: 1)
       logger: Logger.new($stdout, level: Logger::INFO) # Optional logger for this server
+    ),
+    # Streamable HTTP server (HTTP POST with SSE responses and session management)
+    MCPClient.streamable_http_config(
+      base_url: 'https://api.example.com/mcp',
+      endpoint: '/rpc', # Optional JSON-RPC endpoint path (default: '/rpc')
+      headers: { 'Authorization' => 'Bearer YOUR_TOKEN' },
+      name: 'streamable_api', # Optional name for this server
+      read_timeout: 60, # Optional timeout in seconds (default: 30)
+      retries: 3,       # Optional number of retry attempts (default: 3)
+      retry_backoff: 1, # Optional backoff delay in seconds (default: 1)
+      logger: Logger.new($stdout, level: Logger::INFO) # Optional logger for this server
     )
   ],
   # Optional logger for the client and all servers without explicit loggers
@@ -100,13 +113,14 @@ client = MCPClient.create_client(
 )
 
 # MCP server configuration JSON format can be:
-# 1. A single server object: 
+# 1. A single server object:
 #    { "type": "sse", "url": "http://example.com/sse" }
 #    { "type": "http", "url": "http://example.com", "endpoint": "/rpc" }
-# 2. An array of server objects: 
-#    [{ "type": "stdio", "command": "npx server" }, { "type": "sse", "url": "http://..." }, { "type": "http", "url": "http://..." }]
+#    { "type": "streamable_http", "url": "http://example.com/mcp", "endpoint": "/rpc" }
+# 2. An array of server objects:
+#    [{ "type": "stdio", "command": "npx server" }, { "type": "sse", "url": "http://..." }, { "type": "streamable_http", "url": "http://..." }]
 # 3. An object with "mcpServers" key containing named servers:
-#    { "mcpServers": { "server1": { "type": "sse", "url": "http://..." }, "server2": { "type": "http", "url": "http://..." } } }
+#    { "mcpServers": { "server1": { "type": "sse", "url": "http://..." }, "server2": { "type": "streamable_http", "url": "http://..." } } }
 #    Note: When using this format, server1/server2 will be accessible by name
 
 # List available tools
@@ -140,6 +154,45 @@ client.call_tool_streaming('streaming_tool', { param: 'value' }, server: 'api').
   puts chunk
 end
 
+# === Working with Prompts ===
+# List available prompts from all servers
+prompts = client.list_prompts
+
+# Get a specific prompt with parameters
+result = client.get_prompt('greeting', { name: 'Ruby Developer' })
+
+# Get a prompt from a specific server
+result = client.get_prompt('greeting', { name: 'Ruby Developer' }, server: 'filesystem')
+
+# === Working with Resources ===
+# List available resources from all servers (returns hash with 'resources' array and optional 'nextCursor')
+result = client.list_resources
+resources = result['resources']  # Array of Resource objects from all servers
+next_cursor = result['nextCursor']  # nil when aggregating multiple servers
+
+# Get resources from a specific server with pagination support
+result = client.servers.first.list_resources
+resources = result['resources']  # Array of Resource objects
+next_cursor = result['nextCursor']  # For pagination
+
+# List resources with pagination (only works with single server or client.list_resources with cursor)
+result = client.list_resources(cursor: next_cursor)  # Uses first server when cursor provided
+
+# Read a specific resource by URI (returns array of ResourceContent objects)
+contents = client.read_resource('file:///example.txt')
+contents.each do |content|
+  if content.text?
+    puts content.text  # Text content
+  elsif content.binary?
+    data = Base64.decode64(content.blob)  # Binary content
+  end
+  puts content.mime_type if content.mime_type
+  puts content.annotations if content.annotations  # Optional metadata
+end
+
+# Read a resource from a specific server
+contents = client.read_resource('file:///example.txt', server: 'filesystem')
+
 # Format tools for specific AI services
 openai_tools = client.to_openai_tools
 anthropic_tools = client.to_anthropic_tools
@@ -333,15 +386,21 @@ puts "Ping successful: #{ping_result.inspect}"
 mcp_client.cleanup
 ```
 
-See `examples/mcp_sse_server_example.rb` for the full Playwright SSE example.
+See `examples/streamable_http_example.rb` for the full Playwright SSE example.
 
 ### FastMCP Example
 
-The repository includes a complete FastMCP server example that demonstrates the Ruby MCP client working with a Python FastMCP server:
+The repository includes complete FastMCP server examples that demonstrate the Ruby MCP client working with Python FastMCP servers, including full MCP protocol support with tools, prompts, and resources:
+
+#### Basic FastMCP Example
+
+**For FastMCP server with SSE transport (includes tools, prompts, and resources):**
+```bash
+# From the ruby-mcp-client directory
+python examples/echo_server.py
+```
 
 ```ruby
-# Start the FastMCP server
-# python examples/echo_server.py
 
 # Run the Ruby client
 # bundle exec ruby examples/echo_server_client.rb
@@ -352,17 +411,77 @@ require 'mcp_client'
 client = MCPClient.create_client(
   mcp_server_configs: [
     MCPClient.sse_config(
-      base_url: 'http://127.0.0.1:8000/sse/',
+      base_url: 'http://127.0.0.1:8000/sse',
       read_timeout: 30
     )
   ]
 )
 
-# List available tools
+# List and use tools
 tools = client.list_tools
 puts "Found #{tools.length} tools:"
 tools.each { |tool| puts "- #{tool.name}: #{tool.description}" }
 
+result = client.call_tool('echo', { message: 'Hello FastMCP!' })
+
+# List and use prompts
+prompts = client.list_prompts
+puts "Found #{prompts.length} prompts:"
+prompts.each { |prompt| puts "- #{prompt.name}: #{prompt.description}" }
+
+greeting = client.get_prompt('greeting', { name: 'Ruby Developer' })
+
+# List and read resources
+result = client.list_resources
+resources = result['resources']
+puts "Found #{resources.length} resources:"
+resources.each { |resource| puts "- #{resource.name} (#{resource.uri})" }
+
+# Read resource (returns array of ResourceContent objects)
+contents = client.read_resource('file:///sample/README.md')
+contents.each do |content|
+  puts content.text if content.text?
+end
+```
+
+#### Streamable HTTP Example
+
+**For FastMCP server with Streamable HTTP transport (includes tools, prompts, and resources):**
+```bash
+# From the ruby-mcp-client directory
+python examples/echo_server_streamable.py
+```
+
+```ruby
+
+# Run the streamable HTTP client
+# bundle exec ruby examples/echo_server_streamable_client.rb
+
+require 'mcp_client'
+
+# Connect to streamable HTTP server with full MCP protocol support
+client = MCPClient.create_client(
+  mcp_server_configs: [
+    MCPClient.streamable_http_config(
+      base_url: 'http://localhost:8931/mcp',
+      read_timeout: 60
+    )
+  ]
+)
+
+# Full protocol support including real-time notifications
+client.on_notification do |method, params|
+  puts "Server notification: #{method} - #{params}"
+end
+
+# Use all MCP features: tools, prompts, resources
+tools = client.list_tools
+prompts = client.list_prompts
+resources = client.list_resources
+
+# Real-time progress notifications for long-running tasks
+result = client.call_tool('long_task', { duration: 5, steps: 5 })
+
 # Use the tools
 result = client.call_tool('echo', { message: 'Hello from Ruby!' })
 result = client.call_tool('reverse', { text: 'FastMCP rocks!' })
@@ -371,8 +490,10 @@ client.cleanup
 ```
 
 The FastMCP example includes:
-- **`echo_server.py`** - A Python FastMCP server with 4 interactive tools
-- **`echo_server_client.rb`** - Ruby client demonstrating all features
+- **`echo_server.py`** - A Python FastMCP server with tools, prompts, and resources
+- **`echo_server_client.rb`** - Ruby client demonstrating all features including prompts and resources
+- **`echo_server_streamable.py`** - Enhanced streamable HTTP server with tools, prompts, and resources
+- **`echo_server_streamable_client.rb`** - Ruby client demonstrating streamable HTTP transport
 - **`README_ECHO_SERVER.md`** - Complete setup and usage instructions
 
 This example showcases redirect support, proper line ending handling, and seamless integration between Ruby and Python MCP implementations.
@@ -464,8 +585,9 @@ Complete examples can be found in the `examples/` directory:
 - `openai_ruby_mcp.rb` - Integration with official openai/openai-ruby gem
 - `ruby_anthropic_mcp.rb` - Integration with alexrudall/ruby-anthropic gem
 - `gemini_ai_mcp.rb` - Integration with Google Vertex AI and Gemini models
-- `mcp_sse_server_example.rb` - SSE transport with Playwright MCP
+- `streamable_http_example.rb` - Streamable HTTP transport with Playwright MCP
 - `echo_server.py` & `echo_server_client.rb` - FastMCP server example with full setup
+- `echo_server_streamable.py` & `echo_server_streamable_client.rb` - Enhanced streamable HTTP server example
 
 ## MCP Server Compatibility
 
@@ -666,6 +788,126 @@ token = oauth_provider.complete_authorization_flow(code, state)
 
 For complete OAuth documentation, see [OAUTH.md](OAUTH.md).
 
+## Resources
+
+The Ruby MCP Client provides full support for the MCP resources specification, enabling access to files, data, and other content with URI-based identification.
+
+### Resource Features
+
+- **Resource listing** with cursor-based pagination
+- **Resource templates** with URI patterns (RFC 6570)
+- **Resource subscriptions** for real-time updates
+- **Binary content support** with base64 encoding
+- **Resource annotations** for metadata (audience, priority, lastModified)
+- **ResourceContent objects** for structured content access
+
+### Resource API
+
+```ruby
+# Get a server instance
+server = client.servers.first  # or client.find_server('name')
+
+# List resources with pagination
+result = server.list_resources
+resources = result['resources']  # Array of Resource objects
+next_cursor = result['nextCursor']  # String cursor for next page (if any)
+
+# Get next page of resources
+if next_cursor
+  next_result = server.list_resources(cursor: next_cursor)
+end
+
+# Access Resource properties
+resource = resources.first
+resource.uri         # "file:///example.txt"
+resource.name        # "example.txt"
+resource.title       # Optional human-readable title
+resource.description # Optional description
+resource.mime_type   # "text/plain"
+resource.size        # Optional file size in bytes
+resource.annotations # Optional metadata hash
+
+# Read resource contents (returns array of ResourceContent objects)
+contents = server.read_resource(resource.uri)
+
+contents.each do |content|
+  # Check content type
+  if content.text?
+    # Text content
+    text = content.text
+    mime = content.mime_type  # e.g., "text/plain"
+  elsif content.binary?
+    # Binary content (base64 encoded)
+    blob = content.blob  # Base64 string
+    data = Base64.decode64(blob)  # Decoded binary data
+  end
+
+  # Access optional annotations
+  if content.annotations
+    audience = content.annotations['audience']  # e.g., ["user", "assistant"]
+    priority = content.annotations['priority']  # e.g., 0.5
+    modified = content.annotations['lastModified']  # ISO 8601 timestamp
+  end
+end
+
+# List resource templates
+templates_result = server.list_resource_templates
+templates = templates_result['resourceTemplates']  # Array of ResourceTemplate objects
+
+template = templates.first
+template.uri_template  # "file:///{path}" (RFC 6570 URI template)
+template.name         # Template name
+template.title        # Optional title
+template.description  # Optional description
+template.mime_type    # Optional MIME type hint
+
+# Subscribe to resource updates
+server.subscribe_resource('file:///watched.txt')  # Returns true on success
+
+# Unsubscribe from resource updates
+server.unsubscribe_resource('file:///watched.txt')  # Returns true on success
+
+# Check server capabilities for resources
+capabilities = server.capabilities
+if capabilities['resources']
+  can_subscribe = capabilities['resources']['subscribe']  # true/false
+  list_changed = capabilities['resources']['listChanged']  # true/false
+end
+```
+
+### Working with ResourceContent
+
+The `ResourceContent` class provides a structured way to handle both text and binary content:
+
+```ruby
+# ResourceContent for text
+content = MCPClient::ResourceContent.new(
+  uri: 'file:///example.txt',
+  name: 'example.txt',
+  mime_type: 'text/plain',
+  text: 'File contents here',
+  annotations: {
+    'audience' => ['user'],
+    'priority' => 1.0
+  }
+)
+
+# ResourceContent for binary data
+binary_content = MCPClient::ResourceContent.new(
+  uri: 'file:///image.png',
+  name: 'image.png',
+  mime_type: 'image/png',
+  blob: Base64.strict_encode64(binary_data)
+)
+
+# Access content
+if content.text?
+  puts content.text
+elsif content.binary?
+  data = Base64.decode64(content.blob)
+end
+```
+
 ## Key Features
 
 ### Client Features
@@ -679,6 +921,8 @@ For complete OAuth documentation, see [OAUTH.md](OAUTH.md).
 - **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
+- **Prompts support** - List and get prompts with parameters from MCP servers
+- **Resources support** - List and read resources by URI from MCP servers
 - **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

data/lib/mcp_client/client.rb

@@ -9,10 +9,14 @@ module MCPClient
     # @!attribute [r] servers
     #   @return [Array<MCPClient::ServerBase>] list of servers
     # @!attribute [r] tool_cache
-    #   @return [Hash<String, MCPClient::Tool>] cache of tools by name
+    #   @return [Hash<String, MCPClient::Tool>] cache of tools by composite key (server_id:name)
+    # @!attribute [r] prompt_cache
+    #   @return [Hash<String, MCPClient::Prompt>] cache of prompts by composite key (server_id:name)
+    # @!attribute [r] resource_cache
+    #   @return [Hash<String, MCPClient::Resource>] cache of resources by composite key (server_id:uri)
     # @!attribute [r] logger
     #   @return [Logger] logger for client operations
-    attr_reader :servers, :tool_cache, :logger
+    attr_reader :servers, :tool_cache, :prompt_cache, :resource_cache, :logger
 
     # Initialize a new MCPClient::Client
     # @param mcp_server_configs [Array<Hash>] configurations for MCP servers
@@ -26,6 +30,8 @@ module MCPClient
         MCPClient::ServerFactory.create(config, logger: @logger)
       end
       @tool_cache = {}
+      @prompt_cache = {}
+      @resource_cache = {}
       # JSON-RPC notification listeners
       @notification_listeners = []
       # Register default and user-defined notification handlers on each server
@@ -39,6 +45,149 @@ module MCPClient
       end
     end
 
+    # Lists all available prompts from all connected MCP servers
+    # @param cache [Boolean] whether to use cached prompts or fetch fresh
+    # @return [Array<MCPClient::Prompt>] list of available prompts
+    # @raise [MCPClient::Errors::ConnectionError] on authorization failures
+    # @raise [MCPClient::Errors::PromptGetError] if no prompts could be retrieved from any server
+    def list_prompts(cache: true)
+      return @prompt_cache.values if cache && !@prompt_cache.empty?
+
+      prompts = []
+      connection_errors = []
+
+      servers.each do |server|
+        server.list_prompts.each do |prompt|
+          cache_key = cache_key_for(server, prompt.name)
+          @prompt_cache[cache_key] = prompt
+          prompts << prompt
+        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 prompts yet,
+        # raise the auth error directly to avoid cascading error messages
+        raise e if e.message.include?('Authorization failed') && prompts.empty?
+
+        # Store the error and try other servers
+        connection_errors << e
+        @logger.error("Server error: #{e.message}")
+      end
+
+      prompts
+    end
+
+    # Gets a specific prompt by name with the given parameters
+    # @param prompt_name [String] the name of the prompt to get
+    # @param parameters [Hash] the parameters to pass to the prompt
+    # @param server [String, Symbol, Integer, MCPClient::ServerBase, nil] optional server to use
+    # @return [Object] the final prompt
+    def get_prompt(prompt_name, parameters, server: nil)
+      prompts = list_prompts
+
+      if server
+        # Use the specified server
+        srv = select_server(server)
+        # Find the prompt on this specific server
+        prompt = prompts.find { |t| t.name == prompt_name && t.server == srv }
+        unless prompt
+          raise MCPClient::Errors::PromptNotFound,
+                "Prompt '#{prompt_name}' not found on server '#{srv.name || srv.class.name}'"
+        end
+      else
+        # Find the prompt across all servers
+        matching_prompts = prompts.select { |t| t.name == prompt_name }
+
+        if matching_prompts.empty?
+          raise MCPClient::Errors::PromptNotFound, "Prompt '#{prompt_name}' not found"
+        elsif matching_prompts.size > 1
+          # If multiple matches, disambiguate with server names
+          server_names = matching_prompts.map { |t| t.server&.name || 'unnamed' }
+          raise MCPClient::Errors::AmbiguousPromptName,
+                "Multiple prompts named '#{prompt_name}' found across servers (#{server_names.join(', ')}). " \
+                "Please specify a server using the 'server' parameter."
+        end
+
+        prompt = matching_prompts.first
+      end
+
+      # Use the prompt's associated server
+      server = prompt.server
+      raise MCPClient::Errors::ServerNotFound, "No server found for prompt '#{prompt_name}'" unless server
+
+      begin
+        server.get_prompt(prompt_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::PromptGetError,
+              "Error getting prompt '#{prompt_name}': #{e.message} (Server: #{server_id})"
+      end
+    end
+
+    # Lists all available resources from all connected MCP servers
+    # @param cache [Boolean] whether to use cached resources or fetch fresh
+    # @param cursor [String, nil] optional cursor for pagination (only works with single server)
+    # @return [Hash] result containing 'resources' array and optional 'nextCursor'
+    # @raise [MCPClient::Errors::ConnectionError] on authorization failures
+    # @raise [MCPClient::Errors::ResourceReadError] if no resources could be retrieved from any server
+    def list_resources(cache: true, cursor: nil)
+      # If cursor is provided, we can only query one server (the one that provided the cursor)
+      # This is a limitation of aggregating multiple servers
+      if cursor
+        # For now, just use the first server when cursor is provided
+        # In a real implementation, you'd need to track which server the cursor came from
+        return servers.first.list_resources(cursor: cursor) if servers.any?
+
+        return { 'resources' => [], 'nextCursor' => nil }
+      end
+
+      # Use cache if available and no cursor
+      return { 'resources' => @resource_cache.values, 'nextCursor' => nil } if cache && !@resource_cache.empty?
+
+      resources = []
+      connection_errors = []
+
+      servers.each do |server|
+        result = server.list_resources
+        resource_list = result['resources'] || []
+
+        resource_list.each do |resource|
+          cache_key = cache_key_for(server, resource.uri)
+          @resource_cache[cache_key] = resource
+          resources << resource
+        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 resources yet,
+        # raise the auth error directly to avoid cascading error messages
+        raise e if e.message.include?('Authorization failed') && resources.empty?
+
+        # Store the error and try other servers
+        connection_errors << e
+        @logger.error("Server error: #{e.message}")
+      end
+
+      # Return hash format consistent with server methods
+      { 'resources' => resources, 'nextCursor' => nil }
+    end
+
+    # Reads a specific resource by URI
+    # @param uri [String] the URI of the resource to read
+    # @param server [String, Symbol, Integer, MCPClient::ServerBase, nil] optional server to use
+    # @return [Object] the resource contents
+    def read_resource(uri, server: nil)
+      result = list_resources
+      resources = result['resources'] || []
+
+      resource = if server
+                   find_resource_on_server(uri, resources, server)
+                 else
+                   find_resource_across_servers(uri, resources)
+                 end
+
+      execute_resource_read(resource, uri)
+    end
+
     # 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
@@ -52,7 +201,8 @@ module MCPClient
 
       servers.each do |server|
         server.list_tools.each do |tool|
-          @tool_cache[tool.name] = tool
+          cache_key = cache_key_for(server, tool.name)
+          @tool_cache[cache_key] = tool
           tools << tool
         end
       rescue MCPClient::Errors::ConnectionError => e
@@ -162,6 +312,8 @@ module MCPClient
     # @return [void]
     def clear_cache
       @tool_cache.clear
+      @prompt_cache.clear
+      @resource_cache.clear
     end
 
     # Register a callback for JSON-RPC notifications from servers
@@ -312,13 +464,15 @@ module MCPClient
       case method
       when 'notifications/tools/list_changed'
         logger.warn("[#{server_id}] Tool list has changed, clearing tool cache")
-        clear_cache
+        @tool_cache.clear
       when 'notifications/resources/updated'
         logger.warn("[#{server_id}] Resource #{params['uri']} updated")
       when 'notifications/prompts/list_changed'
-        logger.warn("[#{server_id}] Prompt list has changed")
+        logger.warn("[#{server_id}] Prompt list has changed, clearing prompt cache")
+        @prompt_cache.clear
       when 'notifications/resources/list_changed'
-        logger.warn("[#{server_id}] Resource list has changed")
+        logger.warn("[#{server_id}] Resource list has changed, clearing resource cache")
+        @resource_cache.clear
       else
         # Log unknown notification types for debugging purposes
         logger.debug("[#{server_id}] Received unknown notification: #{method} - #{params}")
@@ -379,5 +533,70 @@ module MCPClient
         server.list_tools.any? { |t| t.name == tool.name }
       end
     end
+
+    # Generate a cache key for server-specific items
+    # @param server [MCPClient::ServerBase] the server
+    # @param item_id [String] the item identifier (name or URI)
+    # @return [String] composite cache key
+    def cache_key_for(server, item_id)
+      server_id = server.object_id.to_s
+      "#{server_id}:#{item_id}"
+    end
+
+    # Find a resource on a specific server
+    # @param uri [String] the URI of the resource
+    # @param resources [Array<Resource>] available resources
+    # @param server [String, Symbol, Integer, MCPClient::ServerBase] server selector
+    # @return [Resource] the found resource
+    # @raise [MCPClient::Errors::ResourceNotFound] if resource not found
+    def find_resource_on_server(uri, resources, server)
+      srv = select_server(server)
+      resource = resources.find { |r| r.uri == uri && r.server == srv }
+      unless resource
+        raise MCPClient::Errors::ResourceNotFound,
+              "Resource '#{uri}' not found on server '#{srv.name || srv.class.name}'"
+      end
+      resource
+    end
+
+    # Find a resource across all servers
+    # @param uri [String] the URI of the resource
+    # @param resources [Array<Resource>] available resources
+    # @return [Resource] the found resource
+    # @raise [MCPClient::Errors::ResourceNotFound] if resource not found
+    # @raise [MCPClient::Errors::AmbiguousResourceURI] if multiple resources found
+    def find_resource_across_servers(uri, resources)
+      matching_resources = resources.select { |r| r.uri == uri }
+
+      if matching_resources.empty?
+        raise MCPClient::Errors::ResourceNotFound, "Resource '#{uri}' not found"
+      elsif matching_resources.size > 1
+        server_names = matching_resources.map { |r| r.server&.name || 'unnamed' }
+        raise MCPClient::Errors::AmbiguousResourceURI,
+              "Multiple resources with URI '#{uri}' found across servers (#{server_names.join(', ')}). " \
+              "Please specify a server using the 'server' parameter."
+      end
+
+      matching_resources.first
+    end
+
+    # Execute the resource read operation
+    # @param resource [Resource] the resource to read
+    # @param uri [String] the URI of the resource
+    # @return [Object] the resource contents
+    # @raise [MCPClient::Errors::ServerNotFound] if no server found
+    # @raise [MCPClient::Errors::ResourceReadError] on read errors
+    def execute_resource_read(resource, uri)
+      server = resource.server
+      raise MCPClient::Errors::ServerNotFound, "No server found for resource '#{uri}'" unless server
+
+      begin
+        server.read_resource(uri)
+      rescue MCPClient::Errors::ConnectionError => e
+        server_id = server.name ? "#{server.class}[#{server.name}]" : server.class.name
+        raise MCPClient::Errors::ResourceReadError,
+              "Error reading resource '#{uri}': #{e.message} (Server: #{server_id})"
+      end
+    end
   end
 end

data/lib/mcp_client/errors.rb

@@ -9,12 +9,24 @@ module MCPClient
     # Raised when a tool is not found
     class ToolNotFound < MCPError; end
 
+    # Raised when a prompt is not found
+    class PromptNotFound < MCPError; end
+
+    # Raised when a resource is not found
+    class ResourceNotFound < MCPError; end
+
     # Raised when a server is not found
     class ServerNotFound < MCPError; end
 
     # Raised when there's an error calling a tool
     class ToolCallError < MCPError; end
 
+    # Raised when there's an error getting a prompt
+    class PromptGetError < MCPError; end
+
+    # Raised when there's an error reading a resource
+    class ResourceReadError < MCPError; end
+
     # Raised when there's a connection error with an MCP server
     class ConnectionError < MCPError; end
 
@@ -29,5 +41,11 @@ module MCPClient
 
     # Raised when multiple tools with the same name exist across different servers
     class AmbiguousToolName < MCPError; end
+
+    # Raised when multiple prompts with the same name exist across different servers
+    class AmbiguousPromptName < MCPError; end
+
+    # Raised when multiple resources with the same URI exist across different servers
+    class AmbiguousResourceURI < MCPError; end
   end
 end