ruby-mcp-client 0.8.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 27b97462ec0c99d98299df120726f90944f495aaddf198272d72725544240ec0
-  data.tar.gz: b58b8a6ba53f698abe1cb3576fba8030d66cb0bd7eafa2e39e28943e7ef1337f
+  metadata.gz: 7e0949102c5c22625bef68e2f5b4a0e2aecdfc636495ecba52d16f663c35f2fc
+  data.tar.gz: fbeb7484c1458775b88aa074422913e9d09d8a37b23aac38c7edf82e2111b9cb
 SHA512:
-  metadata.gz: 50d5791642a74f521133a057d924d3daf14e657ec617e73ad8f95510b4d97f3d52742c5a467c54d75dc02030a087f29e63ee346429271e8c80eb71cb96e38f94
-  data.tar.gz: 5f92d87a5d176e3271a11e9bbea7eafc6720107c6ae795601250e088cde69e6d6340911eecd6ea8ab32776d97d9bfb0b4d3740087509eb704cb400bf4e23e5aa
+  metadata.gz: b2e75071c0fceb5061037b1537d9e71fd8f03dc5c94aa6c2bbc2a63ce6f24ae16c1c2c2cdb560f48e12ca4115224561f89043dde2145116d1e4e397c9cb7e409
+  data.tar.gz: d3900ae79aba5d896a1496bc28af3e9ec8f0b7066f30eb0723cd1664845769dd09afd130faa2db0b4b1b67d948f15e3532cfb5abcd3b076d0e7547e7e89671fb

data/README.md

