actionmcp 0.19.1 → 0.22.0

data/lib/action_mcp/client/catalog.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module Client
+    # Catalog
+    #
+    # A collection that manages and provides access to resources.
+    # This class stores resource definitions and provides methods for
+    # retrieving, filtering, and accessing resources by URI or other attributes.
+    # It supports lazy loading of resources when initialized with a client.
+    #
+    # Example usage:
+    #   # Eager loading
+    #   resources_data = client.list_resources # Returns array of resource definitions
+    #   catalog = Catalog.new(resources_data)
+    #
+    #   # Lazy loading
+    #   catalog = Catalog.new([], client)
+    #   resources = catalog.all # Resources are loaded here
+    #
+    #   # Access a specific resource by URI
+    #   main_file = catalog.find_by_uri("file:///project/src/main.rs")
+    #
+    #   # Get all resources matching a criteria
+    #   rust_files = catalog.filter { |r| r.mime_type == "text/x-rust" }
+    #
+    class Catalog
+      # Initialize a new Catalog with resource definitions
+      #
+      # @param resources [Array<Hash>] Array of resource definition hashes, each containing
+      #   uri, name, description, and mimeType keys
+      # @param client [Object, nil] Optional client for lazy loading of resources
+      attr_reader :client
+
+      def initialize(resources, client)
+        self.resources = resources
+        @client = client
+        @loaded = !resources.empty?
+      end
+
+      # Return all resources in the collection. If initialized with a client and resources
+      # haven't been loaded yet, this will trigger lazy loading from the client.
+      #
+      # @return [Array<Resource>] All resource objects in the collection
+      def all
+        load_resources unless @loaded
+        @resources
+      end
+
+      # Force reload all resources from the client and return them
+      #
+      # @return [Array<Resource>] All resource objects in the collection
+      def all!
+        load_resources(force: true)
+        @resources
+      end
+
+      # Find a resource by URI
+      #
+      # @param uri [String] URI of the resource to find
+      # @return [Resource, nil] The resource with the given URI, or nil if not found
+      def find_by_uri(uri)
+        all.find { |resource| resource.uri == uri }
+      end
+
+      # Find resources by name
+      #
+      # @param name [String] Name of the resources to find
+      # @return [Array<Resource>] Resources with the given name
+      def find_by_name(name)
+        all.select { |resource| resource.name == name }
+      end
+
+      # Find resources by MIME type
+      #
+      # @param mime_type [String] MIME type to search for
+      # @return [Array<Resource>] Resources with the given MIME type
+      def find_by_mime_type(mime_type)
+        all.select { |resource| resource.mime_type == mime_type }
+      end
+
+      # Filter resources based on a given block
+      #
+      # @yield [resource] Block that determines whether to include a resource
+      # @yieldparam resource [Resource] A resource from the collection
+      # @yieldreturn [Boolean] true to include the resource, false to exclude it
+      # @return [Array<Resource>] Resources that match the filter criteria
+      def filter(&block)
+        all.select(&block)
+      end
+
+      # Get a list of all resource URIs
+      #
+      # @return [Array<String>] URIs of all resources in the collection
+      def uris
+        all.map(&:uri)
+      end
+
+      # Number of resources in the collection
+      #
+      # @return [Integer] The number of resources
+      def size
+        all.size
+      end
+
+      # Check if the collection contains a resource with the given URI
+      #
+      # @param uri [String] The resource URI to check for
+      # @return [Boolean] true if a resource with the URI exists
+      def contains_uri?(uri)
+        all.any? { |resource| resource.uri == uri }
+      end
+
+      # Group resources by MIME type
+      #
+      # @return [Hash<String, Array<Resource>>] Hash mapping MIME types to arrays of resources
+      def group_by_mime_type
+        all.group_by(&:mime_type)
+      end
+
+      # Search resources by keyword in name or description
+      #
+      # @param keyword [String] Keyword to search for
+      # @return [Array<Resource>] Resources matching the search term
+      def search(keyword)
+        keyword = keyword.downcase
+        all.select do |resource|
+          resource.name.downcase.include?(keyword) ||
+            (resource.description && resource.description.downcase.include?(keyword))
+        end
+      end
+
+      # Implements enumerable functionality for the collection
+      include Enumerable
+
+      # Yield each resource in the collection to the given block
+      #
+      # @yield [resource] Block to execute for each resource
+      # @yieldparam resource [Resource] A resource from the collection
+      # @return [Enumerator] If no block is given
+      def each(&block)
+        all.each(&block)
+      end
+
+      # Convert raw resource data into Resource objects
+      #
+      # @param raw_resources [Array<Hash>] Array of resource definition hashes
+      def resources=(raw_resources)
+        @resources = raw_resources.map { |resource_data| Resource.new(resource_data) }
+      end
+
+      private
+
+      # Load or reload resources using the client
+      #
+      # @param force [Boolean] Whether to force reload even if resources are already loaded
+      # @return [void]
+      def load_resources(force: false)
+        return if @loaded && !force
+
+        begin
+          @client.list_resources
+          @loaded = true
+        rescue StandardError => e
+          Rails.logger.error("Failed to load resources: #{e.message}")
+          @loaded = true unless @resources.empty?
+        end
+      end
+
+      # Internal Resource class to represent individual resources
+      class Resource
+        attr_reader :uri, :name, :description, :mime_type
+
+        # Initialize a new Resource instance
+        #
+        # @param data [Hash] Resource definition hash containing uri, name, description, and mimeType
+        def initialize(data = [])
+          @uri = data["uri"]
+          @name = data["name"]
+          @description = data["description"]
+          @mime_type = data["mimeType"]
+        end
+
+        # Get the file extension from the resource name
+        #
+        # @return [String, nil] The file extension or nil if no extension
+        def extension
+          File.extname(@name)[1..-1] if @name.include?(".")
+        end
+
+        # Check if this resource is a text file based on MIME type
+        #
+        # @return [Boolean] true if the resource is a text file
+        def text?
+          @mime_type&.start_with?("text/")
+        end
+
+        # Check if this resource is an image based on MIME type
+        #
+        # @return [Boolean] true if the resource is an image
+        def image?
+          @mime_type&.start_with?("image/")
+        end
+
+        # Get the path portion of the URI
+        #
+        # @return [String, nil] The path component of the URI
+        def path
+          URI(@uri).path rescue nil
+        end
+
+        # Generate a hash representation of the resource
+        #
+        # @return [Hash] Hash containing resource details
+        def to_h
+          {
+            "uri" => @uri,
+            "name" => @name,
+            "description" => @description,
+            "mimeType" => @mime_type
+          }
+        end
+      end
+    end
+  end
+end

