actionmcp 0.2.0 → 0.2.3

data/lib/action_mcp/client.rb

@@ -1,7 +1,249 @@
 # frozen_string_literal: true
 
-## TODO: Adding this so i don't forget
 module ActionMCP
+  # Create a client appropriate for the given endpoint
+  # @param endpoint [String] The endpoint to connect to (URL or command)
+  # @param logger [Logger] The logger to use
+  # @return [Client] An SSEClient or StdioClient depending on the endpoint
+  def self.create_client(endpoint, logger: Logger.new(STDOUT))
+    if endpoint =~ /\Ahttps?:\/\//
+      logger.info("Creating SSE client for endpoint: #{endpoint}")
+      SSEClient.new(endpoint, logger: logger)
+    else
+      logger.info("Creating STDIO client for command: #{endpoint}")
+      StdioClient.new(endpoint, logger: logger)
+    end
+  end
+
+  # Base client class for MCP protocol
   class Client
+    attr_reader :logger, :capabilities, :type, :connection_error
+
+    def initialize(logger: Logger.new(STDOUT))
+      @logger = logger
+      @connected = false
+      @initialize_request_id = SecureRandom.uuid_v7
+      @server_capabilities = nil
+      @message_callback = nil
+      @error_callback = nil
+      @connection_error = nil
+    end
+
+    def connect
+      return true if @connected
+
+      begin
+        logger.info("Connecting to MCP server...")
+        @connection_error = nil
+
+        # Start transport with proper error handling
+        success = start_transport
+
+        unless success
+          logger.error("Failed to establish connection to MCP server")
+          return false
+        end
+
+        @connected = true
+        logger.info("Connected to MCP server")
+        true
+      rescue => e
+        @connection_error = e.message
+        logger.error("Failed to connect to MCP server: #{e.message}")
+        false
+      end
+    end
+
+    # Disconnect from the MCP server
+    # @return [Boolean] true if disconnection was successful
+    def disconnect
+      return true unless @connected
+
+      begin
+        stop_transport
+        @connected = false
+        logger.info("Disconnected from MCP server")
+        true
+      rescue => e
+        logger.error("Error disconnecting from MCP server: #{e.message}")
+        false
+      end
+    end
+
+    # Send a request to the MCP server
+    # @param payload [Hash, String] The request payload
+    # @return [Boolean] true if the request was sent successfully
+    def send_request(payload)
+      unless @connected
+        logger.error("Cannot send request - not connected")
+        return false
+      end
+
+      begin
+        json = prepare_payload(payload)
+        send_message(json)
+        true
+      rescue => e
+        logger.error("Failed to send request: #{e.message}")
+        false
+      end
+    end
+
+    # Check if the client is ready to send requests
+    # @return [Boolean] true if the client is connected and ready
+    def ready?
+      @connected && transport_ready?
+    end
+
+    # Set a callback for incoming messages
+    # @yield [message] Called when a message is received
+    # @yieldparam message The received message
+    def on_message(&block)
+      @message_callback = block
+    end
+
+    # Set a callback for errors
+    # @yield [error] Called when an error occurs
+    # @yieldparam error The error that occurred
+    def on_error(&block)
+      @error_callback = block
+    end
+
+    # Get the server capabilities
+    # @return [Hash, nil] The server capabilities, or nil if not connected
+    def server_capabilities
+      @server_capabilities
+    end
+
+    protected
+
+    # Start the transport - implemented by subclasses
+    def start_transport
+      raise NotImplementedError, "Subclasses must implement start_transport"
+    end
+
+    # Stop the transport
+    def stop_transport
+      @transport.stop
+    end
+
+    # Send a message through the transport
+    def send_message(json)
+      @transport.send_message(json)
+    end
+
+    # Check if the transport is ready
+    def transport_ready?
+      @transport.ready?
+    end
+
+    private
+
+    # Prepare a payload for sending
+    # @param payload [Hash, String] The payload to prepare
+    # @return [String] The JSON-encoded payload
+    def prepare_payload(payload)
+      case payload
+      when String
+        # Assume it's already JSON
+        payload
+      else
+        # Try to convert to JSON
+        MultiJson.dump(payload)
+      end
+    end
+  end
+
+  # MCP client using Server-Sent Events (SSE) transport
+  class SSEClient < Client
+    # Initialize an SSE client
+    # @param endpoint [String] The SSE endpoint URL
+    # @param logger [Logger] The logger to use
+    def initialize(endpoint, logger: Logger.new(STDOUT))
+      super(logger: logger)
+      @endpoint = endpoint
+      @transport = Transport::SSEClient.new(endpoint, logger: logger)
+      @type = :sse
+
+      # Set up callbacks after transport is initialized
+      setup_callbacks
+    end
+
+    protected
+
+    def start_transport
+      begin
+        @transport.start(@initialize_request_id)
+        true
+      rescue Transport::SSEClient::ConnectionError => e
+        @connection_error = e.message
+        @error_callback&.call(e)
+        false
+      rescue => e
+        @connection_error = e.message
+        @error_callback&.call(e)
+        false
+      end
+    end
+
+    private
+
+    def setup_callbacks
+      @transport.on_message do |message|
+        # Check if this is a response to our initialize request
+        puts @initialize_request_id
+        if message&.id == @initialize_request_id
+          @transport.handle_initialize_response(message)
+        else
+          puts "\e[32mCalling message callback\e[0m"
+          @message_callback&.call(message)
+        end
+      end
+
+      @transport.on_error do |error|
+        @error_callback&.call(error)
+      end
+    end
+  end
+
+  # MCP client using Standard I/O (STDIO) transport
+  class StdioClient < Client
+    # Initialize a STDIO client
+    # @param command [String] The command to execute
+    # @param logger [Logger] The logger to use
+    def initialize(command, logger: Logger.new(STDOUT))
+      super(logger: logger)
+      @command = command
+      @transport = Transport::StdioClient.new(command, logger: logger)
+      @type = :stdio
+
+      # Set up callbacks after transport is initialized
+      setup_callbacks
+    end
+
+    protected
+
+    def start_transport
+      @transport.start
+      # For STDIO, we'll send the capabilities from the connect method
+      # after this method completes and @connected is set to true
+    end
+
+    private
+
+    def setup_callbacks
+      @transport.on_message do |message|
+        # Check if this is a response to our initialize request
+        if message && message.id && message.id == @initialize_request_id
+          @transport.handle_initialize_response(message)
+        end
+
+        @message_callback&.call(message)
+      end
+
+      @transport.on_error do |error|
+        @error_callback&.call(error)
+      end
+    end
   end
 end