@@ -50,7 +50,7 @@ This Ruby MCP Client implements key features from the latest MCP specification (
 - **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** - Complete resources implementation for accessing files and data with URI-based identification
+- **Resources Support** - Full MCP resources specification compliance including templates, subscriptions, pagination, and annotations
 
 ## Usage
 
@@ -165,11 +165,30 @@ result = client.get_prompt('greeting', { name: 'Ruby Developer' })
 result = client.get_prompt('greeting', { name: 'Ruby Developer' }, server: 'filesystem')
 
 # === Working with Resources ===
-# List available resources from all servers
-resources = client.list_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
+# 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')
@@ -413,11 +432,16 @@ prompts.each { |prompt| puts "- #{prompt.name}: #{prompt.description}" }
 greeting = client.get_prompt('greeting', { name: 'Ruby Developer' })
 
 # List and read resources
-resources = client.list_resources
+result = client.list_resources
+resources = result['resources']
 puts "Found #{resources.length} resources:"
 resources.each { |resource| puts "- #{resource.name} (#{resource.uri})" }
 
-readme_content = client.read_resource('file:///sample/README.md')
+# 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
@@ -764,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

data/lib/mcp_client/client.rb

@@ -126,17 +126,32 @@ module MCPClient
 
     # Lists all available resources from all connected MCP servers
     # @param cache [Boolean] whether to use cached resources or fetch fresh
-    # @return [Array<MCPClient::Resource>] list of available resources
+    # @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)
-      return @resource_cache.values if cache && !@resource_cache.empty?
+    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|
-        server.list_resources.each do |resource|
+        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
@@ -152,7 +167,8 @@ module MCPClient
         @logger.error("Server error: #{e.message}")
       end
 
-      resources
+      # Return hash format consistent with server methods
+      { 'resources' => resources, 'nextCursor' => nil }
     end
 
     # Reads a specific resource by URI
@@ -160,46 +176,16 @@ module MCPClient
     # @param server [String, Symbol, Integer, MCPClient::ServerBase, nil] optional server to use
     # @return [Object] the resource contents
     def read_resource(uri, server: nil)
-      resources = list_resources
-
-      if server
-        # Use the specified server
-        srv = select_server(server)
-        # Find the resource on this specific 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
-      else
-        # Find the resource across all servers
-        matching_resources = resources.select { |r| r.uri == uri }
+      result = list_resources
+      resources = result['resources'] || []
 
-        if matching_resources.empty?
-          raise MCPClient::Errors::ResourceNotFound, "Resource '#{uri}' not found"
-        elsif matching_resources.size > 1
-          # If multiple matches, disambiguate with server names
-          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
+      resource = if server
+                   find_resource_on_server(uri, resources, server)
+                 else
+                   find_resource_across_servers(uri, resources)
+                 end
 
-        resource = matching_resources.first
-      end
-
-      # Use the resource's associated server
-      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
-        # Add server identity information to the error for better context
-        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
+      execute_resource_read(resource, uri)
     end
 
     # Lists all available tools from all connected MCP servers
@@ -478,7 +464,7 @@ 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'
@@ -556,5 +542,61 @@ module MCPClient
       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/resource_content.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module MCPClient
+  # Representation of MCP resource content
+  # Resources can contain either text or binary data
+  class ResourceContent
+    # @!attribute [r] uri
+    #   @return [String] unique identifier for the resource
+    # @!attribute [r] name
+    #   @return [String] the name of the resource
+    # @!attribute [r] title
+    #   @return [String, nil] optional human-readable name for display purposes
+    # @!attribute [r] mime_type
+    #   @return [String, nil] optional MIME type
+    # @!attribute [r] text
+    #   @return [String, nil] text content (mutually exclusive with blob)
+    # @!attribute [r] blob
+    #   @return [String, nil] base64-encoded binary content (mutually exclusive with text)
+    # @!attribute [r] annotations
+    #   @return [Hash, nil] optional annotations that provide hints to clients
+    attr_reader :uri, :name, :title, :mime_type, :text, :blob, :annotations
+
+    # Initialize resource content
+    # @param uri [String] unique identifier for the resource
+    # @param name [String] the name of the resource
+    # @param title [String, nil] optional human-readable name for display purposes
+    # @param mime_type [String, nil] optional MIME type
+    # @param text [String, nil] text content (mutually exclusive with blob)
+    # @param blob [String, nil] base64-encoded binary content (mutually exclusive with text)
+    # @param annotations [Hash, nil] optional annotations that provide hints to clients
+    def initialize(uri:, name:, title: nil, mime_type: nil, text: nil, blob: nil, annotations: nil)
+      raise ArgumentError, 'ResourceContent cannot have both text and blob' if text && blob
+      raise ArgumentError, 'ResourceContent must have either text or blob' if !text && !blob
+
+      @uri = uri
+      @name = name
+      @title = title
+      @mime_type = mime_type
+      @text = text
+      @blob = blob
+      @annotations = annotations
+    end
+
+    # Create a ResourceContent instance from JSON data
+    # @param data [Hash] JSON data from MCP server
+    # @return [MCPClient::ResourceContent] resource content instance
+    def self.from_json(data)
+      new(
+        uri: data['uri'],
+        name: data['name'],
+        title: data['title'],
+        mime_type: data['mimeType'],
+        text: data['text'],
+        blob: data['blob'],
+        annotations: data['annotations']
+      )
+    end
+
+    # Check if content is text
+    # @return [Boolean] true if content is text
+    def text?
+      !@text.nil?
+    end
+
+    # Check if content is binary
+    # @return [Boolean] true if content is binary
+    def binary?
+      !@blob.nil?
+    end
+
+    # Get the content (text or decoded blob)
+    # @return [String] the content
+    def content
+      return @text if text?
+
+      require 'base64'
+      Base64.decode64(@blob)
+    end
+  end
+end

data/lib/mcp_client/resource_template.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module MCPClient
+  # Representation of an MCP resource template
+  # Resource templates allow servers to expose parameterized resources using URI templates
+  class ResourceTemplate
+    # @!attribute [r] uri_template
+    #   @return [String] URI template following RFC 6570
+    # @!attribute [r] name
+    #   @return [String] the name of the resource template
+    # @!attribute [r] title
+    #   @return [String, nil] optional human-readable name for display purposes
+    # @!attribute [r] description
+    #   @return [String, nil] optional description
+    # @!attribute [r] mime_type
+    #   @return [String, nil] optional MIME type for resources created from this template
+    # @!attribute [r] annotations
+    #   @return [Hash, nil] optional annotations that provide hints to clients
+    # @!attribute [r] server
+    #   @return [MCPClient::ServerBase, nil] the server this resource template belongs to
+    attr_reader :uri_template, :name, :title, :description, :mime_type, :annotations, :server
+
+    # Initialize a new resource template
+    # @param uri_template [String] URI template following RFC 6570
+    # @param name [String] the name of the resource template
+    # @param title [String, nil] optional human-readable name for display purposes
+    # @param description [String, nil] optional description
+    # @param mime_type [String, nil] optional MIME type
+    # @param annotations [Hash, nil] optional annotations that provide hints to clients
+    # @param server [MCPClient::ServerBase, nil] the server this resource template belongs to
+    def initialize(uri_template:, name:, title: nil, description: nil, mime_type: nil, annotations: nil, server: nil)
+      @uri_template = uri_template
+      @name = name
+      @title = title
+      @description = description
+      @mime_type = mime_type
+      @annotations = annotations
+      @server = server
+    end
+
+    # Create a ResourceTemplate instance from JSON data
+    # @param data [Hash] JSON data from MCP server
+    # @param server [MCPClient::ServerBase, nil] the server this resource template belongs to
+    # @return [MCPClient::ResourceTemplate] resource template instance
+    def self.from_json(data, server: nil)
+      new(
+        uri_template: data['uriTemplate'],
+        name: data['name'],
+        title: data['title'],
+        description: data['description'],
+        mime_type: data['mimeType'],
+        annotations: data['annotations'],
+        server: server
+      )
+    end
+  end
+end

data/lib/mcp_client/server_base.rb

@@ -48,18 +48,46 @@ module MCPClient
     end
 
     # List all resources available from the MCP server
-    # @return [Array<MCPClient::Resource>] list of available resources
-    def list_resources
+    # @param cursor [String, nil] optional cursor for pagination
+    # @return [Hash] result containing resources array and optional nextCursor
+    def list_resources(cursor: nil)
       raise NotImplementedError, 'Subclasses must implement list_resources'
     end
 
     # Read a resource by its URI
     # @param uri [String] the URI of the resource to read
-    # @return [Object] the resource contents
+    # @return [Array<MCPClient::ResourceContent>] array of resource contents
     def read_resource(uri)
       raise NotImplementedError, 'Subclasses must implement read_resource'
     end
 
+    # List all resource templates available from the MCP server
+    # @param cursor [String, nil] optional cursor for pagination
+    # @return [Hash] result containing resourceTemplates array and optional nextCursor
+    def list_resource_templates(cursor: nil)
+      raise NotImplementedError, 'Subclasses must implement list_resource_templates'
+    end
+
+    # Subscribe to resource updates
+    # @param uri [String] the URI of the resource to subscribe to
+    # @return [Boolean] true if subscription successful
+    def subscribe_resource(uri)
+      raise NotImplementedError, 'Subclasses must implement subscribe_resource'
+    end
+
+    # Unsubscribe from resource updates
+    # @param uri [String] the URI of the resource to unsubscribe from
+    # @return [Boolean] true if unsubscription successful
+    def unsubscribe_resource(uri)
+      raise NotImplementedError, 'Subclasses must implement unsubscribe_resource'
+    end
+
+    # Get server capabilities
+    # @return [Hash, nil] server capabilities
+    def capabilities
+      raise NotImplementedError, 'Subclasses must implement capabilities'
+    end
+
     # Clean up the server connection
     def cleanup
       raise NotImplementedError, 'Subclasses must implement cleanup'

data/lib/mcp_client/server_http.rb

@@ -216,6 +216,148 @@ module MCPClient
       end
     end
 
+    # List all prompts available from the MCP server
+    # @return [Array<MCPClient::Prompt>] list of available prompts
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    # @raise [MCPClient::Errors::TransportError] if response isn't valid JSON
+    # @raise [MCPClient::Errors::PromptGetError] for other errors during prompt listing
+    def list_prompts
+      @mutex.synchronize do
+        return @prompts if @prompts
+      end
+
+      begin
+        ensure_connected
+
+        prompts_data = rpc_request('prompts/list')
+        prompts = prompts_data['prompts'] || []
+
+        @mutex.synchronize do
+          @prompts = prompts.map do |prompt_data|
+            MCPClient::Prompt.from_json(prompt_data, server: self)
+          end
+        end
+
+        @mutex.synchronize { @prompts }
+      rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+        raise
+      rescue StandardError => e
+        raise MCPClient::Errors::PromptGetError, "Error listing prompts: #{e.message}"
+      end
+    end
+
+    # Get a prompt 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
+    # @return [Object] the result of the prompt interpolation
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    # @raise [MCPClient::Errors::TransportError] if response isn't valid JSON
+    # @raise [MCPClient::Errors::PromptGetError] for other errors during prompt interpolation
+    def get_prompt(prompt_name, parameters)
+      rpc_request('prompts/get', {
+                    name: prompt_name,
+                    arguments: parameters
+                  })
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
+      raise
+    rescue StandardError => e
+      raise MCPClient::Errors::PromptGetError, "Error getting prompt '#{prompt_name}': #{e.message}"
+    end
+
+    # List all resources available from the MCP server
+    # @param cursor [String, nil] optional cursor for pagination
+    # @return [Hash] result containing resources array and optional nextCursor
+    # @raise [MCPClient::Errors::ResourceReadError] if resources list retrieval fails
+    def list_resources(cursor: nil)
+      @mutex.synchronize do
+        return @resources_result if @resources_result && !cursor
+      end
+
+      begin
+        ensure_connected
+
+        params = {}
+        params['cursor'] = cursor if cursor
+        result = rpc_request('resources/list', params)
+
+        resources = (result['resources'] || []).map do |resource_data|
+          MCPClient::Resource.from_json(resource_data, server: self)
+        end
+
+        resources_result = { 'resources' => resources, 'nextCursor' => result['nextCursor'] }
+
+        @mutex.synchronize do
+          @resources_result = resources_result unless cursor
+        end
+
+        resources_result
+      rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+        raise
+      rescue StandardError => e
+        raise MCPClient::Errors::ResourceReadError, "Error listing resources: #{e.message}"
+      end
+    end
+
+    # Read a resource by its URI
+    # @param uri [String] the URI of the resource to read
+    # @return [Array<MCPClient::ResourceContent>] array of resource contents
+    # @raise [MCPClient::Errors::ResourceReadError] if resource reading fails
+    def read_resource(uri)
+      result = rpc_request('resources/read', { uri: uri })
+      contents = result['contents'] || []
+      contents.map { |content| MCPClient::ResourceContent.from_json(content) }
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
+      raise
+    rescue StandardError => e
+      raise MCPClient::Errors::ResourceReadError, "Error reading resource '#{uri}': #{e.message}"
+    end
+
+    # List all resource templates available from the MCP server
+    # @param cursor [String, nil] optional cursor for pagination
+    # @return [Hash] result containing resourceTemplates array and optional nextCursor
+    # @raise [MCPClient::Errors::ResourceReadError] for other errors during resource template listing
+    def list_resource_templates(cursor: nil)
+      params = {}
+      params['cursor'] = cursor if cursor
+      result = rpc_request('resources/templates/list', params)
+
+      templates = (result['resourceTemplates'] || []).map do |template_data|
+        MCPClient::ResourceTemplate.from_json(template_data, server: self)
+      end
+
+      { 'resourceTemplates' => templates, 'nextCursor' => result['nextCursor'] }
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+      raise
+    rescue StandardError => e
+      raise MCPClient::Errors::ResourceReadError, "Error listing resource templates: #{e.message}"
+    end
+
+    # Subscribe to resource updates
+    # @param uri [String] the URI of the resource to subscribe to
+    # @return [Boolean] true if subscription successful
+    # @raise [MCPClient::Errors::ResourceReadError] for other errors during subscription
+    def subscribe_resource(uri)
+      rpc_request('resources/subscribe', { uri: uri })
+      true
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+      raise
+    rescue StandardError => e
+      raise MCPClient::Errors::ResourceReadError, "Error subscribing to resource '#{uri}': #{e.message}"
+    end
+
+    # Unsubscribe from resource updates
+    # @param uri [String] the URI of the resource to unsubscribe from
+    # @return [Boolean] true if unsubscription successful
+    # @raise [MCPClient::Errors::ResourceReadError] for other errors during unsubscription
+    def unsubscribe_resource(uri)
+      rpc_request('resources/unsubscribe', { uri: uri })
+      true
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+      raise
+    rescue StandardError => e
+      raise MCPClient::Errors::ResourceReadError, "Error unsubscribing from resource '#{uri}': #{e.message}"
+    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

data/lib/mcp_client/server_sse.rb

@@ -161,26 +161,34 @@ module MCPClient
     end
 
     # List all resources available from the MCP server
-    # @return [Array<MCPClient::Resource>] list of available resources
+    # @param cursor [String, nil] optional cursor for pagination
+    # @return [Hash] result containing resources array and optional nextCursor
     # @raise [MCPClient::Errors::ServerError] if server returns an error
     # @raise [MCPClient::Errors::TransportError] if response isn't valid JSON
     # @raise [MCPClient::Errors::ResourceReadError] for other errors during resource listing
-    def list_resources
+    def list_resources(cursor: nil)
       @mutex.synchronize do
-        return @resources if @resources
+        return @resources_result if @resources_result && !cursor
       end
 
       begin
         ensure_initialized
 
-        resources_data = request_resources_list
+        params = {}
+        params['cursor'] = cursor if cursor
+        result = rpc_request('resources/list', params)
+
+        resources = (result['resources'] || []).map do |resource_data|
+          MCPClient::Resource.from_json(resource_data, server: self)
+        end
+
+        resources_result = { 'resources' => resources, 'nextCursor' => result['nextCursor'] }
+
         @mutex.synchronize do
-          @resources = resources_data.map do |resource_data|
-            MCPClient::Resource.from_json(resource_data, server: self)
-          end
+          @resources_result = resources_result unless cursor
         end
 
-        @mutex.synchronize { @resources }
+        resources_result
       rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
         # Re-raise these errors directly
         raise
@@ -191,15 +199,15 @@ module MCPClient
 
     # Read a resource by its URI
     # @param uri [String] the URI of the resource to read
-    # @return [Object] the resource contents
+    # @return [Array<MCPClient::ResourceContent>] array of resource contents
     # @raise [MCPClient::Errors::ServerError] if server returns an error
     # @raise [MCPClient::Errors::TransportError] if response isn't valid JSON
     # @raise [MCPClient::Errors::ResourceReadError] for other errors during resource reading
     # @raise [MCPClient::Errors::ConnectionError] if server is disconnected
     def read_resource(uri)
-      rpc_request('resources/read', {
-                    uri: uri
-                  })
+      result = rpc_request('resources/read', { uri: uri })
+      contents = result['contents'] || []
+      contents.map { |content| MCPClient::ResourceContent.from_json(content) }
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
       # Re-raise connection/transport errors directly to match test expectations
       raise
@@ -208,6 +216,58 @@ module MCPClient
       raise MCPClient::Errors::ResourceReadError, "Error reading resource '#{uri}': #{e.message}"
     end
 
+    # List all resource templates available from the MCP server
+    # @param cursor [String, nil] optional cursor for pagination
+    # @return [Hash] result containing resourceTemplates array and optional nextCursor
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    # @raise [MCPClient::Errors::ResourceReadError] for other errors during resource template listing
+    def list_resource_templates(cursor: nil)
+      ensure_initialized
+      params = {}
+      params['cursor'] = cursor if cursor
+      result = rpc_request('resources/templates/list', params)
+
+      templates = (result['resourceTemplates'] || []).map do |template_data|
+        MCPClient::ResourceTemplate.from_json(template_data, server: self)
+      end
+
+      { 'resourceTemplates' => templates, 'nextCursor' => result['nextCursor'] }
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+      raise
+    rescue StandardError => e
+      raise MCPClient::Errors::ResourceReadError, "Error listing resource templates: #{e.message}"
+    end
+
+    # Subscribe to resource updates
+    # @param uri [String] the URI of the resource to subscribe to
+    # @return [Boolean] true if subscription successful
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    # @raise [MCPClient::Errors::ResourceReadError] for other errors during subscription
+    def subscribe_resource(uri)
+      ensure_initialized
+      rpc_request('resources/subscribe', { uri: uri })
+      true
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+      raise
+    rescue StandardError => e
+      raise MCPClient::Errors::ResourceReadError, "Error subscribing to resource '#{uri}': #{e.message}"
+    end
+
+    # Unsubscribe from resource updates
+    # @param uri [String] the URI of the resource to unsubscribe from
+    # @return [Boolean] true if unsubscription successful
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    # @raise [MCPClient::Errors::ResourceReadError] for other errors during unsubscription
+    def unsubscribe_resource(uri)
+      ensure_initialized
+      rpc_request('resources/unsubscribe', { uri: uri })
+      true
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+      raise
+    rescue StandardError => e
+      raise MCPClient::Errors::ResourceReadError, "Error unsubscribing from resource '#{uri}': #{e.message}"
+    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

data/lib/mcp_client/server_stdio/json_rpc_transport.rb

@@ -34,6 +34,11 @@ module MCPClient
           raise MCPClient::Errors::ConnectionError, "Initialize failed: #{err['message']}"
         end
 
+        # Store server info and capabilities
+        result = res['result'] || {}
+        @server_info = result['serverInfo']
+        @capabilities = result['capabilities']
+
         # Send initialized notification
         notif = build_jsonrpc_notification('notifications/initialized', {})
         @stdin.puts(notif.to_json)

data/lib/mcp_client/server_stdio.rb

@@ -39,6 +39,8 @@ module MCPClient
       @next_id = 1
       @pending = {}
       @initialized = false
+      @server_info = nil
+      @capabilities = nil
       initialize_logger(logger)
       @max_retries   = retries
       @retry_backoff = retry_backoff
@@ -46,6 +48,14 @@ module MCPClient
       @env           = env || {}
     end
 
+    # Server info from the initialize response
+    # @return [Hash, nil] Server information
+    attr_reader :server_info
+
+    # Server capabilities from the initialize response
+    # @return [Hash, nil] Server capabilities
+    attr_reader :capabilities
+
     # Connect to the MCP server by launching the command process via stdin/stdout
     # @return [Boolean] true if connection was successful
     # @raise [MCPClient::Errors::ConnectionError] if connection fails
@@ -149,27 +159,32 @@ module MCPClient
     end
 
     # List all resources available from the MCP server
-    # @return [Array<MCPClient::Resource>] list of available resources
+    # @param cursor [String, nil] optional cursor for pagination
+    # @return [Hash] result containing resources array and optional nextCursor
     # @raise [MCPClient::Errors::ServerError] if server returns an error
     # @raise [MCPClient::Errors::ResourceReadError] for other errors during resource listing
-    def list_resources
+    def list_resources(cursor: nil)
       ensure_initialized
       req_id = next_id
-      req = { 'jsonrpc' => '2.0', 'id' => req_id, 'method' => 'resources/list', 'params' => {} }
+      params = {}
+      params['cursor'] = cursor if cursor
+      req = { 'jsonrpc' => '2.0', 'id' => req_id, 'method' => 'resources/list', 'params' => params }
       send_request(req)
       res = wait_response(req_id)
       if (err = res['error'])
         raise MCPClient::Errors::ServerError, err['message']
       end
 
-      (res.dig('result', 'resources') || []).map { |td| MCPClient::Resource.from_json(td, server: self) }
+      result = res['result'] || {}
+      resources = (result['resources'] || []).map { |td| MCPClient::Resource.from_json(td, server: self) }
+      { 'resources' => resources, 'nextCursor' => result['nextCursor'] }
     rescue StandardError => e
       raise MCPClient::Errors::ResourceReadError, "Error listing resources: #{e.message}"
     end
 
     # Read a resource by its URI
     # @param uri [String] the URI of the resource to read
-    # @return [Object] the resource contents
+    # @return [Array<MCPClient::ResourceContent>] array of resource contents
     # @raise [MCPClient::Errors::ServerError] if server returns an error
     # @raise [MCPClient::Errors::ResourceReadError] for other errors during resource reading
     def read_resource(uri)
@@ -188,11 +203,87 @@ module MCPClient
         raise MCPClient::Errors::ServerError, err['message']
       end
 
-      res['result']
+      result = res['result'] || {}
+      contents = result['contents'] || []
+      contents.map { |content| MCPClient::ResourceContent.from_json(content) }
     rescue StandardError => e
       raise MCPClient::Errors::ResourceReadError, "Error reading resource '#{uri}': #{e.message}"
     end
 
+    # List all resource templates available from the MCP server
+    # @param cursor [String, nil] optional cursor for pagination
+    # @return [Hash] result containing resourceTemplates array and optional nextCursor
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    # @raise [MCPClient::Errors::ResourceReadError] for other errors during resource template listing
+    def list_resource_templates(cursor: nil)
+      ensure_initialized
+      req_id = next_id
+      params = {}
+      params['cursor'] = cursor if cursor
+      req = { 'jsonrpc' => '2.0', 'id' => req_id, 'method' => 'resources/templates/list', 'params' => params }
+      send_request(req)
+      res = wait_response(req_id)
+      if (err = res['error'])
+        raise MCPClient::Errors::ServerError, err['message']
+      end
+
+      result = res['result'] || {}
+      templates = (result['resourceTemplates'] || []).map { |td| MCPClient::ResourceTemplate.from_json(td, server: self) }
+      { 'resourceTemplates' => templates, 'nextCursor' => result['nextCursor'] }
+    rescue StandardError => e
+      raise MCPClient::Errors::ResourceReadError, "Error listing resource templates: #{e.message}"
+    end
+
+    # Subscribe to resource updates
+    # @param uri [String] the URI of the resource to subscribe to
+    # @return [Boolean] true if subscription successful
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    # @raise [MCPClient::Errors::ResourceReadError] for other errors during subscription
+    def subscribe_resource(uri)
+      ensure_initialized
+      req_id = next_id
+      req = {
+        'jsonrpc' => '2.0',
+        'id' => req_id,
+        'method' => 'resources/subscribe',
+        'params' => { 'uri' => uri }
+      }
+      send_request(req)
+      res = wait_response(req_id)
+      if (err = res['error'])
+        raise MCPClient::Errors::ServerError, err['message']
+      end
+
+      true
+    rescue StandardError => e
+      raise MCPClient::Errors::ResourceReadError, "Error subscribing to resource '#{uri}': #{e.message}"
+    end
+
+    # Unsubscribe from resource updates
+    # @param uri [String] the URI of the resource to unsubscribe from
+    # @return [Boolean] true if unsubscription successful
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    # @raise [MCPClient::Errors::ResourceReadError] for other errors during unsubscription
+    def unsubscribe_resource(uri)
+      ensure_initialized
+      req_id = next_id
+      req = {
+        'jsonrpc' => '2.0',
+        'id' => req_id,
+        'method' => 'resources/unsubscribe',
+        'params' => { 'uri' => uri }
+      }
+      send_request(req)
+      res = wait_response(req_id)
+      if (err = res['error'])
+        raise MCPClient::Errors::ServerError, err['message']
+      end
+
+      true
+    rescue StandardError => e
+      raise MCPClient::Errors::ResourceReadError, "Error unsubscribing from resource '#{uri}': #{e.message}"
+    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

data/lib/mcp_client/server_streamable_http.rb

@@ -262,24 +262,32 @@ module MCPClient
     end
 
     # List all resources available from the MCP server
-    # @return [Array<MCPClient::Resource>] list of available resources
+    # @param cursor [String, nil] optional cursor for pagination
+    # @return [Hash] result containing resources array and optional nextCursor
     # @raise [MCPClient::Errors::ResourceReadError] if resources list retrieval fails
-    def list_resources
+    def list_resources(cursor: nil)
       @mutex.synchronize do
-        return @resources if @resources
+        return @resources_result if @resources_result && !cursor
       end
 
       begin
         ensure_connected
 
-        resources_data = request_resources_list
+        params = {}
+        params['cursor'] = cursor if cursor
+        result = rpc_request('resources/list', params)
+
+        resources = (result['resources'] || []).map do |resource_data|
+          MCPClient::Resource.from_json(resource_data, server: self)
+        end
+
+        resources_result = { 'resources' => resources, 'nextCursor' => result['nextCursor'] }
+
         @mutex.synchronize do
-          @resources = resources_data.map do |resource_data|
-            MCPClient::Resource.from_json(resource_data, server: self)
-          end
+          @resources_result = resources_result unless cursor
         end
 
-        @mutex.synchronize { @resources }
+        resources_result
       rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
         # Re-raise these errors directly
         raise
@@ -290,10 +298,12 @@ module MCPClient
 
     # Read a resource by its URI
     # @param uri [String] the URI of the resource to read
-    # @return [Object] the resource contents
+    # @return [Array<MCPClient::ResourceContent>] array of resource contents
     # @raise [MCPClient::Errors::ResourceReadError] if resource reading fails
     def read_resource(uri)
-      rpc_request('resources/read', { uri: uri })
+      result = rpc_request('resources/read', { uri: uri })
+      contents = result['contents'] || []
+      contents.map { |content| MCPClient::ResourceContent.from_json(content) }
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
       # Re-raise connection/transport errors directly
       raise
@@ -302,6 +312,52 @@ module MCPClient
       raise MCPClient::Errors::ResourceReadError, "Error reading resource '#{uri}': #{e.message}"
     end
 
+    # List all resource templates available from the MCP server
+    # @param cursor [String, nil] optional cursor for pagination
+    # @return [Hash] result containing resourceTemplates array and optional nextCursor
+    # @raise [MCPClient::Errors::ResourceReadError] for other errors during resource template listing
+    def list_resource_templates(cursor: nil)
+      params = {}
+      params['cursor'] = cursor if cursor
+      result = rpc_request('resources/templates/list', params)
+
+      templates = (result['resourceTemplates'] || []).map do |template_data|
+        MCPClient::ResourceTemplate.from_json(template_data, server: self)
+      end
+
+      { 'resourceTemplates' => templates, 'nextCursor' => result['nextCursor'] }
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+      raise
+    rescue StandardError => e
+      raise MCPClient::Errors::ResourceReadError, "Error listing resource templates: #{e.message}"
+    end
+
+    # Subscribe to resource updates
+    # @param uri [String] the URI of the resource to subscribe to
+    # @return [Boolean] true if subscription successful
+    # @raise [MCPClient::Errors::ResourceReadError] for other errors during subscription
+    def subscribe_resource(uri)
+      rpc_request('resources/subscribe', { uri: uri })
+      true
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+      raise
+    rescue StandardError => e
+      raise MCPClient::Errors::ResourceReadError, "Error subscribing to resource '#{uri}': #{e.message}"
+    end
+
+    # Unsubscribe from resource updates
+    # @param uri [String] the URI of the resource to unsubscribe from
+    # @return [Boolean] true if unsubscription successful
+    # @raise [MCPClient::Errors::ResourceReadError] for other errors during unsubscription
+    def unsubscribe_resource(uri)
+      rpc_request('resources/unsubscribe', { uri: uri })
+      true
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+      raise
+    rescue StandardError => e
+      raise MCPClient::Errors::ResourceReadError, "Error unsubscribing from resource '#{uri}': #{e.message}"
+    end
+
     # Override apply_request_headers to add session and SSE headers for MCP protocol
     def apply_request_headers(req, request)
       super

data/lib/mcp_client/version.rb

@@ -2,7 +2,7 @@
 
 module MCPClient
   # Current version of the MCP client gem
-  VERSION = '0.8.0'
+  VERSION = '0.8.1'
 
   # MCP protocol version (date-based) - unified across all transports
   PROTOCOL_VERSION = '2025-03-26'

data/lib/mcp_client.rb

@@ -5,6 +5,8 @@ require_relative 'mcp_client/errors'
 require_relative 'mcp_client/tool'
 require_relative 'mcp_client/prompt'
 require_relative 'mcp_client/resource'
+require_relative 'mcp_client/resource_template'
+require_relative 'mcp_client/resource_content'
 require_relative 'mcp_client/server_base'
 require_relative 'mcp_client/server_stdio'
 require_relative 'mcp_client/server_sse'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-mcp-client
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.1
 platform: ruby
 authors:
 - Szymon Kurcab
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-09-16 00:00:00.000000000 Z
+date: 2025-09-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -129,6 +129,8 @@ files:
 - lib/mcp_client/oauth_client.rb
 - lib/mcp_client/prompt.rb
 - lib/mcp_client/resource.rb
+- lib/mcp_client/resource_content.rb
+- lib/mcp_client/resource_template.rb
 - lib/mcp_client/server_base.rb
 - lib/mcp_client/server_factory.rb
 - lib/mcp_client/server_http.rb