actionmcp 0.31.1 → 0.33.0

data/lib/action_mcp/server/solid_cable_adapter.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "concurrent/map"
+require "concurrent/array"
+require "concurrent/executor/thread_pool_executor"
+
+module ActionMCP
+  module Server
+    # Mock SolidCable::PubSub for testing
+    class MockSolidCablePubSub
+      attr_reader :subscriptions, :messages
+
+      def initialize(options = {})
+        @options = options
+        @subscriptions = Concurrent::Map.new
+        @messages = Concurrent::Array.new
+      end
+
+      def subscribe(channel, &block)
+        @subscriptions[channel] ||= Concurrent::Array.new
+        @subscriptions[channel] << block
+      end
+
+      def unsubscribe(channel)
+        @subscriptions.delete(channel)
+      end
+
+      def broadcast(channel, message)
+        @messages << { channel: channel, message: message }
+        callbacks = @subscriptions[channel] || []
+        callbacks.each { |callback| callback.call(message) }
+      end
+    end
+
+    # Adapter for SolidCable PubSub
+    class SolidCableAdapter
+      # Thread pool configuration
+      DEFAULT_MIN_THREADS = 5
+      DEFAULT_MAX_THREADS = 10
+      DEFAULT_MAX_QUEUE = 100
+      DEFAULT_THREAD_TIMEOUT = 60  # seconds
+
+      def initialize(options = {})
+        @options = options
+        @subscriptions = Concurrent::Map.new
+        @channels = Concurrent::Map.new
+        @channel_subscribed = Concurrent::Map.new  # Track channel subscription status
+
+        # Initialize thread pool for callbacks
+        pool_options = {
+          min_threads: options["min_threads"] || DEFAULT_MIN_THREADS,
+          max_threads: options["max_threads"] || DEFAULT_MAX_THREADS,
+          max_queue: options["max_queue"] || DEFAULT_MAX_QUEUE,
+          fallback_policy: :caller_runs, # Execute in the caller's thread if queue is full
+          idletime: DEFAULT_THREAD_TIMEOUT
+        }
+        @thread_pool = Concurrent::ThreadPoolExecutor.new(pool_options)
+
+        # Configure SolidCable with options from mcp.yml
+        # The main option we care about is polling_interval
+        pubsub_options = {}
+
+        if @options["polling_interval"]
+          # Convert from ActiveSupport::Duration if needed (e.g., "0.1.seconds")
+          interval = @options["polling_interval"]
+          interval = interval.to_f if interval.respond_to?(:to_f)
+          pubsub_options[:polling_interval] = interval
+        end
+
+        # If there's a connects_to option, pass it along
+        if @options["connects_to"]
+          pubsub_options[:connects_to] = @options["connects_to"]
+        end
+
+        # Use mock version for testing or real version in production
+        if defined?(SolidCable) && !testing?
+          @solid_cable_pubsub = SolidCable::PubSub.new(pubsub_options)
+        else
+          @solid_cable_pubsub = MockSolidCablePubSub.new(pubsub_options)
+        end
+      end
+
+      # Subscribe to a channel
+      # @param channel [String] The channel name
+      # @param message_callback [Proc] Callback for received messages
+      # @param success_callback [Proc] Callback for successful subscription
+      # @return [String] Subscription ID
+      def subscribe(channel, message_callback, success_callback = nil)
+        subscription_id = SecureRandom.uuid
+
+        @subscriptions[subscription_id] = {
+          channel: channel,
+          message_callback: message_callback
+        }
+
+        @channels[channel] ||= Concurrent::Array.new
+        @channels[channel] << subscription_id
+
+        # Subscribe to SolidCable only if we haven't already subscribed to this channel
+        unless subscribed_to_solid_cable?(channel)
+          @solid_cable_pubsub.subscribe(channel) do |message|
+            dispatch_message(channel, message)
+          end
+          @channel_subscribed[channel] = true
+        end
+
+        log_subscription_event(channel, "Subscribed", subscription_id)
+        success_callback&.call
+
+        subscription_id
+      end
+
+      # Unsubscribe from a channel
+      # @param channel [String] The channel name
+      # @param callback [Proc] Optional callback for unsubscribe completion
+      def unsubscribe(channel, callback = nil)
+        # Remove our subscriptions
+        subscription_ids = @channels[channel] || []
+        subscription_ids.each do |subscription_id|
+          @subscriptions.delete(subscription_id)
+        end
+
+        @channels.delete(channel)
+
+        # Only unsubscribe from SolidCable if we're actually subscribed
+        if subscribed_to_solid_cable?(channel)
+          @solid_cable_pubsub.unsubscribe(channel)
+          @channel_subscribed.delete(channel)
+        end
+
+        log_subscription_event(channel, "Unsubscribed")
+        callback&.call
+      end
+
+      # Broadcast a message to a channel
+      # @param channel [String] The channel name
+      # @param message [String] The message to broadcast
+      def broadcast(channel, message)
+        @solid_cable_pubsub.broadcast(channel, message)
+        log_broadcast_event(channel, message)
+      end
+
+      # Check if a channel has subscribers
+      # @param channel [String] The channel name
+      # @return [Boolean] True if channel has subscribers
+      def has_subscribers?(channel)
+        subscribers = @channels[channel]
+        return false unless subscribers
+        !subscribers.empty?
+      end
+
+      # Check if we're already subscribed to a channel
+      # @param channel [String] The channel name
+      # @return [Boolean] True if we're already subscribed
+      def subscribed_to?(channel)
+        channel_subs = @channels[channel]
+        return false if channel_subs.nil?
+        !channel_subs.empty?
+      end
+
+      # Shut down the thread pool gracefully
+      def shutdown
+        @thread_pool.shutdown
+        @thread_pool.wait_for_termination(5) # Wait up to 5 seconds for tasks to complete
+      end
+
+      private
+
+      # Check if we're in a testing environment
+      def testing?
+        defined?(Minitest) || ENV["RAILS_ENV"] == "test"
+      end
+
+      # Check if we're already subscribed to this channel in SolidCable
+      def subscribed_to_solid_cable?(channel)
+        @channel_subscribed[channel] == true
+      end
+
+      def dispatch_message(channel, message)
+        subscription_ids = @channels[channel] || []
+
+        subscription_ids.each do |subscription_id|
+          subscription = @subscriptions[subscription_id]
+          next unless subscription && subscription[:message_callback]
+
+          @thread_pool.post do
+            begin
+              subscription[:message_callback].call(message)
+            rescue StandardError => e
+              log_error("Error in message callback: #{e.message}\n#{e.backtrace.join("\n")}")
+            end
+          end
+        end
+      end
+
+      def log_subscription_event(channel, action, subscription_id = nil)
+        return unless defined?(Rails) && Rails.respond_to?(:logger)
+
+        message = "SolidCableAdapter: #{action} channel=#{channel}"
+        message += " subscription_id=#{subscription_id}" if subscription_id
+
+        Rails.logger.debug(message)
+      end
+
+      def log_broadcast_event(channel, message)
+        return unless defined?(Rails) && Rails.respond_to?(:logger)
+
+        # Truncate the message for logging
+        truncated_message = message.to_s[0..100]
+        truncated_message += "..." if message.to_s.length > 100
+
+        Rails.logger.debug("SolidCableAdapter: Broadcasting to channel=#{channel} message=#{truncated_message}")
+      end
+
+      def log_error(message)
+        return unless defined?(Rails) && Rails.respond_to?(:logger)
+        Rails.logger.error("SolidCableAdapter: #{message}")
+      end
+    end
+  end
+end