data/lib/action_mcp/client/json_rpc_handler.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module Client
+    class JsonRpcHandler < JsonRpcHandlerBase
+      attr_reader :client
+      def initialize(transport, client)
+        super(transport)
+        @client = client
+      end
+
+      protected
+
+      # Handle client-specific methods
+      # @param rpc_method [String]
+      # @param id [String, Integer]
+      # @param params [Hash]
+      def handle_method(rpc_method, id, params)
+        puts "\e[31mUnknown server method: #{rpc_method} #{id} #{params}\e[0m"
+      end
+
+      # @param rpc_method [String]
+      # @param id [String]
+      def process_roots(rpc_method, id)
+        case rpc_method
+        when "roots/list" # List available roots
+          transport.send_roots_list(id)
+        else
+          Rails.logger.warn("Unknown roots method: #{rpc_method}")
+        end
+      end
+
+      # @param rpc_method [String]
+      # @param id [String]
+      # @param params [Hash]
+      def process_sampling(rpc_method, id, params)
+        case rpc_method
+        when "sampling/createMessage" # Create a message using AI
+          # @param id [String]
+          # @param params [SamplingRequest]
+          transport.send_sampling_create_message(id, params)
+        else
+          Rails.logger.warn("Unknown sampling method: #{rpc_method}")
+        end
+      end
+
+      # @param rpc_method [String]
+      def process_notifications(rpc_method, params)
+        case rpc_method
+        when "notifications/resources/updated" # Resource update notification
+          puts "\e[31m Resource #{params['uri']} was updated\e[0m"
+          # Handle resource update notification
+          # TODO: fetch updated resource or mark it as stale
+        when "notifications/tools/list_changed" # Tool list change notification
+          puts "\e[31m Tool list has changed\e[0m"
+          # Handle tool list change notification
+          # TODO: fetch new tools or mark them as stale
+        when "notifications/prompts/list_changed" # Prompt list change notification
+          puts "\e[31m Prompt list has changed\e[0m"
+          # Handle prompt list change notification
+          # TODO: fetch new prompts or mark them as stale
+        when "notifications/resources/list_changed" # Resource list change notification
+          puts "\e[31m Resource list has changed\e[0m"
+          # Handle resource list change notification
+          # TODO: fetch new resources or mark them as stale
+        else
+          super
+        end
+      end
+
+      def process_response(id, result)
+        if transport.id == id
+          ## This initialize the transport
+          client.server = Client::Server.new(result)
+          return send_initialized_notification
+        end
+        request = transport.messages.requests.find_by(jsonrpc_id: id)
+        return unless request
+        case request.rpc_method
+        when "tools/list"
+           client.toolbox.tools = result["tools"]
+           return client.toolbox.all
+        when "prompts/list"
+          client.prompt_book.prompts = result["prompts"]
+          return client.prompt_book.all
+        when "resources/list"
+          client.catalog.resources = result["resources"]
+          return client.catalog.all
+        when "resources/templates/list"
+          client.blueprint.templates = result["resourceTemplates"]
+          return client.blueprint.all
+        end
+
+        puts "\e[31mUnknown response: #{id} #{result}\e[0m"
+      end
+
+      def process_error(id, error)
+        # Do something ?
+        puts "\e[31mUnknown error: #{id} #{error}\e[0m"
+      end
+
+
+      def send_initialized_notification
+        transport.initialize!
+        client.send_jsonrpc_notification("notifications/initialized")
+      end
+    end
+  end
+end

