actionmcp 0.19.1 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f6822a7c2f7b29500c36ebb7a61f050e5a88e3e42b9d0286f17908a5f3e994e
-  data.tar.gz: f472562a0547b097cc3935ddc029385c55d8cc3e4be008e0676f82c844e2aba1
+  metadata.gz: 5c997c4c99f4ecf6409fb3749bb58efab0eb03622e70d9a447781125620e6c82
+  data.tar.gz: dd9fc6be1b7364f306a6cbcfe0cd9e8db3b00530e46056c6ad49e6995ab7810b
 SHA512:
-  metadata.gz: 72a2892dea8ba2869d29fa3f3021962a765a47fbc503214c2f63a4818e281f496c8e6153df3e48dc367ffb54dd38f07fbda79ec2eeb2536ae521a7a8b35d64cc
-  data.tar.gz: 7ccde9675fefd062cb482acecd2d55403277f46f60de794cef40124a721f28a40252dc76ea8b17c05bedcbabc3d7c5942f882bb418552e0d48fcd2f7708ff00a
+  metadata.gz: c6de9245cf20071a23b0f35181d1eb20db9a2fb96298c6afc165a05aa31f14c3f8035b2b3dbd9ac9b04319f0981ce26609f8afde1ab67ef99a055a070ce3018c
+  data.tar.gz: e8b0006312a943b8228408ab0fe5b859d4a638bfbbe89ddcb6be0d38465476fdb9977f6d2b322676eb1ddc1608abcc7531c9352495c7bde11bb04868586edae1

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

@@ -53,6 +53,10 @@ module ActionMCP
       # 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)

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/base_response.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  class BaseResponse
+    include Enumerable
+    attr_reader :is_error
+
+    def initialize
+      @is_error = false
+    end
+
+    # Mark response as error
+    def mark_as_error!(symbol = :invalid_request, message: nil, data: nil)
+      @is_error = true
+      @symbol = symbol
+      @error_message = message
+      @error_data = data
+      self
+    end
+
+    # Convert to hash format expected by MCP protocol
+    def to_h
+      if @is_error
+        JsonRpc::JsonRpcError.new(@symbol, message: @error_message, data: @error_data).to_h
+      else
+        build_success_hash
+      end
+    end
+
+    # Method to be implemented by subclasses
+    def build_success_hash
+      raise NotImplementedError, "Subclasses must implement #build_success_hash"
+    end
+
+    # Alias as_json to to_h for consistency
+    alias as_json to_h
+
+    # Handle to_json directly
+    def to_json(options = nil)
+      to_h.to_json(options)
+    end
+
+    # Compare with hash for easier testing
+    def ==(other)
+      case other
+      when Hash
+        # Convert both to normalized format for comparison
+        hash_self = to_h.deep_transform_keys { |key| key.to_s.underscore }
+        hash_other = other.deep_transform_keys { |key| key.to_s.underscore }
+        hash_self == hash_other
+      when self.class
+        compare_with_same_class(other)
+      else
+        super
+      end
+    end
+
+    # Method to be implemented by subclasses for comparison
+    def compare_with_same_class(other)
+      raise NotImplementedError, "Subclasses must implement #compare_with_same_class"
+    end
+
+    # Implement eql? for hash key comparison
+    def eql?(other)
+      self == other
+    end
+
+    # Method to be implemented by subclasses for hash generation
+    def hash_components
+      raise NotImplementedError, "Subclasses must implement #hash_components"
+    end
+
+    # Implement hash method for hash key usage
+    def hash
+      hash_components.hash
+    end
+
+    def success?
+      !is_error
+    end
+
+    def error?
+      is_error
+    end
+  end
+end

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,227 @@
+# 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
+      # 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
+      attr_reader :client
+
+      def initialize(templates, client)
+        self.templates = templates
+        @client = client
+        @loaded = !templates.empty?
+      end
+
+      # Return all URI templates in the collection. If initialized with a client and templates
+      # haven't been loaded yet, this will trigger lazy loading from the client.
+      #
+      # @return [Array<Blueprint>] All blueprint objects in the collection
+      def all
+        load_templates unless @loaded
+        @templates
+      end
+
+      # Force reload all templates from the client and return them
+      #
+      # @return [Array<Blueprint>] All blueprint objects in the collection
+      def all!
+        load_templates(force: true)
+        @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
+
+      # Filter blueprints based on a given block
+      #
+      # @yield [blueprint] Block that determines whether to include a blueprint
+      # @yieldparam blueprint [Blueprint] A blueprint from the collection
+      # @yieldreturn [Boolean] true to include the blueprint, false to exclude it
+      # @return [Array<Blueprint>] Blueprints that match the filter criteria
+      def filter(&block)
+        all.select(&block)
+      end
+
+      # Number of blueprints in the collection
+      #
+      # @return [Integer] The number of blueprints
+      def size
+        all.size
+      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
+
+      # Implements enumerable functionality for the collection
+      include Enumerable
+
+      # Yield each blueprint in the collection to the given block
+      #
+      # @yield [blueprint] Block to execute for each blueprint
+      # @yieldparam blueprint [Blueprint] A blueprint from the collection
+      # @return [Enumerator] If no block is given
+      def each(&block)
+        all.each(&block)
+      end
+
+      # Convert raw template data into ResourceTemplate objects
+      #
+      # @param templates [Array<Hash>] Array of template definition hashes
+      def templates=(templates)
+        @templates = templates.map { |template_data| ResourceTemplate.new(template_data) }
+      end
+
+      private
+
+      # Load or reload templates using the client
+      #
+      # @param force [Boolean] Whether to force reload even if templates are already loaded
+      # @return [void]
+      def load_templates(force: false)
+        return if @loaded && !force
+
+        begin
+          @client.list_resource_templates
+          @loaded = true
+        rescue StandardError => e
+          Rails.logger.error("Failed to load templates: #{e.message}")
+          @loaded = true unless @templates.empty?
+        end
+      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