actionmcp 0.31.1 → 0.32.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '04854ab6466f148e4d5db713d595acbedbe52420cdf7cfc9c1635a61b513678d'
-  data.tar.gz: 69ed1465da06169ed2115c63d108be8cc1d1c5ecc988d1c2ac563dc5ad41c3b9
+  metadata.gz: 54b807ad23c23796ef5495fb91afffb9ee10d998516a72d20897c519bed56c4c
+  data.tar.gz: e5ec996f8e8dcb73383de34fe5f851382961a74a27e3b28c26271aadb343c30f
 SHA512:
-  metadata.gz: 38d9feb89e3f5584cdca0ed4adf27ee02321d97c125513ad114e335a0a7c701fbc7ce5e69ec448d806e020a9d89c6f6b91c220a96030422866b1788ed9eb9775
-  data.tar.gz: 903100988152291df5ea15f53b3c859721bdee80e22a7440999c7cc8a219ae2fbd63f6e18e34d3b481a2e60301712316284d74dd7ae877c89945bebbb7dfb504
+  metadata.gz: 55938823b5df5d13b8ffe2adbb9e581331e60fabb2f7111807fa10b119cd898f2ab3dd695cbda8924af0b9be79cf9eb0767b18324a1042ac46fb4facb6562abe
+  data.tar.gz: 76c6c5a553e55f06b61165844a3d55e45854dffe515879f14eaaf5b1399aa8f3273563b3c78cf028bab54547cc3165947cd5e2606e19f96be55285c845c641ef

data/README.md

@@ -169,6 +169,7 @@ class ProductResourceTemplate < ApplicationMCPResTemplate
     )
   end
 end
+```
 
 # Example of callbacks:
 
@@ -222,15 +223,25 @@ For dynamic versioning, consider adding the `rails_app_version` gem.
 
 ## Engine and Mounting
 
-ActionMCP is implemented as a Rails engine, which means it can be mounted in your application's routes.
-The engine provides no authentication or authorization by default, so you'll need to handle that in your application for now.
+**ActionMCP** runs as a standalone Rack application, similar to **ActionCable**. It is **not** mounted in `routes.rb`.
+
+> **Note:** Authentication and authorization are not included. You are responsible for securing the endpoint.
 
-To mount the ActionMCP engine in your routes, add the following line to your `config/routes.rb`:
+### 1. Create `mcp.ru`
 
 ```ruby
-Rails.application.routes.draw do
-  mount ActionMCP::Engine => "/action_mcp"
+# Load the full Rails environment to access models, DB, Redis, etc.
+require_relative "config/environment"
+
+ActionMCP.configure do |config|
+  config.mcp_endpoint_path = "/mcp"
 end