data/lib/action_mcp/client/logging.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module Client
+    module Logging
+      # Set the client's logging level
+      # @param level [String] Logging level (debug, info, warning, error, etc.)
+      # @return [Boolean] Success status
+      def set_logging_level(level)
+        request_id = SecureRandom.uuid_v7
+
+        # Send request
+        send_jsonrpc_request("client/setLoggingLevel",
+                             params: { level: level },
+                             id: request_id
+        )
+      end
+    end
+  end
+end

data/lib/action_mcp/{transport → client}/messaging.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module ActionMCP
-  module Transport
+  module Client
     module Messaging
       def send_jsonrpc_request(method, params: nil, id: SecureRandom.uuid_v7)
         request = JsonRpc::Request.new(id: id, method: method, params: params)

data/lib/action_mcp/client/prompt_book.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module Client
+    # PromptBook
+    #
+    # A collection that manages and provides access to prompt templates from the MCP server.
+    # The class stores prompt definitions along with their arguments and provides methods
+    # for retrieving, filtering, and accessing prompts. It supports lazy loading of prompts
+    # when initialized with a client.
+    #
+    # Example usage:
+    #   # Eager loading
+    #   prompts_data = client.list_prompts # Returns array of prompt definitions
+    #   book = PromptBook.new(prompts_data)
+    #
+    #   # Lazy loading
+    #   book = PromptBook.new([], client)
+    #   prompts = book.all # Prompts are loaded here
+    #
+    #   # Access a specific prompt by name
+    #   summary_prompt = book.find("summarize_text")
+    #
+    #   # Get all prompts matching a criteria
+    #   text_prompts = book.filter { |p| p.name.include?("text") }
+    #
+    class PromptBook
+      # Initialize a new PromptBook with prompt definitions
+      #
+      # @param prompts [Array<Hash>] Array of prompt definition hashes, each containing
+      #   name, description, and arguments keys
+      # @param client [Object, nil] Optional client for lazy loading of prompts
+      attr_reader :client
+
+      def initialize(prompts, client)
+        self.prompts = prompts
+        @client = client
+        @loaded = !prompts.empty?
+      end
+
+      # Return all prompts in the collection. If initialized with a client and prompts
+      # haven't been loaded yet, this will trigger lazy loading from the client.
+      #
+      # @return [Array<Prompt>] All prompt objects in the collection
+      def all
+        load_prompts unless @loaded
+        @prompts
+      end
+
+      # Find a prompt by name
+      #
+      # @param name [String] Name of the prompt to find
+      # @return [Prompt, nil] The prompt with the given name, or nil if not found
+      def find(name)
+        all.find { |prompt| prompt.name == name }
+      end
+
+      # Filter prompts based on a given block
+      #
+      # @yield [prompt] Block that determines whether to include a prompt
+      # @yieldparam prompt [Prompt] A prompt from the collection
+      # @yieldreturn [Boolean] true to include the prompt, false to exclude it
+      # @return [Array<Prompt>] Prompts that match the filter criteria
+      def filter(&block)
+        all.select(&block)
+      end
+
+      # Get a list of all prompt names
+      #
+      # @return [Array<String>] Names of all prompts in the collection
+      def names
+        all.map(&:name)
+      end
+
+      # Number of prompts in the collection
+      #
+      # @return [Integer] The number of prompts
+      def size
+        all.size
+      end
+
+      # Check if the collection contains a prompt with the given name
+      #
+      # @param name [String] The prompt name to check for
+      # @return [Boolean] true if a prompt with the name exists
+      def contains?(name)
+        all.any? { |prompt| prompt.name == name }
+      end
+
+      # Implements enumerable functionality for the collection
+      include Enumerable
+
+      # Yield each prompt in the collection to the given block
+      #
+      # @yield [prompt] Block to execute for each prompt
+      # @yieldparam prompt [Prompt] A prompt from the collection
+      # @return [Enumerator] If no block is given
+      def each(&block)
+        all.each(&block)
+      end
+
+      # Force reload all prompts from the client and return them
+      #
+      # @return [Array<Prompt>] All prompt objects in the collection
+      def all!
+        load_prompts(force: true)
+        all
+      end
+
+      # Convert raw prompt data into Prompt objects
+      #
+      # @param prompts [Array<Hash>] Array of prompt definition hashes
+      def prompts=(prompts)
+        @prompts = prompts.map { |data| Prompt.new(data) }
+      end
+
+      private
+
+      # Load or reload prompts using the client
+      #
+      # @param force [Boolean] Whether to force reload even if prompts are already loaded
+      # @return [void]
+      def load_prompts(force: false)
+        return if @loaded && !force
+
+        begin
+          @client.list_prompts
+          @loaded = true
+        rescue StandardError => e
+          Rails.logger.error("Failed to load prompts: #{e.message}")
+          @loaded = true unless @prompts.empty?
+        end
+      end
+
+      # Internal Prompt class to represent individual prompts
+      class Prompt
+        attr_reader :name, :description, :arguments
+
+        # Initialize a new Prompt instance
+        #
+        # @param data [Hash] Prompt definition hash containing name, description, and arguments
+        def initialize(data)
+          @name = data["name"]
+          @description = data["description"]
+          @arguments = data["arguments"] || []
+        end
+
+        # Get all required arguments for this prompt
+        #
+        # @return [Array<Hash>] Array of argument hashes that are required
+        def required_arguments
+          @arguments.select { |arg| arg["required"] }
+        end
+
+        # Get all optional arguments for this prompt
+        #
+        # @return [Array<Hash>] Array of argument hashes that are optional
+        def optional_arguments
+          @arguments.reject { |arg| arg["required"] }
+        end
+
+        # Check if the prompt has a specific argument
+        #
+        # @param name [String] Name of the argument to check for
+        # @return [Boolean] true if the argument exists
+        def has_argument?(name)
+          @arguments.any? { |arg| arg["name"] == name }
+        end
+
+        # Generate a hash representation of the prompt
+        #
+        # @return [Hash] Hash containing prompt details
+        def to_h
+          {
+            "name" => @name,
+            "description" => @description,
+            "arguments" => @arguments
+          }
+        end
+      end
+    end
+  end
+end