data/lib/action_mcp/server/tools.rb

@@ -3,19 +3,63 @@
 module ActionMCP
   module Server
     module Tools
-      def send_tools_list(request_id)
-        tools = format_registry_items(ToolsRegistry.non_abstract)
+      def send_tools_list(request_id, params = {})
+        protocol_version = session.protocol_version
+        # Extract progress token from _meta if provided
+        progress_token = params.dig("_meta", "progressToken")
+
+        # Send initial progress notification if token is provided
+        if progress_token
+          session.send_progress_notification(
+            progressToken: progress_token,
+            progress: 0,
+            message: "Starting tools list retrieval"
+          )
+        end
+
+        # Use session's registered tools instead of global registry
+        tools = session.registered_tools.map { |tool_class|
+          tool_class.to_h(protocol_version: protocol_version)
+        }
+
+        # Send completion progress notification if token is provided
+        if progress_token
+          session.send_progress_notification(
+            progressToken: progress_token,
+            progress: 100,
+            message: "Tools list retrieval complete"
+          )
+        end
+
         send_jsonrpc_response(request_id, result: { tools: tools })
       end
 
       def send_tools_call(request_id, tool_name, arguments, _meta = {})
-        result = ToolsRegistry.tool_call(tool_name, arguments, _meta)
-        if result.is_error
-          send_jsonrpc_response(request_id, error: result)
+        # Find tool in session's registry
+        tool_class = session.registered_tools.find { |t| t.tool_name == tool_name }
+
+        if tool_class
+          # Create tool and set execution context
+          tool = tool_class.new(arguments)
+          tool.with_context({ session: session })
+
+          result = tool.call
+
+          if result.is_error
+            send_jsonrpc_response(request_id, error: result)
+          else
+            send_jsonrpc_response(request_id, result: result)
+          end
         else