+
+run ActionMCP::Engine
+```
+### 2. Start the server
+```bash
+bin/rails s -c mcp.ru -p 6277 -P tmp/pids/mcp.pid
 ```
 
 ## Generators

data/app/controllers/action_mcp/mcp_controller.rb

@@ -33,51 +33,47 @@ module ActionMCP
     def find_or_initialize_session
       session_id = extract_session_id
       if session_id
-        # Attempt to find the session by ID. Return nil if not found.
-        # Controllers should handle the nil case (e.g., return 404).
-        Session.find_by(id: session_id)
+        session = Session.find_by(id: session_id)
+        if session && session.protocol_version != self.class::REQUIRED_PROTOCOL_VERSION
+          # Update existing session to use 2025 protocol
+          session.update!(protocol_version: self.class::REQUIRED_PROTOCOL_VERSION)
+        end
+        session
       else
-        # No session ID provided, initialize a new one (likely for 'initialize' request).
-        Session.new
+        # Create new session with 2025 protocol
+        Session.new(protocol_version: self.class::REQUIRED_PROTOCOL_VERSION)
       end
     end
 
-    # Extracts the session ID from the request header or parameters.
-    # Prefers the Mcp-Session-Id header (new spec) over the param (old spec).
-    # @return [String, nil] The extracted session ID or nil if not found.
-    def extract_session_id
-      request.headers[MCP_SESSION_ID_HEADER].presence || params[:session_id].presence
-    end
-
     # Renders a 400 Bad Request response with a JSON-RPC-like error structure.
     def render_bad_request(message = "Bad Request")
       # Using -32600 for Invalid Request based on JSON-RPC spec
-      render json: { jsonrpc: "2.0", error: { code: -32_600, message: message } }, status: :bad_request
+      render json: { jsonrpc: "2.0", error: { code: -32_600, message: message } }
     end
 
     # Renders a 404 Not Found response with a JSON-RPC-like error structure.
     def render_not_found(message = "Not Found")
       # Using a custom code or a generic server error range code might be appropriate.
       # Let's use -32001 for a generic server error.
-      render json: { jsonrpc: "2.0", error: { code: -32_001, message: message } }, status: :not_found
+      render json: { jsonrpc: "2.0", error: { code: -32_001, message: message } }
     end
 
     # Renders a 405 Method Not Allowed response.
     def render_method_not_allowed(message = "Method Not Allowed")
       # Using -32601 Method not found from JSON-RPC spec seems applicable
-      render json: { jsonrpc: "2.0", error: { code: -32_601, message: message } }, status: :method_not_allowed
+      render json: { jsonrpc: "2.0", error: { code: -32_601, message: message } }
     end
 
     # Renders a 406 Not Acceptable response.
     def render_not_acceptable(message = "Not Acceptable")
       # No direct JSON-RPC equivalent, using a generic server error code.
-      render json: { jsonrpc: "2.0", error: { code: -32_002, message: message } }, status: :not_acceptable
+      render json: { jsonrpc: "2.0", error: { code: -32_002, message: message } }
     end
 
     # Renders a 501 Not Implemented response.
     def render_not_implemented(message = "Not Implemented")
       # No direct JSON-RPC equivalent, using a generic server error code.
-      render json: { jsonrpc: "2.0", error: { code: -32_003, message: message } }, status: :not_implemented
+      render json: { jsonrpc: "2.0", error: { code: -32_003, message: message } }
     end
   end
 end

data/app/controllers/action_mcp/messages_controller.rb

@@ -2,6 +2,8 @@
 
 module ActionMCP
   class MessagesController < MCPController
+    REQUIRED_PROTOCOL_VERSION = "2024-11-05"
+
     include Instrumentation::ControllerRuntime
 
     # @route POST / (sse_in)
@@ -34,7 +36,7 @@ module ActionMCP
 
     def filter_jsonrpc_params(params)
       # Valid JSON-RPC keys (both request and response)
-      valid_keys = [ "jsonrpc", "method", "params", "id", "result", "error" ]
+      valid_keys = %w[jsonrpc method params id result error]
 
       params.to_h.slice(*valid_keys)
     end

data/app/controllers/action_mcp/sse_controller.rb

@@ -2,6 +2,8 @@
 
 module ActionMCP
   class SSEController < MCPController
+    REQUIRED_PROTOCOL_VERSION = "2024-11-05"
+
     HEARTBEAT_INTERVAL = 30 # in seconds
     INITIAL_CONNECTION_TIMEOUT = 5 # in seconds
     include ActionController::Live
@@ -35,8 +37,16 @@ module ActionMCP
             error = build_timeout_error
             # Safely write error and close the stream
             Concurrent::Promise.execute do
-              sse.write(error) rescue nil
-              response.stream.close rescue nil
+              begin
+                sse.write(error)
+              rescue StandardError
+                nil
+              end
+              begin
+                response.stream.close
+              rescue StandardError
+                nil
+              end
               connection_active.make_false
             end
           end
@@ -108,8 +118,16 @@ module ActionMCP
         heartbeat_active&.make_false  # Signal to stop scheduling new heartbeats
         heartbeat_task&.cancel        # Cancel any pending heartbeat task
         listener&.stop
-        mcp_session.close! rescue nil
-        response.stream.close rescue nil
+        begin
+          mcp_session.close!
+        rescue StandardError
+          nil
+        end
+        begin
+          response.stream.close
+        rescue StandardError
+          nil
+        end
 
         Rails.logger.debug "SSE: Connection cleaned up for session: #{session_id}"
       end

data/app/controllers/action_mcp/unified_controller.rb

@@ -5,12 +5,15 @@ module ActionMCP
   # Supports GET for server-initiated SSE streams, POST for client messages
   # (responding with JSON or SSE), and optionally DELETE for session termination.
   class UnifiedController < MCPController
+    REQUIRED_PROTOCOL_VERSION = "2025-03-26"
+
+    include JSONRPC_Rails::ControllerHelpers
     include ActionController::Live
     # TODO: Include Instrumentation::ControllerRuntime if needed for metrics
 
     # Handles GET requests for establishing server-initiated SSE streams (2025-03-26 spec).
     # @route GET /mcp
-    def handle_get
+    def show
       # 1. Check Accept Header
       unless request.accepts.any? { |type| type.to_s == "text/event-stream" }
         return render_not_acceptable("Client must accept 'text/event-stream' for GET requests.")
@@ -30,7 +33,9 @@ module ActionMCP
         return render_not_found("Session has been terminated.")
       end
 
-      # TODO: Handle Last-Event-ID header for stream resumption
+      # Check for Last-Event-ID header for resumability
+      last_event_id = request.headers["Last-Event-ID"].presence
+      Rails.logger.info "Unified SSE (GET): Resuming from Last-Event-ID: #{last_event_id}" if last_event_id
 
       # 3. Set SSE Headers
       response.headers["Content-Type"] = "text/event-stream"
@@ -43,8 +48,10 @@ module ActionMCP
       # 4. Setup Stream, Listener, and Heartbeat
       sse = SSE.new(response.stream)
       listener = SSEListener.new(session) # Use the listener class (defined below or moved)
-      connection_active = Concurrent::AtomicBoolean.new(true)
-      heartbeat_active = Concurrent::AtomicBoolean.new(true)
+      connection_active = Concurrent::AtomicBoolean.new
+      connection_active.make_true
+      heartbeat_active = Concurrent::AtomicBoolean.new
+      heartbeat_active.make_true
       heartbeat_task = nil
 
       # Start listener
@@ -60,6 +67,27 @@ module ActionMCP
         return # Error logged, connection will close in ensure block
       end
 
+      # Handle resumability by sending missed events if Last-Event-ID is provided
+      if last_event_id.present? && last_event_id.to_i > 0
+        begin
+          # Fetch events that occurred after the Last-Event-ID
+          missed_events = session.get_sse_events_after(last_event_id.to_i)
+
+          if missed_events.any?
+            Rails.logger.info "Unified SSE (GET): Sending #{missed_events.size} missed events for session: #{session.id}"
+
+            # Send each missed event to the client
+            missed_events.each do |event|
+              sse.stream.write(event.to_sse)
+            end
+          else
+            Rails.logger.info "Unified SSE (GET): No missed events to send for session: #{session.id}"
+          end
+        rescue => e
+          Rails.logger.error "Unified SSE (GET): Error sending missed events: #{e.message}"
+        end
+      end
+
       # Heartbeat sender proc
       heartbeat_sender = lambda do
         if connection_active.true? && !response.stream.closed?
@@ -98,6 +126,10 @@ module ActionMCP
       heartbeat_active&.make_false
       heartbeat_task&.cancel
       listener&.stop
+
+      # Clean up old SSE events if resumability is enabled
+      cleanup_old_sse_events(session) if session
+
       # Don't close the session itself here, it might be used by other connections/requests
       sse&.close
       begin
@@ -109,18 +141,14 @@ module ActionMCP
 
     # Handles POST requests containing client JSON-RPC messages according to 2025-03-26 spec.
     # @route POST /mcp
-    def handle_post
+    def create
       # 1. Check Accept Header
       unless accepts_valid_content_types?
         return render_not_acceptable("Client must accept 'application/json' and 'text/event-stream'")
       end
 
-      # 2. Parse Request Body
-      parsed_body = parse_request_body
-      return unless parsed_body # Error rendered in parse_request_body
-
       # Determine if this is an initialize request (before session check)
-      is_initialize_request = check_if_initialize_request(parsed_body)
+      is_initialize_request = check_if_initialize_request(jsonrpc_params)
 
       # 3. Check Session (unless it's an initialize request)
       session_initially_missing = extract_session_id.nil?
@@ -134,13 +162,16 @@ module ActionMCP
           return render_not_found("Session has been terminated.")
         end
       end
-
+      if session.new_record?
+        session.save!
+        response.headers[MCP_SESSION_ID_HEADER] = session.id
+      end
       # 4. Instantiate Handlers
       transport_handler = Server::TransportHandler.new(session)
       json_rpc_handler = Server::JsonRpcHandler.new(transport_handler)
 
       # 5. Call Handler
-      handler_results = json_rpc_handler.call(parsed_body)
+      handler_results = json_rpc_handler.call(jsonrpc_params.to_h)
 
       # 6. Process Results
       process_handler_results(handler_results, session, session_initially_missing, is_initialize_request)
@@ -160,13 +191,7 @@ module ActionMCP
 
     # Handles DELETE requests for session termination (2025-03-26 spec).
     # @route DELETE /mcp
-    def handle_delete
-      allow_termination = ActionMCP.configuration.allow_client_session_termination
-
-      unless allow_termination
-        return render_method_not_allowed("Session termination via DELETE is not supported by this server.")
-      end
-
+    def destroy
       # 1. Check Session Header
       session_id_from_header = extract_session_id
       return render_bad_request("Mcp-Session-Id header is required for DELETE requests.") unless session_id_from_header
@@ -195,58 +220,91 @@ module ActionMCP
 
     private
 
+    # @return [String, nil] The extracted session ID or nil if not found.
+    def extract_session_id
+      request.headers[MCP_SESSION_ID_HEADER].presence
+    end
+
     # Checks if the client's Accept header includes the required types.
     def accepts_valid_content_types?
       request.accepts.any? { |type| type.to_s == "application/json" } &&
         request.accepts.any? { |type| type.to_s == "text/event-stream" }
     end
 
-    # Parses the JSON request body. Renders error if invalid.
-    def parse_request_body
-      body = request.body.read
-      MultiJson.load(body)
-    rescue MultiJson::ParseError => e
-      render_bad_request("Invalid JSON in request body: #{e.message}")
-      nil # Indicate failure
-    end
-
     # Checks if the parsed body represents an 'initialize' request.
-    def check_if_initialize_request(parsed_body)
-      if parsed_body.is_a?(Hash) && parsed_body["method"] == "initialize"
-        true
-      elsif parsed_body.is_a?(Array) # Cannot be in a batch
-        false
-      else
-        false
-      end
+    def check_if_initialize_request(payload)
+      return false unless payload.is_a?(JSON_RPC::Request) && !jsonrpc_params_batch?
+      payload.method == "initialize"
     end
 
     # Processes the results from the JsonRpcHandler.
     def process_handler_results(results, session, session_initially_missing, is_initialize_request)
-      case results[:type]
+      # Make sure we always have a results hash
+      results ||= {}
+
+      # Check if this is a notification request
+      is_notification = jsonrpc_params.is_a?(Hash) &&
+                        jsonrpc_params["method"].to_s.start_with?("notifications/") &&
+                        !jsonrpc_params.key?("id")
+
+      # Extract request ID from results
+      request_id = nil
+      if results.is_a?(Hash)
+        request_id = results[:request_id] || results[:id]
+
+        # If we have a payload that's a response, extract ID from there as well
+        if results[:payload].is_a?(Hash) && results[:payload][:id]
+          request_id ||= results[:payload][:id]
+        end
+      end
+
+      # Default to empty hash for response payload if nil
+      result_type = results[:type]
+      result_payload = results[:payload] || {}
+
+      # Ensure payload has the correct ID if it's a hash
+      if result_payload.is_a?(Hash) && request_id
+        result_payload[:id] = request_id unless result_payload.key?(:id)
+      end
+
+      # Check if the payload is a notification
+      is_notification_payload = result_payload.is_a?(Hash) &&
+                              result_payload[:method]&.to_s&.start_with?("notifications/") &&
+                              !result_payload.key?(:id)
+
+      case result_type
       when :error
-        # Handle handler-level errors (e.g., batch parse error)
-        render json: results[:payload], status: results.fetch(:status, :bad_request)
+        # Ensure error responses preserve the ID
+        error_payload = result_payload
+        if error_payload.is_a?(Hash) && !error_payload.key?(:id) && request_id
+          error_payload[:id] = request_id
+        end
+        render json: error_payload, status: results.fetch(:status, :bad_request)
       when :notifications_only
-        # No response needed, just accept
         head :accepted
       when :responses
-        # Determine response format based on server preference and client acceptance.
-        # Client MUST accept both 'application/json' and 'text/event-stream' (checked earlier).
-        server_preference = ActionMCP.configuration.post_response_preference # :json or :sse
+        server_preference = ActionMCP.configuration.post_response_preference
         use_sse = (server_preference == :sse)
 
-        # Add session ID header if this was a successful initialize request that created the session
         add_session_header = is_initialize_request && session_initially_missing && session.persisted?
 
         if use_sse
-          render_sse_response(results[:payload], session, add_session_header)
+          render_sse_response(result_payload, session, add_session_header)
         else
-          render_json_response(results[:payload], session, add_session_header)
+          render_json_response(result_payload, session, add_session_header)
         end
       else
-        # Should not happen
-        render_internal_server_error("Unknown handler result type: #{results[:type]}")
+        # This was causing the "Unknown handler result type: " error
+        Rails.logger.error "Unknown handler result type: #{result_type.inspect}"
+
+        # Return a proper JSON-RPC response with the preserved ID
+        # Default to a response with JSON-RPC message format
+        status = is_notification ? :accepted : :ok
+        render json: {
+          jsonrpc: "2.0",
+          id: request_id,
+          result: {}
+        }, status: status
       end
     end
 
@@ -254,11 +312,13 @@ module ActionMCP
     def render_json_response(payload, session, add_session_header)
       response.headers[MCP_SESSION_ID_HEADER] = session.id if add_session_header
       response.headers["Content-Type"] = "application/json"
+
       render json: payload, status: :ok
     end
 
     # Renders the JSON-RPC response(s) as an SSE stream.
     def render_sse_response(payload, session, add_session_header)
+      # This is not recommended with puma
       response.headers[MCP_SESSION_ID_HEADER] = session.id if add_session_header
       response.headers["Content-Type"] = "text/event-stream"
       response.headers["X-Accel-Buffering"] = "no"
@@ -285,17 +345,52 @@ module ActionMCP
     end
 
     # Renders a 500 Internal Server Error response.
-    def render_internal_server_error(message = "Internal Server Error")
+    def render_internal_server_error(message = "Internal Server Error", id = nil)
       # Using -32000 for generic server error
-      render json: { jsonrpc: "2.0", error: { code: -32_000, message: message } }, status: :internal_server_error
+      render json: { jsonrpc: "2.0", id: id, error: { code: -32_000, message: message } }
+    end
+
+    # Helper to clean up old SSE events for a session
+    def cleanup_old_sse_events(session)
+      return unless ActionMCP.configuration.enable_sse_resumability
+
+      begin
+        # Get retention period from configuration
+        retention_period = session.sse_event_retention_period
+        count = session.cleanup_old_sse_events(retention_period)
+
+        Rails.logger.debug "Cleaned up #{count} old SSE events for session: #{session.id}" if count > 0
+      rescue => e
+        Rails.logger.error "Error cleaning up old SSE events: #{e.message}"
+      end
     end
 
     # Helper to write a JSON payload as an SSE event with a unique ID.
+    # Also stores the event for potential resumability.
     def write_sse_event(sse, session, payload)
       event_id = session.increment_sse_counter!
+
       # Manually format the SSE event string including the ID
-      data = MultiJson.dump(payload)
-      sse.stream.write("id: #{event_id}\ndata: #{data}\n\n")
+      data = payload.is_a?(String) ? payload : MultiJson.dump(payload)
+      sse_event = "id: #{event_id}\ndata: #{data}\n\n"
+
+      # Write to the stream
+      sse.stream.write(sse_event)
+
+      # Store the event for potential resumption if resumability is enabled
+      if ActionMCP.configuration.enable_sse_resumability
+        begin
+          session.store_sse_event(event_id, payload, session.max_stored_sse_events)
+        rescue => e
+          Rails.logger.error "Failed to store SSE event for resumability: #{e.message}"
+        end
+      end
+    end
+
+    def format_tools_list(tools, session)
+      # Pass the session's protocol version when formatting tools
+      protocol_version = session.protocol_version || ActionMCP.configuration.protocol_version
+      tools.map { |tool| tool.klass.to_h(protocol_version: protocol_version) }
     end
 
     # TODO: Add methods for handle_get (SSE setup, listener, heartbeat) - Partially Done

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

@@ -32,6 +32,7 @@ module ActionMCP
     # including the direction (client or server), message type (request, response, notification),
     # and any associated JSON-RPC ID.
     class Message < ApplicationRecord
+      include MCPMessageInspect
       belongs_to :session,
                  class_name: "ActionMCP::Session",
                  inverse_of: :messages,

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# == Schema Information
+#
+# Table name: action_mcp_sse_events
+#
+#  id         :bigint           not null, primary key
+#  data       :text             not null
+#  created_at :datetime         not null
+#  updated_at :datetime         not null
+#  event_id   :integer          not null
+#  session_id :string           not null
+#
+# Indexes
+#
+#  index_action_mcp_sse_events_on_created_at               (created_at)
+#  index_action_mcp_sse_events_on_session_id               (session_id)
+#  index_action_mcp_sse_events_on_session_id_and_event_id  (session_id,event_id) UNIQUE
+#
+# Foreign Keys
+#
+#  fk_rails_...  (session_id => action_mcp_sessions.id)
+#
+module ActionMCP
+  class Session
+    # Represents a Server-Sent Event (SSE) in an MCP session
+    # These events are stored for potential resumption when a client reconnects
+    class SSEEvent < ApplicationRecord
+      self.table_name = "action_mcp_sse_events"
+
+      belongs_to :session, class_name: "ActionMCP::Session"
+
+      # Validations
+      validates :event_id, presence: true, numericality: { only_integer: true, greater_than: 0 }
+      validates :data, presence: true
+
+      # Scopes
+      scope :recent, -> { order(event_id: :desc) }
+      scope :after_id, ->(id) { where("event_id > ?", id) }
+      scope :before, ->(time) { where("created_at < ?", time) }
+
+      # Serializes the data as JSON if it's not already a string
+      def data_for_stream
+        return data if data.is_a?(String)
+        data.is_a?(Hash) ? data.to_json : data.to_s
+      end
+
+      # Generates the SSE formatted event string
+      # @return [String] The formatted SSE event
+      def to_sse
+        "id: #{event_id}\ndata: #{data_for_stream}\n\n"
+      end
+    end
+  end
+end