data/lib/action_mcp/configuration.rb

@@ -3,18 +3,67 @@
 module ActionMCP
   # Configuration class to hold settings for the ActionMCP server.
   class Configuration
+    # @!attribute name
+    #   @return [String] The name of the MCP Server.
+    # @!attribute version
+    #   @return [String] The version of the MCP Server.
+    # @!attribute logging_enabled
+    #   @return [Boolean] Whether logging is enabled.
+    # @!attribute list_changed
+    #   @return [Boolean] Whether to send a listChanged notification for tools, prompts, and resources.
+    # @!attribute resources_subscribe
+    #   @return [Boolean] Whether to subscribe to resources.
+    # @!attribute logging_level
+    #   @return [Symbol] The logging level.
     attr_accessor :name, :version, :logging_enabled,
                   # Right now, if enabled, the server will send a listChanged notification for tools, prompts, and resources.
                   # We can make it more granular in the future, but for now, it's a simple boolean.
                   :list_changed,
-                  :resources_subscribe
+                  :resources_subscribe,
+                  :logging_level
 
+    # Initializes a new Configuration instance.
+    #
+    # @return [void]
     def initialize
       # Use Rails.application values if available, or fallback to defaults.
       @name = defined?(Rails) && Rails.respond_to?(:application) && Rails.application.respond_to?(:name) ? Rails.application.name : "ActionMCP"
       @version = defined?(Rails) && Rails.respond_to?(:application) && Rails.application.respond_to?(:version) ? Rails.application.version.to_s.presence : "0.0.1"
       @logging_enabled = true
       @list_changed = false