-          send_jsonrpc_response(request_id, result:)
+          send_jsonrpc_error(request_id, :method_not_found, "Tool '#{tool_name}' not available in this session")
         end
       end
+
+      private
+
+      def format_registry_items(registry, protocol_version = nil)
+        registry.map { |item| item.klass.to_h(protocol_version: protocol_version) }
+      end
     end
   end
 end

data/lib/action_mcp/server.rb

@@ -1,13 +1,95 @@
 # frozen_string_literal: true
 
-# TODO: move all server related code here before version 1.0.0
+require_relative "server/simple_pub_sub"
+require_relative "server/configuration"
+
+# Conditionally load adapters based on available gems
+begin
+  require "solid_cable/pubsub"
+  require_relative "server/solid_cable_adapter"
+rescue LoadError
+  # SolidCable not available
+end
+
 module ActionMCP
   # Module for server-related functionality.
   module Server
     module_function
 
     def server
-      @server ||= ActionCable::Server::Base.new
+      @server ||= ServerBase.new
+    end
+
+    # Shut down the server and clean up resources
+    def shutdown
+      return unless @server
+      @server.shutdown
+      @server = nil
+    end
+
+    # Available pubsub adapter types
+    ADAPTERS = {
+      "test" => "SimplePubSub",
+      "simple" => "SimplePubSub",
+      "solid_cable" => "SolidCableAdapter" # Will use mock version in tests
+    }.compact.freeze
+
+    # Custom server base class for PubSub functionality
+    class ServerBase
+      def initialize(config_path = nil)
+        @configuration = Configuration.new(config_path)
+      end
+
+      def pubsub
+        @pubsub ||= create_pubsub
+      end
+
+      # Allow manual override of the configuration
+      # @param config_path [String] Path to a cable.yml configuration file
+      def configure(config_path)
+        shutdown_pubsub if @pubsub
+        @configuration = Configuration.new(config_path)
+        @pubsub = nil  # Reset pubsub so it will be recreated with new config
+      end
+
+      # Gracefully shut down the server and its resources
+      def shutdown
+        shutdown_pubsub
+      end
+
+      private
+
+      # Shut down the pubsub adapter gracefully
+      def shutdown_pubsub
+        return unless @pubsub && @pubsub.respond_to?(:shutdown)
+
+        begin
+          @pubsub.shutdown
+        rescue => e
+          message = "Error shutting down pubsub adapter: #{e.message}"
+          Rails.logger.error(message) if defined?(Rails) && Rails.respond_to?(:logger)
+        ensure
+          @pubsub = nil
+        end
+      end
+
+      def create_pubsub
+        adapter_name = @configuration.adapter_name
+        adapter_options = @configuration.adapter_options
+
+        # Default to simple if adapter not found
+        adapter_class_name = ADAPTERS[adapter_name] || "SimplePubSub"
+
+        begin
+          # Create an instance of the adapter class with the configuration options
+          adapter_class = ActionMCP::Server.const_get(adapter_class_name)
+          adapter_class.new(adapter_options)
+        rescue NameError, LoadError => e
+          message = "Error creating adapter #{adapter_name}: #{e.message}"
+          Rails.logger.error(message) if defined?(Rails) && Rails.respond_to?(:logger)
+          SimplePubSub.new  # Fallback to simple pubsub
+        end
+      end
     end
   end
 end

data/lib/action_mcp/sse_listener.rb

@@ -4,7 +4,7 @@ require "concurrent/atomic/atomic_boolean"
 require "concurrent/promise"
 
 module ActionMCP
-  # Listener class to subscribe to session messages via Action Cable adapter.
+  # Listener class to subscribe to session messages via PubSub adapter.
   class SSEListener
     delegate :session_key, :adapter, to: :@session
 
