actionmcp 0.20.0 → 0.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86bd5d34d17ae66d5fcae2cf75c8231f78d6c08f88199f4835e42faed93e9589
-  data.tar.gz: 239b2fc880942da6f7b4c1b6bf1b498ab12a7866d1bfb34e719bb7f46e206985
+  metadata.gz: 6b50744d4dcd16237d18d1b5c787f721e56281c82d1037c776201226a06cc60c
+  data.tar.gz: ed2b466652be17b4443508719da7b474b1bfc941047815f9a45bc4acf39ca2d6
 SHA512:
-  metadata.gz: ded4b3ae254173fa102465c03e665606ebd1f8acea443e117a2190c1d1115ee53b30401e94c9b9842d469493002213b32a21e58612f74f46a4e0956885f8f4b6
-  data.tar.gz: 730190f2a425916ea1c719cbdbdcd427ff606a0539b66e88226225f638d242f61c2663c9dcd0b38201ebe0856a4aa44ed3527f26399885e9658ee4319407c22d
+  metadata.gz: ba4f687a5368fb04a2f986b61859e19d05658c00e39dc2b600984db39f34fd3e0f56259e6d08c425d140c1f1641d55ee209ec0ae69109bde1e0ec5312b01cf57
+  data.tar.gz: 6daf198545188c392453e6a53b905fafd3aa6c84ab508114c563ef59ff1c8b0e44712d5c8c82dc8643497daef7136bc3c284baec482d9fd8193c3cf1a32d4fe0

data/app/controllers/action_mcp/messages_controller.rb

@@ -17,11 +17,11 @@ module ActionMCP
     private
 
     def transport_handler
-      TransportHandler.new(mcp_session)
+      Server::TransportHandler.new(mcp_session)
     end
 
     def json_rpc_handler
-      @json_rpc_handler ||= ActionMCP::JsonRpcHandler.new(transport_handler)
+      @json_rpc_handler ||= Server::JsonRpcHandler.new(transport_handler)
     end
 
     def handle_post_message(params, response)

data/app/models/action_mcp/session/message.rb

@@ -48,11 +48,15 @@ module ActionMCP
 
       after_create_commit :broadcast_message, if: :outgoing_message?
       # Set is_ping on responses if the original request was a ping
-      after_create :handle_ping_response, if: -> { %w[response error].include?(message_type) }
+      after_create :acknowledge_request, if: -> { %w[response error].include?(message_type) }
 
       # Scope to exclude both "ping" requests and their responses
       scope :without_pings, -> { where(is_ping: false) }
 
+      scope :requests, -> { where(message_type: "request") }
+      scope :notifications, -> { where(message_type: "notification") }
+      scope :responses, -> { where(message_type: "response") }
+
       # @param payload [String, Hash]
       def data=(payload)
         @data = payload
@@ -92,6 +96,11 @@ module ActionMCP
         message_type == "response"
       end
 
+      def rpc_method
+        return false unless request?
+        data["method"]
+      end
+
       private
 
       def outgoing_message?
@@ -99,7 +108,9 @@ module ActionMCP
       end
 
       def broadcast_message
-        adapter.broadcast(session_key, data.to_json)
+        if adapter.present?
+          adapter.broadcast(session_key, data.to_json)
+        end
       end
 
       def process_json_content(content)
@@ -125,17 +136,22 @@ module ActionMCP
         end
       end
 
-      def handle_ping_response
+      def acknowledge_request
         return unless jsonrpc_id.present?
 
         request_message = session.messages.find_by(
           jsonrpc_id: jsonrpc_id,
           message_type: "request"
         )
-        return unless request_message&.is_ping
 
-        self.is_ping = true
+        return unless request_message
+
+        # Set is_ping based on the request
+        self.is_ping = request_message.is_ping
+
+        # Mark the request as acknowledged for all responses
         request_message.update(request_acknowledged: true)
+
         save! if changed?
       end
     end

data/app/models/action_mcp/session.rb

@@ -46,8 +46,11 @@ module ActionMCP
     scope :closed, -> { where(status: "closed") }
     scope :without_messages, -> { includes(:messages).where(action_mcp_session_messages: { id: nil }) }
 
-    before_create :set_server_info
-    before_create :set_server_capabilities
+    scope :from_server, -> { where(role: "server") }
+    scope :from_client, -> { where(role: "client") }
+
+    before_create :set_server_info, if: -> { role == "server" }
+    before_create :set_server_capabilities, if: -> { role == "server" }
 
     validates :protocol_version, inclusion: { in: [ PROTOCOL_VERSION ] }, allow_nil: true
 
