ruby-mcp-client 0.7.3 → 0.8.1

data/lib/mcp_client/prompt.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module MCPClient
+  # Representation of an MCP prompt
+  class Prompt
+    # @!attribute [r] name
+    #   @return [String] the name of the prompt
+    # @!attribute [r] description
+    #   @return [String] the description of the prompt
+    # @!attribute [r] arguments
+    #   @return [Hash] the JSON arguments for the prompt
+    # @!attribute [r] server
+    #   @return [MCPClient::ServerBase, nil] the server this prompt belongs to
+    attr_reader :name, :description, :arguments, :server
+
+    # Initialize a new prompt
+    # @param name [String] the name of the prompt
+    # @param description [String] the description of the prompt
+    # @param arguments [Hash] the JSON arguments for the prompt
+    # @param server [MCPClient::ServerBase, nil] the server this prompt belongs to
+    def initialize(name:, description:, arguments: {}, server: nil)
+      @name = name
+      @description = description
+      @arguments = arguments
+      @server = server
+    end
+
+    # Create a Prompt instance from JSON data
+    # @param data [Hash] JSON data from MCP server
+    # @param server [MCPClient::ServerBase, nil] the server this prompt belongs to
+    # @return [MCPClient::Prompt] prompt instance
+    def self.from_json(data, server: nil)
+      new(
+        name: data['name'],
+        description: data['description'],
+        arguments: data['arguments'] || {},
+        server: server
+      )
+    end
+  end
+end

data/lib/mcp_client/resource.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module MCPClient
+  # Representation of an MCP resource
+  class Resource
+    # @!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 of the resource for display purposes
+    # @!attribute [r] description
+    #   @return [String, nil] optional description
+    # @!attribute [r] mime_type
+    #   @return [String, nil] optional MIME type
+    # @!attribute [r] size
+    #   @return [Integer, nil] optional size in bytes
+    # @!attribute [r] annotations
+    #   @return [Hash, nil] optional annotations that provide hints to clients
+    # @!attribute [r] server
+    #   @return [MCPClient::ServerBase, nil] the server this resource belongs to
+    attr_reader :uri, :name, :title, :description, :mime_type, :size, :annotations, :server
+
+    # Initialize a new resource
+    # @param uri [String] unique identifier for the resource
+    # @param name [String] the name of the resource
+    # @param title [String, nil] optional human-readable name of the resource for display purposes
+    # @param description [String, nil] optional description
+    # @param mime_type [String, nil] optional MIME type
+    # @param size [Integer, nil] optional size in bytes
+    # @param annotations [Hash, nil] optional annotations that provide hints to clients
+    # @param server [MCPClient::ServerBase, nil] the server this resource belongs to
+    def initialize(uri:, name:, title: nil, description: nil, mime_type: nil, size: nil, annotations: nil, server: nil)
+      @uri = uri
+      @name = name
+      @title = title
+      @description = description
+      @mime_type = mime_type
+      @size = size
+      @annotations = annotations
+      @server = server
+    end
+
+    # Create a Resource instance from JSON data
+    # @param data [Hash] JSON data from MCP server
+    # @param server [MCPClient::ServerBase, nil] the server this resource belongs to
+    # @return [MCPClient::Resource] resource instance
+    def self.from_json(data, server: nil)
+      new(
+        uri: data['uri'],
+        name: data['name'],
+        title: data['title'],
+        description: data['description'],
+        mime_type: data['mimeType'],
+        size: data['size'],
+        annotations: data['annotations'],
+        server: server
+      )
+    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

@@ -33,6 +33,61 @@ module MCPClient
       raise NotImplementedError, 'Subclasses must implement call_tool'
     end
 
+    # List all prompts available from the MCP server
+    # @return [Array<MCPClient::Prompt>] list of available prompts
+    def list_prompts
+      raise NotImplementedError, 'Subclasses must implement list_prompts'
+    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
+    def get_prompt(prompt_name, parameters)
+      raise NotImplementedError, 'Subclasses must implement get_prompt'
+    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
+    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 [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/json_rpc_transport.rb

@@ -7,6 +7,7 @@ module MCPClient
     # JSON-RPC request/notification plumbing for SSE transport
     module JsonRpcTransport
       include JsonRpcCommon
+
       # Generic JSON-RPC request: send method with params and return result
       # @param method [String] JSON-RPC method name
       # @param params [Hash] parameters for the request