+      @logging_level = :info
+    end
+
+    # Returns a hash of capabilities.
+    #
+    # @return [Hash] A hash containing the resources capabilities.
+    def capabilities
+      capabilities = {}
+      # Only include each capability if the corresponding registry is non-empty.
+      capabilities[:tools] = { listChanged: @list_changed } if ToolsRegistry.non_abstract.any?
+      capabilities[:prompts] = { listChanged: @list_changed } if PromptsRegistry.non_abstract.any?
+      capabilities[:logging] = {} if @logging_enabled
+      # capabilities[:resources] = { subscribe: @resources_subscribe,
+      #                              listChanged: @list_changed }.compact
+      { capabilities: capabilities }
+    end
+  end
+
+  class << self
+    attr_accessor :server
+    # Returns the configuration instance.
+    #
+    # @return [Configuration] the configuration instance
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configures the ActionMCP module.
+    #
+    # @yield [configuration] the configuration instance
+    # @return [void]
+    def configure
+      yield(configuration)
     end
   end
 end

data/lib/action_mcp/content/audio.rb

@@ -4,14 +4,23 @@ module ActionMCP
   module Content
     # Audio content includes a base64-encoded audio clip and its MIME type.
     class Audio < Base
+      # @return [String] The base64-encoded audio data.
+      # @return [String] The MIME type of the audio data.
       attr_reader :data, :mime_type
 
+      # Initializes a new Audio content.
+      #
+      # @param data [String] The base64-encoded audio data.
+      # @param mime_type [String] The MIME type of the audio data.
       def initialize(data, mime_type)
         super("audio")
         @data = data
         @mime_type = mime_type
       end
 
+      # Returns a hash representation of the audio content.
+      #
+      # @return [Hash] The hash representation of the audio content.
       def to_h
         super.merge(data: @data, mimeType: @mime_type)
       end

data/lib/action_mcp/content/image.rb

@@ -4,14 +4,23 @@ module ActionMCP
   module Content
     # Image content includes a base64-encoded image and its MIME type.
     class Image < Base
+      # @return [String] The base64-encoded image data.
+      # @return [String] The MIME type of the image data.
       attr_reader :data, :mime_type
 
+      # Initializes a new Image content.
+      #
+      # @param data [String] The base64-encoded image data.
+      # @param mime_type [String] The MIME type of the image data.
       def initialize(data, mime_type)
         super("image")
         @data = data
         @mime_type = mime_type
       end
 
+      # Returns a hash representation of the image content.
+      #
+      # @return [Hash] The hash representation of the image content.
       def to_h
         super.merge(data: @data, mimeType: @mime_type)
       end

data/lib/action_mcp/content/resource.rb

@@ -5,8 +5,18 @@ module ActionMCP
     # Resource content references a server-managed resource.
     # It includes a URI, MIME type, and optionally text content or a base64-encoded blob.
     class Resource < Base
+      # @return [String] The URI of the resource.
+      # @return [String] The MIME type of the resource.
+      # @return [String, nil] The text content of the resource (optional).
+      # @return [String, nil] The base64-encoded blob of the resource (optional).
       attr_reader :uri, :mime_type, :text, :blob
 
+      # Initializes a new Resource content.
+      #
+      # @param uri [String] The URI of the resource.
+      # @param mime_type [String] The MIME type of the resource.
+      # @param text [String, nil] The text content of the resource (optional).
+      # @param blob [String, nil] The base64-encoded blob of the resource (optional).
       def initialize(uri, mime_type, text: nil, blob: nil)
         super("resource")
         @uri = uri
@@ -15,6 +25,9 @@ module ActionMCP
         @blob = blob
       end
 