@@ -58,6 +61,7 @@ module ActionMCP
       subscriptions.delete_all # delete all subscriptions
     end
 
+    # MESSAGING dispatch
     def write(data)
       if data.is_a?(JsonRpc::Request) || data.is_a?(JsonRpc::Response) || data.is_a?(JsonRpc::Notification)
         data = data.to_json
@@ -100,8 +104,8 @@ module ActionMCP
     end
 
     def initialize!
-      # update the session initialized to true if client_capabilities are present
-      return unless client_capabilities.present?
+      # update the session initialized to true
+      return false if initialized?
 
       update!(initialized: true,
               status: "initialized")

data/lib/action_mcp/capability.rb

@@ -23,8 +23,8 @@ module ActionMCP
       @abstract_capability ||= false # Default to false, unique to each class
     end
 
-    def self.abstract_capability=(value)
-      @abstract_capability = value
+    class << self
+      attr_writer :abstract_capability
     end
 
     # Marks this tool as abstract so that it won’t be available for use.
@@ -49,6 +49,5 @@ module ActionMCP
         _description
       end
     end
-    ActiveSupport.run_load_hooks(:active_mcp, self)
   end
 end

data/lib/action_mcp/client/base.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module Client
+    # Base client class containing common MCP functionality
+    class Base
+      # Include all transport protocol modules
+      include Messaging
+      include Tools
+      include Prompts
+      include Resources
+      include Roots
+      include Logging
+
+      attr_reader :logger, :type,
+                  :connection_error, :server,
+                  :server_capabilities, :session,
+                  :catalog, :blueprint,
+                  :prompt_book, :toolbox
+      delegate :initialized?, to: :session
+
+      def initialize(logger: ActionMCP.logger)
+        @logger = logger
+        @connected = false
+        @session = Session.from_client.new(
+          protocol_version: PROTOCOL_VERSION,
+          client_info: client_info,
+          client_capabilities: client_capabilities
+        )
+        @server_capabilities = nil
+        @message_callback = nil
+        @error_callback = nil
+        @connection_error = nil
+        @initialized = false
+
+        # Resource objects
+        @catalog = Catalog.new([], self)
+        # Resource template objects
+        @blueprint = Blueprint.new([], self)
+        # Prompt objects
+        @prompt_book = PromptBook.new([], self)
+        # Tool objects
+        @toolbox = Toolbox.new([], self)
+      end
+
+      def connected?
+        @connected
+      end
+
+      # Connect to the MCP server, if something went wrong at initialization
+      def connect
+        return true if @connected
+
+        begin
+          log_debug("Connecting to MCP server...")
+          @connection_error = nil
+
+          # Start transport with proper error handling
+          success = start_transport
+
+          unless success
+            log_error("Failed to establish connection to MCP server")
+            return false
+          end
+
+          @connected = true
+          log_debug("Connected to MCP server")
+
+          # Create handler only if it doesn't exist yet
+          @json_rpc_handler ||= JsonRpcHandler.new(session, self)
+
+          # Clear any existing message callback and set a new one
+          @message_callback = lambda do |response|
+            @json_rpc_handler.call(response)
+          end
+
+          true
+        rescue StandardError => e
+          @connection_error = e.message
+          log_error("Failed to connect to MCP server: #{e.message}")
+          @error_callback&.call(e)
+          false
+        end
+      end
+
+      # Disconnect from the MCP server
+      def disconnect
+        return true unless @connected
+
+        begin
+          stop_transport
+          @connected = false
+          log_debug("Disconnected from MCP server")
+          true
+        rescue StandardError => e
+          log_error("Error disconnecting from MCP server: #{e.message}")
+          @error_callback&.call(e)
+          false
+        end
+      end
+
+      # Set a callback for incoming messages
+      def on_message(&block)
+        @message_callback = block
+      end
+
+      # Set a callback for errors
+      def on_error(&block)
+        @error_callback = block
+      end
+
+      # Send a request to the MCP server
+      def write_message(payload)
+        unless @connected
+          log_error("Cannot send request - not connected")
+          return false
+        end
+
+        begin
+          session.write(payload)
+          data = payload.to_json unless payload.is_a?(String)
+          send_message(data)
+          true
+        rescue StandardError => e
+          log_error("Failed to send request: #{e.message}")
+          @error_callback&.call(e)
+          false
+        end
+      end
+
+      # Methods to be implemented by subclasses
+      def start_transport
+        raise NotImplementedError, "#{self.class} must implement #start_transport"
+      end
+
+      def stop_transport
+        raise NotImplementedError, "#{self.class} must implement #stop_transport"
+      end
+
+      def send_message(json)
+        raise NotImplementedError, "#{self.class} must implement #send_message"
+      end
+
+      def ready?
+        raise NotImplementedError, "#{self.class} must implement #ready?"
+      end
+
+      def server=(server)
+        if server.is_a?(Client::Server)
+          @server = server
+        else
+          @server = Client::Server.new(server)
+        end
+        session.server_capabilities = server.capabilities
+        session.server_info = server.server_info
+        session.save
+        server
+      end
+
+      def inspect
+        "#<#{self.class.name} server: #{server}, client_name: #{client_info[:name]}, client_version: #{client_info[:version]}, capabilities: #{client_capabilities} , connected: #{connected?}, initialized: #{initialized?}, session: #{session.id}>"
+      end
+
+      protected
+
+      def handle_raw_message(raw)
+        begin
+          @message_callback&.call(raw)
+        rescue MultiJson::ParseError => e
+          log_error("JSON parse error: #{e} (raw: #{raw})")
+          @error_callback&.call(e)
+        rescue StandardError => e
+          log_error("Error handling message: #{e} (raw: #{raw})")
+          @error_callback&.call(e)
+        end
+      end
+
+      def send_initial_capabilities
+        log_debug("Sending client capabilities")
+        # We have contact! Let's send our CV to the recruiter.
+        # We persist the session object to the database
+        session.save
+        params= {
+          protocolVersion: session.protocol_version,
+          capabilities: session.client_capabilities,
+          clientInfo: session.client_info
+        }
+        send_jsonrpc_request("initialize", params: params, id: session.id)
+      end
+
+      def client_capabilities
+        {
+          # Base client capabilities can be defined here
+          # TODO
+        }
+      end
+
+      def user_agent
+        "ActionMCP-Client"
+      end
+
+      def client_info
+        {
+          name: user_agent,
+          version: ActionMCP.gem_version.to_s
+        }
+      end
+
+      def log_debug(message)
+        logger.debug("[ActionMCP::#{self.class.name.split('::').last}] #{message}")
+      end
+
+      def log_info(message)
+        logger.info("[ActionMCP::#{self.class.name.split('::').last}] #{message}")
+      end
+
+      def log_error(message)
+        logger.error("[ActionMCP::#{self.class.name.split('::').last}] #{message}")
+      end
+    end
+  end
+end