@@ -15,22 +15,22 @@ module ActionMCP
       @subscription_active = Concurrent::AtomicBoolean.new
     end
 
-    # Start listening using ActionCable's adapter
+    # Start listening using PubSub adapter
     # @yield [Hash] Yields parsed message received from the pub/sub channel
     # @return [Boolean] True if subscription was successful within timeout, false otherwise.
     def start(&callback)
       Rails.logger.debug "SSEListener: Starting for channel: #{session_key}"
 
-      success_callback = -> {
+      success_callback = lambda {
         Rails.logger.info "SSEListener: Successfully subscribed to channel: #{session_key}"
         @subscription_active.make_true
       }
 
-      message_callback = ->(raw_message) {
+      message_callback = lambda { |raw_message|
         process_message(raw_message, callback)
       }
 
-      # Subscribe using the ActionCable adapter
+      # Subscribe using the PubSub adapter
       adapter.subscribe(session_key, message_callback, success_callback)
 
       wait_for_subscription
@@ -81,6 +81,7 @@ module ActionMCP
 
     def valid_json_format?(string)
       return false if string.blank?
+
       string = string.strip
       (string.start_with?("{") && string.end_with?("}")) ||
         (string.start_with?("[") && string.end_with?("]"))

data/lib/action_mcp/tagged_stream_logging.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# frozen_string_literal: true
+
+# lib/action_mcp/tagged_io_logging.rb
+
+module ActionMCP
+  module TaggedStreamLogging
+    # ────────────  ANSI COLOURS  ────────────
+    CLR        = "\e[0m"
+    BLUE_TX    = "\e[34m"  # outgoing JSON‑RPC (TX)
+    GREEN_RX   = "\e[32m"  # incoming JSON‑RPC (RX)
+    YELLOW_ERR = "\e[33m"  # decode / validation warnings
+    RED_FATAL  = "\e[31m"  # unexpected exceptions
+
+    # ———  Outbound: any frame we ‘write’ to the wire  ———
+    def write_message(data)
+      pretty = json_normalise(data)
+      ActionMCP.logger.tagged("MCP", "TX") { ActionMCP.logger.debug("#{BLUE_TX}#{pretty}#{CLR}") }
+      super
+    rescue StandardError => e
+      ActionMCP.logger.tagged("MCP", "TX") { ActionMCP.logger.error("#{RED_FATAL}#{e.message}#{CLR}") }
+      raise
+    end
+
+    # ———  Inbound: every raw line handed to the JSON‑RPC handler  ———
+    def read(line)
+      pretty = json_normalise(line)
+      ActionMCP.logger.tagged("MCP", "RX") { ActionMCP.logger.debug("#{GREEN_RX}#{pretty}#{CLR}") }
+      super
+    rescue MultiJson::ParseError => e
+      ActionMCP.logger.tagged("MCP", "RX") { ActionMCP.logger.warn("#{YELLOW_ERR}Bad JSON → #{e.message}#{CLR}") }
+      raise
+    rescue StandardError => e
+      ActionMCP.logger.tagged("MCP", "RX") { ActionMCP.logger.error("#{RED_FATAL}#{e.message}#{CLR}") }
+      raise
+    end
+
+    private
+
+    # Accepts String, Hash, or any #to_json‑able object.
+    def json_normalise(obj)
+      str = obj.is_a?(String) ? obj.strip : MultiJson.dump(obj)
+      str.empty? ? "<empty frame>" : str
+    end
+  end
+end

data/lib/action_mcp/test_helper.rb

@@ -3,53 +3,76 @@
 require "active_support/testing/assertions"
 
 module ActionMCP
+  #---------------------------------------------------------------------------
+  # ActionMCP::TestHelper
+  #
+  # Include in any `ActiveSupport::TestCase`:
+  #
+  #   include ActionMCP::TestHelper
+  #
+  # and you get   assert_mcp_tool_findable,
+  #               assert_mcp_prompt_findable,
+  #               execute_mcp_tool,
+  #               execute_mcp_prompt,
+  #               assert_mcp_error_code,
+  #               assert_mcp_tool_output,
+  #               assert_mcp_prompt_output.
+  #
+  # Short alias names (without the prefix) remain for this gem’s own suite but
+  # are *not* documented for public use.
+  #---------------------------------------------------------------------------
   module TestHelper
     include ActiveSupport::Testing::Assertions
 
-    # Asserts that a tool is findable in the ToolsRegistry.
-    # @param [String] tool_name
-    def assert_tool_findable(tool_name)
-      assert ActionMCP::ToolsRegistry.tools.key?(tool_name), "Tool #{tool_name} not found in registry"
+    # ──── Registry assertions ────────────────────────────────────────────────
+    def assert_mcp_tool_findable(name, msg = nil)
+      assert ActionMCP::ToolsRegistry.tools.key?(name),
+             msg || "Tool #{name.inspect} not found in ToolsRegistry"
     end
+    alias assert_tool_findable assert_mcp_tool_findable
 
-    # Asserts that a prompt is findable in the PromptsRegistry.
-    # @param [String] prompt_name
-    def assert_prompt_findable(prompt_name)
-      assert ActionMCP::PromptsRegistry.prompts.key?(prompt_name), "Prompt #{prompt_name} not found in registry"
+    def assert_mcp_prompt_findable(name, msg = nil)
+      assert ActionMCP::PromptsRegistry.prompts.key?(name),
+             msg || "Prompt #{name.inspect} not found in PromptsRegistry"
     end
+    alias assert_prompt_findable assert_mcp_prompt_findable
 
-    # Executes a tool with the given name and arguments.
-    # @param [String] tool_name
-    # @param [Hash] args
-    def execute_tool(tool_name, args = {})
-      result = ActionMCP::ToolsRegistry.tool_call(tool_name, args)
-      assert_not result.is_error, "Tool #{tool_name} returned an error: #{result.to_h[:message]}"
-      result
+    # ──── Execution helpers (happy‑path only) ────────────────────────────────
+    def execute_mcp_tool(name, args = {})
+      resp = ActionMCP::ToolsRegistry.tool_call(name, args)
+      assert !resp.is_error, "Tool #{name.inspect} returned error: #{resp.to_h[:message]}"
+      resp
     end
+    alias execute_tool execute_mcp_tool
 
-    # Executes a prompt with the given name and arguments.
-    # @param [String] prompt_name
-    # @param [Hash] args
-    def execute_prompt(prompt_name, args = {})
-      result = ActionMCP::PromptsRegistry.prompt_call(prompt_name, args)
-      assert_not result.is_error, "Prompt #{prompt_name} returned an error: #{result.to_h[:message]}"
-      result
+    def execute_mcp_prompt(name, args = {})
+      resp = ActionMCP::PromptsRegistry.prompt_call(name, args)
+      assert !resp.is_error, "Prompt #{name.inspect} returned error: #{resp.to_h[:message]}"
+      resp
     end
+    alias execute_prompt execute_mcp_prompt
 
-    # Asserts that the output of a tool is equal to the expected output.
-    # @param [Hash] expected_output
-    # @param [ActionMCP::ToolResponse] result
-    def assert_tool_output(expected_output, result)
-      assert_equal expected_output, result.to_h[:content],
-                   "Tool output did not match expected output #{expected_output} != #{result.to_h[:content]}"
+    # ──── Negative‑path helper ───────────────────────────────────────────────
+    def assert_mcp_error_code(code, response, msg = nil)
+      assert response.error?, msg || "Expected response to be an error"
+      assert_equal code, response.to_h[:code],
+                   msg || "Expected error code #{code}, got #{response.to_h[:code]}"
     end
+    alias assert_error_code assert_mcp_error_code
 
-    # Asserts that the output of a prompt is equal to the expected output.
-    # @param [Hash] expected_output
-    # @param [ActionMCP::PromptResponse] result
-    def assert_prompt_output(expected_output, result)
-      assert_equal expected_output, result.to_h[:messages],
-                   "Prompt output did not match expected output #{expected_output} != #{result.to_h[:messages]}"
+    # ──── Output assertions ─────────────────────────────────────────────────
+    def assert_mcp_tool_output(expected, response, msg = nil)
+      assert response.success?, msg || "Expected a successful tool response"
+      assert_equal expected, response.contents.map(&:to_h),
+                   msg || "Tool output did not match expected"
     end
+    alias assert_tool_output assert_mcp_tool_output
+
+    def assert_mcp_prompt_output(expected, response, msg = nil)
+      assert response.success?, msg || "Expected a successful prompt response"
+      assert_equal expected, response.messages,
+                   msg || "Prompt output did not match expected"
+    end
+    alias assert_prompt_output assert_mcp_prompt_output
   end
 end