+      # Returns a hash representation of the resource content.
+      #
+      # @return [Hash] The hash representation of the resource content.
       def to_h
         resource_data = { uri: @uri, mimeType: @mime_type }
         resource_data[:text] = @text if @text

data/lib/action_mcp/content/text.rb

@@ -4,13 +4,20 @@ module ActionMCP
   module Content
     # Text content represents plain text messages.
     class Text < Base
+      # @return [String] The text content.
       attr_reader :text
 
+      # Initializes a new Text content.
+      #
+      # @param text [String] The text content.
       def initialize(text)
         super("text")
         @text = text.to_s
       end
 
+      # Returns a hash representation of the text content.
+      #
+      # @return [Hash] The hash representation of the text content.
       def to_h
         super.merge(text: @text)
       end

data/lib/action_mcp/content.rb

@@ -1,28 +1,33 @@
 # frozen_string_literal: true
 
 module ActionMCP
+  # Module for managing content within ActionMCP.
   module Content
-    extend ActiveSupport::Autoload
     # Base class for MCP content items.
     class Base
+      # @return [Symbol] The type of content.
       attr_reader :type
 
+      # Initializes a new content item.
+      #
+      # @param type [Symbol] The type of content.
       def initialize(type)
         @type = type
       end
 
+      # Returns a hash representation of the content.
+      #
+      # @return [Hash] The hash representation.
       def to_h
         { type: @type }
       end
 
+      # Returns a JSON representation of the content.
+      #
+      # @return [String] The JSON representation.
       def to_json(*)
         MultiJson.dump(to_h, *)
       end
     end
-
-    autoload :Image
-    autoload :Text
-    autoload :Audio
-    autoload :Resource
   end
 end

data/lib/action_mcp/engine.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "rails"
+require "active_model/railtie"
+
+module ActionMCP
+  # Engine for integrating ActionMCP with Rails applications.
+  class Engine < ::Rails::Engine
+    isolate_namespace ActionMCP
+
+    ActiveSupport::Inflector.inflections(:en) do |inflect|
+      inflect.acronym "SSE"
+      inflect.acronym "MCP"
+    end
+    # Provide a configuration namespace for ActionMCP
+    config.action_mcp = ActiveSupport::OrderedOptions.new
+
+    initializer "action_mcp.configure" do |app|
+      options = app.config.action_mcp.to_h.symbolize_keys
+
+      # Override the default configuration if specified in the Rails app.
+      ActionMCP.configuration.name            = options[:name] if options.key?(:name)
+      ActionMCP.configuration.version         = options[:version] if options.key?(:version)
+      ActionMCP.configuration.logging_enabled = options.fetch(:logging_enabled, true)
+    end
+
+    # Initialize the ActionMCP logger.
+    initializer "action_mcp.logger" do
+      ActiveSupport.on_load(:action_mcp) do
+        self.logger = ::Rails.logger
+      end
+    end
+  end
+end

data/lib/action_mcp/gem_version.rb

@@ -1,7 +1,7 @@
-# frozen_string_literal: true
-
 module ActionMCP
   # Returns the currently loaded version of Active MCP as a +Gem::Version+.
+  #
+  # @return [Gem::Version] the currently loaded version of Active MCP
   def self.gem_version
     Gem::Version.new VERSION
   end

data/lib/action_mcp/integer_array.rb

@@ -3,7 +3,13 @@
 module ActionMCP
   # This temporary naming extracted from MCPangea
   # If there is a better name, please suggest it or part of ActiveModel, open a PR
+  #
+  # Custom type for handling arrays of integers in ActiveModel.
   class IntegerArray < ActiveModel::Type::Value
+    # Casts the given value to an array of integers.
+    #
+    # @param value [Object] The value to cast.
+    # @return [Array<Integer>] The array of integers.
     def cast(value)
       Array(value).map(&:to_i) # Ensure all elements are integers
     end

data/lib/action_mcp/json_rpc/json_rpc_error.rb