data/lib/action_mcp/client/blueprint.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module Client
+    # Blueprints
+    #
+    # A collection that manages and provides access to URI templates (blueprints) for Model Context Protocol (MCP)
+    # resource discovery. These blueprints allow dynamic construction of resource URIs by filling in
+    # variable placeholders with specific values. The class supports lazy loading of templates when
+    # initialized with a client.
+    #
+    # Example usage:
+    #   # Eager loading
+    #   template_data = client.list_resource_templates # Returns array of URI template definitions
+    #   blueprints = Blueprint.new(template_data)
+    #
+    #   # Lazy loading
+    #   blueprints = Blueprint.new([], client)
+    #   templates = blueprints.all # Templates are loaded here
+    #
+    #   # Access a specific blueprint by pattern
+    #   file_blueprint = Blueprint.find_by_pattern("file://{path}")
+    #
+    #   # Generate a concrete URI from a blueprint with parameters
+    #   uri = Blueprint.construct("file://{path}", { path: "/logs/app.log" })
+    #
+    class Blueprint < Collection
+      # Initialize a new Blueprints collection with URI template definitions
+      #
+      # @param templates [Array<Hash>] Array of URI template definition hashes, each containing
+      #   uriTemplate, name, description, and optionally mimeType keys
+      # @param client [Object, nil] Optional client for lazy loading of templates
+      def initialize(templates, client)
+        super(templates, client)
+        self.templates = @collection_data
+        @load_method = :list_resource_templates
+      end
+
+      # Find a blueprint by its URI pattern
+      #
+      # @param pattern [String] URI template pattern to find
+      # @return [Blueprint, nil] The blueprint with the given pattern, or nil if not found
+      def find_by_pattern(pattern)
+        all.find { |blueprint| blueprint.pattern == pattern }
+      end
+
+      # Find blueprints by name
+      #
+      # @param name [String] Name of the blueprints to find
+      # @return [Array<Blueprint>] Blueprints with the given name
+      def find_by_name(name)
+        all.select { |blueprint| blueprint.name == name }
+      end
+
+      # Construct a concrete URI by applying parameters to a blueprint
+      #
+      # @param pattern [String] URI template pattern to use
+      # @param params [Hash] Parameters to substitute into the pattern
+      # @return [String] The constructed URI with parameters applied
+      # @raise [KeyError] If a required parameter is missing
+      def construct(pattern, params)
+        blueprint = find_by_pattern(pattern)
+        raise ArgumentError, "Unknown blueprint pattern: #{pattern}" unless blueprint
+
+        blueprint.construct(params)
+      end
+
+      # Check if the collection contains a blueprint with the given pattern
+      #
+      # @param pattern [String] The blueprint pattern to check for
+      # @return [Boolean] true if a blueprint with the pattern exists
+      def contains?(pattern)
+        all.any? { |blueprint| blueprint.pattern == pattern }
+      end
+
+      # Group blueprints by their base protocol
+      #
+      # @return [Hash<String, Array<Blueprint>>] Hash mapping protocols to arrays of blueprints
+      def group_by_protocol
+        all.group_by(&:protocol)
+      end
+
+      # Convert raw template data into ResourceTemplate objects
+      #
+      # @param templates [Array<Hash>] Array of template definition hashes
+      def templates=(templates)
+        @collection_data = templates.map { |template_data| ResourceTemplate.new(template_data) }
+      end
+
+      # Internal Blueprint class to represent individual URI templates
+      class ResourceTemplate
+        attr_reader :pattern, :name, :description, :mime_type
+
+        # Initialize a new ResourceTemplate instance
+        #
+        # @param data [Hash] ResourceTemplate definition hash containing uriTemplate, name, description,
+        #   and optionally mimeType
+        def initialize(data)
+          @pattern = data["uriTemplate"]
+          @name = data["name"]
+          @description = data["description"]
+          @mime_type = data["mimeType"]
+          @variable_pattern = /{([^}]+)}/
+        end
+
+        # Extract variable names from the template pattern
+        #
+        # @return [Array<String>] List of variable names in the pattern
+        def variables
+          @pattern.scan(@variable_pattern).flatten
+        end
+
+        # Get the protocol part of the URI template
+        #
+        # @return [String] The protocol (scheme) of the URI template
+        def protocol
+          @pattern.split("://").first
+        end
+
+        # Construct a concrete URI by substituting parameters into the template pattern
+        #
+        # @param params [Hash] Parameters to substitute into the pattern
+        # @return [String] The constructed URI with parameters applied
+        # @raise [KeyError] If a required parameter is missing
+        def construct(params)
+          result = @pattern.dup
+
+          variables.each do |var|
+            raise KeyError, "Missing required parameter: #{var}" unless params.key?(var.to_sym) || params.key?(var)
+
+            value = params[var.to_sym] || params[var]
+            result.gsub!("{#{var}}", value.to_s)
+          end
+
+          result
+        end
+
+        # Check if this template is compatible with a set of parameters
+        #
+        # @param params [Hash] Parameters to check
+        # @return [Boolean] true if all required variables have corresponding parameters
+        def compatible_with?(params)
+          symbolized_params = params.transform_keys(&:to_sym)
+          variables.all? { |var| symbolized_params.key?(var.to_sym) }
+        end
+
+        # Generate a hash representation of the blueprint
+        #
+        # @return [Hash] Hash containing blueprint details
+        def to_h
+          {
+            "uriTemplate" => @pattern,
+            "name" => @name,
+            "description" => @description,
+            "mimeType" => @mime_type
+          }
+        end
+      end
+    end
+  end
+end

data/lib/action_mcp/client/catalog.rb

@@ -0,0 +1,160 @@
+# 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 < Collection
+      # 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
+      def initialize(resources, client)
+        super(resources, client)
+        self.resources = @collection_data
+        @load_method = :list_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
+
+      # Get a list of all resource URIs
+      #
+      # @return [Array<String>] URIs of all resources in the collection
+      def uris
+        all.map(&:uri)
+      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
+
+      # Convert raw resource data into Resource objects
+      #
+      # @param raw_resources [Array<Hash>] Array of resource definition hashes
+      def resources=(raw_resources)
+        @collection_data = raw_resources.map { |resource_data| Resource.new(resource_data) }
+      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