data/lib/action_mcp/client/prompts.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module Client
+    module Prompts
+      # List all available prompts from the server
+      # @return [Array<Hash>] List of available prompts with their metadata
+      def list_prompts
+        request_id = SecureRandom.uuid_v7
+
+        # Send request
+        send_jsonrpc_request("prompts/list", id: request_id)
+      end
+
+      # Get a specific prompt with arguments
+      # @param name [String] Name of the prompt to get
+      # @param arguments [Hash] Arguments to pass to the prompt
+      # @return [Hash] Prompt content with messages
+      def get_prompt(name, arguments = {})
+        request_id = SecureRandom.uuid_v7
+
+        # Send request
+        send_jsonrpc_request("prompts/get",
+                             params: {
+                               name: name,
+                               arguments: arguments
+                             },
+                             id: request_id
+        )
+      end
+    end
+  end
+end

data/lib/action_mcp/client/resources.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module Client
+    module Resources
+      # List all available resources from the server
+      # @return [Array<Hash>] List of available resources with their metadata
+      def list_resources
+        request_id = SecureRandom.uuid_v7
+
+        # Send request
+        send_jsonrpc_request("resources/list", id: request_id)
+      end
+
+      # List resource templates from the server
+      # @return [Array<Hash>] List of resource templates
+      def list_resource_templates
+        request_id = SecureRandom.uuid_v7
+
+        # Send request
+        send_jsonrpc_request("resources/templates/list", id: request_id)
+      end
+
+      # Read a specific resource
+      # @param uri [String] URI of the resource to read
+      # @return [Hash] Resource content
+      def read_resource(uri)
+        request_id = SecureRandom.uuid_v7
+
+        # Send request
+        send_jsonrpc_request("resources/read",
+                             params: { uri: uri },
+                             id: request_id
+        )
+      end
+
+      # Subscribe to updates for a specific resource
+      # @param uri [String] URI of the resource to subscribe to
+      # @param update_callback [Proc] Callback for resource updates
+      # @return [Boolean] Success status
+      def subscribe_resource(uri, update_callback)
+        @resource_subscriptions ||= {}
+        @resource_subscriptions[uri] = update_callback
+
+        request_id = SecureRandom.uuid_v7
+
+        # Send request
+        send_jsonrpc_request("resources/subscribe",
+                             params: { uri: uri },
+                             id: request_id
+        )
+      end
+
+      # Unsubscribe from updates for a specific resource
+      # @param uri [String] URI of the resource to unsubscribe from
+      # @return [Boolean] Success status
+      def unsubscribe_resource(uri)
+        @resource_subscriptions&.delete(uri)
+
+        request_id = SecureRandom.uuid_v7
+
+        # Send request
+        send_jsonrpc_request("resources/unsubscribe",
+                             params: { uri: uri },
+                             id: request_id
+        )
+      end
+    end
+  end
+end

data/lib/action_mcp/client/roots.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module Client
+    module Roots
+      # Notify the server that the roots list has changed
+      def roots_list_changed_notification
+        send_jsonrpc_notification("notifications/roots/list_changed")
+        true
+      end
+    end
+  end
+end