@@ -2,6 +2,7 @@
 
 module ActionMCP
   module JsonRpc
+    # Custom exception class for JSON-RPC errors, based on the JSON-RPC 2.0 specification.
     class JsonRpcError < StandardError
       # Define the standard JSON-RPC 2.0 error codes
       ERROR_CODES = {
@@ -31,14 +32,25 @@ module ActionMCP
         }
       }.freeze
 
+      # @return [Integer] The error code.
+      # @return [Object] The error data.
       attr_reader :code, :data
 
       # Retrieve error details by symbol.
+      #
+      # @param symbol [Symbol] The error symbol.
+      # @raise [ArgumentError] if the error code is unknown.
+      # @return [Hash] The error details.
       def self.[](symbol)
         ERROR_CODES[symbol] or raise ArgumentError, "Unknown error code: #{symbol}"
       end
 
       # Build an error hash, allowing custom message or data to override defaults.
+      #
+      # @param symbol [Symbol] The error symbol.
+      # @param message [String, nil] Optional custom message.
+      # @param data [Object, nil] Optional custom data.
+      # @return [Hash] The error hash.
       def self.build(symbol, message: nil, data: nil)
         error = self[symbol].dup
         error[:message] = message if message
@@ -47,6 +59,10 @@ module ActionMCP
       end
 
       # Initialize the error using a symbol key, with optional custom message and data.
+      #
+      # @param symbol [Symbol] The error symbol.
+      # @param message [String, nil] Optional custom message.
+      # @param data [Object, nil] Optional custom data.
       def initialize(symbol, message: nil, data: nil)
         error_details = self.class.build(symbol, message: message, data: data)
         @code = error_details[:code]
@@ -55,6 +71,8 @@ module ActionMCP
       end
 
       # Returns a hash formatted for a JSON-RPC error response.
+      #
+      # @return [Hash] The error hash.
       def as_json
         hash = { code: code, message: message }
         hash[:data] = data if data
@@ -62,6 +80,9 @@ module ActionMCP
       end
 
       # Converts the error hash to a JSON string.
+      #
+      # @param _args [Array] Arguments passed to MultiJson.dump.
+      # @return [String] The JSON string.
       def to_json(*_args)
         MultiJson.dump(as_json, *args)
       end

data/lib/action_mcp/json_rpc/notification.rb

@@ -2,11 +2,19 @@
 
 module ActionMCP
   module JsonRpc
+    # Represents a JSON-RPC notification.
     Notification = Data.define(:method, :params) do
+      # Initializes a new Notification.
+      #
+      # @param method [String] The method name.
+      # @param params [Hash, nil] The parameters (optional).
       def initialize(method:, params: nil)
         super
       end
 
+      # Returns a hash representation of the notification.
+      #
+      # @return [Hash] The hash representation.
       def to_h
         {
           jsonrpc: "2.0",

data/lib/action_mcp/json_rpc/request.rb

@@ -2,12 +2,22 @@
 
 module ActionMCP
   module JsonRpc
+    # Represents a JSON-RPC request.
     Request = Data.define(:id, :method, :params) do
+      # Initializes a new Request.
+      #
+      # @param id [String, Numeric] The request identifier.
+      # @param method [String] The method name.
+      # @param params [Hash, nil] The parameters (optional).
+      # @raise [JsonRpcError] if the ID is invalid.
       def initialize(id:, method:, params: nil)
         validate_id(id)
         super
       end
 
+      # Returns a hash representation of the request.
+      #
+      # @return [Hash] The hash representation.
       def to_h
         hash = {
           jsonrpc: "2.0",
@@ -20,6 +30,10 @@ module ActionMCP
 
       private
 
+      # Validates the ID.
+      #
+      # @param id [Object] The ID to validate.
+      # @raise [JsonRpcError] if the ID is invalid.
       def validate_id(id)
         unless id.is_a?(String) || id.is_a?(Numeric)
           raise JsonRpcError.new(:invalid_params,