actionmcp 0.2.0 → 0.2.4

data/exe/actionmcp_cli

@@ -0,0 +1,221 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup' # Ensure correct gem dependencies
+require 'optparse'
+require 'multi_json'
+require 'actionmcp'
+require 'action_mcp/client'
+require 'securerandom'
+require 'logger'
+
+# Default options
+options = {
+  logging_level: "INFO",
+  auto_initialize: true
+}
+
+# Set up logger
+logger = Logger.new(STDOUT)
+logger.formatter = proc do |severity, _, _, msg|
+  "#{severity}: #{msg}\n"
+end
+
+# Parse command-line arguments
+parser = OptionParser.new do |opts|
+  opts.banner = "Usage: mcp_client ENDPOINT [options]"
+  opts.on("-l", "--log-level LEVEL", "Set log level (DEBUG, INFO, WARN, ERROR)") do |l|
+    options[:logging_level] = l.upcase
+    logger.level = Logger.const_get(l.upcase) rescue Logger::INFO
+  end
+  opts.on("--no-auto-init", "Don't automatically initialize the connection") do
+    options[:auto_initialize] = false
+  end
+  opts.on("-h", "--help", "Show this help message") do
+    puts opts
+    exit
+  end
+end
+
+# Extract first argument as endpoint
+endpoint = ARGV.shift
+
+# Parse remaining options
+parser.parse!(ARGV)
+
+if endpoint.nil?
+  puts "Error: You must provide an MCP endpoint."
+  puts parser
+  exit 1
+end
+
+# Function to generate a unique request ID
+def generate_request_id
+  SecureRandom.uuid
+end
+
+# Function to parse command shortcuts and return a Request object
+def parse_command(input)
+  parts = input.strip.split(/\s+/)
+  command = parts.shift
+
+  case command
+  when "call_tool"
+    tool_name = parts.shift
+    return nil unless tool_name
+
+    arguments = {}
+    parts.each do |arg|
+      key, value = arg.split(":", 2)
+      next unless value
+
+      # Try to convert the value to appropriate type
+      parsed_value = case value
+      when /^\d+$/
+                       value.to_i
+      when /^\d+\.\d+$/
+                       value.to_f
+      when "true"
+                       true
+      when "false"
+                       false
+      when "null"
+                       nil
+      else
+                       value
+      end
+
+      arguments[key] = parsed_value
+    end
+
+    ActionMCP::JsonRpc::Request.new(
+      id: generate_request_id,
+      method: "tools/get",
+      params: {
+        "name" => tool_name,
+        "arguments" => arguments
+      }
+    )
+  when "list_tools"
+    ActionMCP::JsonRpc::Request.new(
+      id: generate_request_id,
+      method: "tools/list"
+    )
+  when "list_prompts"
+    ActionMCP::JsonRpc::Request.new(
+      id: generate_request_id,
+      method: "prompts/list"
+    )
+  else
+    nil
+  end
+end
+
+# Help message for shortcuts
+def print_help
+  puts "Available shortcuts:"
+  puts "  list_tools"
+  puts "    - Get a list of available tools"
+  puts "  call_tool TOOL_NAME PARAM1:VALUE1 PARAM2:VALUE2 ..."
+  puts "    - Sends a tools/get request with the specified tool and parameters"
+  puts "  list_prompts"
+  puts "    - Get a list of available prompts"
+  puts "  get_prompt PROMPT_NAME PARAM1:VALUE1 PARAM2:VALUE2 ..."
+  puts "    - Sends a prompts/get request with the specified prompt and arguments"
+  puts "  help - Show this help message"
+  puts "  exit - Quit the client"
+  puts "Otherwise, enter a raw JSON-RPC request to send directly"
+end
+
+# Initialize and start the client
+client = ActionMCP.create_client(endpoint, logger: logger)
+
+# Start the transport
+unless client.connect
+  error_msg = client.connection_error || "Unknown connection error"
+  puts "\nERROR: Failed to connect to MCP server at #{endpoint}"
+  puts "Reason: #{error_msg}"
+  puts "\nPlease check that:"
+  puts "  1. The server is running"
+  puts "  2. The endpoint URL/address is correct"
+  puts "  3. Any required firewall ports are open"
+
+  if endpoint =~ /\Ahttps?:\/\//
+    puts "  4. The URL includes the correct protocol, host, and port"
+    puts "     For example: http://localhost:3000/action_mcp"
+  end
+
+  exit 1
+end
+
+Signal.trap("INT") do
+  puts "\nReceived Ctrl+C. Disconnecting..."
+  client.disconnect
+  puts "MCP Client stopped."
+  exit 0
+end
+
+# Main REPL loop
+loop do
+  print "mcp> "
+  input = gets&.chomp
+  break unless input # Handle EOF
+  next if input.empty?
+
+  case input.downcase
+  when "exit"
+    break
+  when "help"
+    print_help
+    next
+  else
+    begin
+      # Check if input is a command shortcut
+      if input.start_with?("call_tool")
+        request = parse_command(input)
+        logger.debug("Parsed shortcut to: #{request.to_h}") if request
+      elsif input.start_with?("connect") || input.start_with?("initialize")
+        request = parse_command(input)
+        logger.debug("Initializing connection with: #{request.to_h}") if request
+      elsif input.start_with?("list_tools") || input.start_with?("list_prompts")
+        request = parse_command(input)
+        logger.debug("Requesting tool list: #{request.to_h}") if request
+      else
+        # Try parsing as JSON and creating a Request object
+        begin
+          json = MultiJson.load(input)
+          # Validate that the parsed JSON has the required fields
+          if json["method"]
+            request = ActionMCP::JsonRpc::Request.new(
+              id: json["id"] || generate_request_id,
+              method: json["method"],
+              params: json["params"]
+            )
+          else
+            puts "Invalid JSON-RPC request: missing 'method' field"
+            next
+          end
+        rescue MultiJson::ParseError => e
+          puts "Invalid input: not a valid command or JSON. #{e.message}"
+          next
+        rescue ActionMCP::JsonRpc::JsonRpcError => e
+          puts "Invalid JSON-RPC request: #{e.message}"
+          next
+        end
+      end
+
+      if request
+        client.send_request(request.to_h)
+      else
+        puts "Invalid command format. Type 'help' for available commands."
+      end
+    rescue StandardError => e
+      puts "Error: #{e.message}"
+      puts e.backtrace.first(5) if logger.level == Logger::DEBUG
+    end
+  end
+end
+
+puts "Disconnecting..."
+client.disconnect
+puts "MCP Client stopped."

data/lib/action_mcp/capability.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "renderable"
+
+module ActionMCP
+  class Capability
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+    include Renderable
+
+    class_attribute :_capability_name, instance_accessor: false
+    class_attribute :_description, instance_accessor: false, default: ""
+    class_attribute :abstract_tool, instance_accessor: false, default: false
+
+    # use _capability_name or default_capability_name
+    def self.capability_name
+      _capability_name || default_capability_name
+    end
+
+    def self.abstract_capability
+      @abstract_tool ||= false # Default to false, unique to each class
+    end
+
+    def self.abstract_capability=(value)
+      @abstract_tool = value
+    end
+
+    # Marks this tool as abstract so that it won’t be available for use.
+    # If the tool is registered in ToolsRegistry, it is unregistered.
+    #
+    # @return [void]
+    def self.abstract!
+      self.abstract_capability = true
+    end
+
+    # Returns whether this tool is abstract.
+    #
+    # @return [Boolean] true if abstract, false otherwise.
+    def self.abstract?
+      abstract_capability
+    end
+
+
+    def self.description(text = nil)
+      if text
+        self._description = text
+      else
+        _description
+      end
+    end
+  end
+end

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