vector_mcp 0.3.4 → 0.5.0

data/lib/vector_mcp/rails/tool.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "active_support/core_ext/hash/indifferent_access"
+require "vector_mcp/tool"
+
+module VectorMCP
+  module Rails
+    # Rails-aware base class for declarative tool definitions.
+    #
+    # Adds ergonomics for the common patterns that show up in ActiveRecord-
+    # backed MCP tools:
+    #
+    # * +find!+ -- fetch a record or raise +VectorMCP::NotFoundError+
+    # * +respond_with+ -- standard success/error payload from a record
+    # * +with_transaction+ -- wrap a mutation in an AR transaction
+    # * Auto-rescue of +ActiveRecord::RecordNotFound+ (-> NotFoundError)
+    #   and +ActiveRecord::RecordInvalid+ (-> error payload)
+    # * Arguments delivered to +#call+ as a +HashWithIndifferentAccess+
+    #   so +args[:id]+ and +args["id"]+ both work
+    #
+    # @example
+    #   class UpdateProvider < VectorMCP::Rails::Tool
+    #     tool_name   "update_provider"
+    #     description "Update an existing provider"
+    #
+    #     param :id,   type: :integer, required: true
+    #     param :name, type: :string
+    #
+    #     def call(args, _session)
+    #       provider = find!(Provider, args[:id])
+    #       provider.update(args.except(:id))
+    #       respond_with(provider, name: provider.name)
+    #     end
+    #   end
+    class Tool < VectorMCP::Tool
+      # Overrides the parent handler to add indifferent-access args and
+      # auto-rescue ActiveRecord exceptions.
+      def self.build_handler
+        klass = self
+        params = @params
+        lambda do |args, session|
+          coerced = klass.coerce_args(args, params).with_indifferent_access
+          klass.new.call(coerced, session)
+        rescue ActiveRecord::RecordNotFound => e
+          raise VectorMCP::NotFoundError, e.message
+        rescue ActiveRecord::RecordInvalid => e
+          { success: false, errors: e.record.errors.full_messages }
+        end
+      end
+      private_class_method :build_handler
+
+      # Finds a record by id or raises VectorMCP::NotFoundError.
+      #
+      # @param model [Class] an ActiveRecord model class
+      # @param id [Integer, String] the record id
+      # @return [ActiveRecord::Base]
+      def find!(model, id)
+        model.find_by(id: id) ||
+          raise(VectorMCP::NotFoundError, "#{model.name} #{id} not found")
+      end
+
+      # Builds a standard response payload from a record.
+      #
+      # Success shape: +{ success: true, id: record.id, **extras }+
+      # Error shape:   +{ success: false, errors: record.errors.full_messages }+
+      #
+      # @param record [ActiveRecord::Base]
+      # @param extras [Hash] additional keys to merge into the success payload
+      # @return [Hash]
+      def respond_with(record, **extras)
+        if record.persisted? && record.errors.empty?
+          { success: true, id: record.id, **extras }
+        else
+          { success: false, errors: record.errors.full_messages }
+        end
+      end
+
+      # Runs the given block inside an ActiveRecord transaction.
+      def with_transaction(&)
+        ActiveRecord::Base.transaction(&)
+      end
+    end
+  end
+end

data/lib/vector_mcp/request_context.rb

@@ -92,7 +92,7 @@ module VectorMCP
     end
 
     # Create a minimal request context for non-HTTP transports.
-    # This is useful for stdio and other command-line transports.
+    # This is useful for non-HTTP transports or testing contexts.
     #
     # @param transport_type [String] The transport type identifier
     # @return [RequestContext] A minimal request context

data/lib/vector_mcp/security/auth_manager.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "auth_result"
+
 module VectorMCP
   module Security
     # Manages authentication strategies for VectorMCP servers
@@ -42,25 +44,22 @@ module VectorMCP
       # Authenticate a request using the specified or default strategy
       # @param request [Hash] the request object containing headers, params, etc.
       # @param strategy [Symbol] optional strategy override
-      # @return [Object, false] authentication result or false if failed
+      # @return [AuthResult] the authentication outcome
       def authenticate(request, strategy: nil)
-        return { authenticated: true, user: nil } unless @enabled
+        return AuthResult.passthrough unless @enabled
 
         strategy_name = strategy || @default_strategy
         auth_strategy = @strategies[strategy_name]
+        return AuthResult.failure unless auth_strategy
 
-        return { authenticated: false, error: "Unknown strategy: #{strategy_name}" } unless auth_strategy
-
-        begin
-          result = auth_strategy.authenticate(request)
-          if result
-            { authenticated: true, user: result }
-          else
-            { authenticated: false, error: "Authentication failed" }
-          end
-        rescue StandardError => e
-          { authenticated: false, error: "Authentication error: #{e.message}" }
+        result = auth_strategy.authenticate(request)
+        if result == false
+          AuthResult.failure
+        else
+          AuthResult.success(user: result, strategy: strategy_name.to_s)
         end
+      rescue StandardError
+        AuthResult.failure
       end
 
       # Check if authentication is required

data/lib/vector_mcp/security/auth_result.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module VectorMCP
+  module Security
+    # Value object representing the outcome of an authentication attempt.
+    # Replaces the unstructured Hash that previously flowed through the auth pipeline.
+    class AuthResult
+      attr_reader :user, :strategy, :authenticated_at
+
+      def initialize(authenticated:, user: nil, strategy: nil, authenticated_at: nil)
+        @authenticated = authenticated
+        @user = user
+        @strategy = strategy
+        @authenticated_at = authenticated_at || (Time.now if authenticated)
+        freeze
+      end
+
+      def authenticated? = @authenticated
+
+      def self.success(user:, strategy:, authenticated_at: Time.now)
+        new(authenticated: true, user: user, strategy: strategy, authenticated_at: authenticated_at)
+      end
+
+      def self.failure
+        new(authenticated: false)
+      end
+
+      def self.passthrough
+        new(authenticated: true)
+      end
+    end
+  end
+end

data/lib/vector_mcp/security/authorization.rb

@@ -10,6 +10,7 @@ module VectorMCP
       def initialize
         @policies = {}
         @enabled = false
+        @logger = VectorMCP.logger_for("authorization")
       end
 
       # Enable authorization system
@@ -45,17 +46,12 @@ module VectorMCP
 
         resource_type = determine_resource_type(resource)
         policy = @policies[resource_type]
-
-        # If no policy is defined, allow access (opt-in authorization)
         return true unless policy
 
-        begin
-          policy_result = policy.call(user, action, resource)
-          policy_result ? true : false
-        rescue StandardError
-          # Log error but deny access for safety
-          false
-        end
+        !!policy.call(user, action, resource)
+      rescue StandardError => e
+        @logger.error("Authorization policy error for #{resource_type}: #{e.message}")
+        false
       end
 
       # Check if authorization is required

data/lib/vector_mcp/security/middleware.rb

@@ -120,11 +120,11 @@ module VectorMCP
       # @param transport_request [Object] the transport request
       # @return [Hash] extracted request data
       def extract_request_data(transport_request)
-        # Handle Rack environment (for SSE transport)
+        # Handle Rack environment (for HTTP transports)
         if transport_request.respond_to?(:[]) && transport_request["REQUEST_METHOD"]
           extract_from_rack_env(transport_request)
         else
-          # Default fallback
+          # Default fallback for non-HTTP request formats
           { headers: {}, params: {} }
         end
       end

data/lib/vector_mcp/security/session_context.rb

@@ -113,34 +113,18 @@ module VectorMCP
         new(authenticated: false)
       end
 
-      # Create an authenticated session context from auth result
-      # @param auth_result [Hash] the authentication result
-      # @return [SessionContext] an authenticated session
+      # Create an authenticated session context from an AuthResult
+      # @param auth_result [VectorMCP::Security::AuthResult] the authentication outcome
+      # @return [SessionContext] an authenticated or anonymous session
       def self.from_auth_result(auth_result)
-        return anonymous unless auth_result&.dig(:authenticated)
-
-        user_data = auth_result[:user]
-
-        # Handle special marker for authenticated nil user
-        if user_data == :authenticated_nil_user
-          new(
-            user: nil,
-            authenticated: true,
-            auth_strategy: "custom",
-            authenticated_at: Time.now
-          )
-        else
-          # Extract strategy and authenticated_at only if user_data is a Hash
-          strategy = user_data.is_a?(Hash) ? user_data[:strategy] : nil
-          auth_time = user_data.is_a?(Hash) ? user_data[:authenticated_at] : nil
-
-          new(
-            user: user_data,
-            authenticated: true,
-            auth_strategy: strategy,
-            authenticated_at: auth_time
-          )
-        end
+        return anonymous unless auth_result&.authenticated?
+
+        new(
+          user: auth_result.user,
+          authenticated: true,
+          auth_strategy: auth_result.strategy,
+          authenticated_at: auth_result.authenticated_at
+        )
       end
     end
   end

data/lib/vector_mcp/security/strategies/api_key.rb

@@ -38,11 +38,7 @@ module VectorMCP
           return false unless api_key&.length&.positive?
 
           if secure_key_match?(api_key)
-            {
-              api_key: api_key,
-              strategy: "api_key",
-              authenticated_at: Time.now
-            }
+            { api_key: api_key }
           else
             false
           end

data/lib/vector_mcp/security/strategies/custom.rb

@@ -16,20 +16,20 @@ module VectorMCP
           @handler = handler
         end
 
-        # Authenticate a request using the custom handler
+        # Authenticate a request using the custom handler.
+        # If the handler returns a Hash with a :user key, the value is extracted
+        # so that AuthManager receives the user data directly.
         # @param request [Hash] the request object
-        # @return [Object, false] result from custom handler or false if authentication failed
+        # @return [Object, nil, false] user data or false if authentication failed.
+        #   A return of nil (from { user: nil }) signals "authenticated, no user object."
         def authenticate(request)
           result = @handler.call(request)
+          return false unless result && result != false
 
-          # Ensure result includes strategy info if it's successful
-          if result && result != false
-            format_successful_result(result)
-          else
-            false
-          end
-        rescue NoMemoryError, StandardError
-          # Log error but return false for security
+          return result unless result.is_a?(Hash) && result.key?(:user)
+
+          result[:user]
+        rescue StandardError, NoMemoryError
           false
         end
 
@@ -38,33 +38,6 @@ module VectorMCP
         def configured?
           !@handler.nil?
         end
-
-        private
-
-        # Format successful authentication result with strategy metadata
-        # @param result [Object] the result from the custom handler
-        # @return [Object] formatted result with strategy metadata
-        def format_successful_result(result)
-          case result
-          when Hash
-            # If result has a :user key, extract it and use as main user data
-            if result.key?(:user)
-              user_data = result[:user]
-              # For nil user, return a marker that will become nil in session context
-              return :authenticated_nil_user if user_data.nil?
-
-              user_data
-            else
-              result.merge(strategy: "custom", authenticated_at: Time.now)
-            end
-          else
-            {
-              user: result,
-              strategy: "custom",
-              authenticated_at: Time.now
-            }
-          end
-        end
       end
     end
   end

data/lib/vector_mcp/security/strategies/jwt_token.rb

@@ -43,16 +43,7 @@ module VectorMCP
 
           begin
             decoded = JWT.decode(token, @secret, true, @options)
-            payload = decoded[0] # First element is the payload
-            headers = decoded[1] # Second element is the headers
-
-            # Return user info from JWT payload
-            {
-              **payload,
-              strategy: "jwt",
-              authenticated_at: Time.now,
-              jwt_headers: headers
-            }
+            decoded[0]
           rescue JWT::ExpiredSignature, JWT::InvalidIssuerError, JWT::InvalidAudienceError,
                  JWT::VerificationError, JWT::DecodeError, StandardError
             false # Token validation failed

data/lib/vector_mcp/server/capabilities.rb

@@ -39,22 +39,7 @@ module VectorMCP
       # Notifies connected clients that the list of available prompts has changed.
       # @return [void]
       def notify_prompts_list_changed
-        return unless transport && @prompts_list_changed
-
-        notification_method = "notifications/prompts/list_changed"
-        begin
-          if transport.respond_to?(:broadcast_notification)
-            logger.debug("Broadcasting prompts list changed notification.")
-            transport.broadcast_notification(notification_method)
-          elsif transport.respond_to?(:send_notification)
-            logger.debug("Sending prompts list changed notification (transport may broadcast or send to first client).")
-            transport.send_notification(notification_method)
-          else
-            logger.warn("Transport does not support sending notifications/prompts/list_changed.")
-          end
-        rescue StandardError => e
-          logger.error("Failed to send prompts list changed notification: #{e.class.name}: #{e.message}")
-        end
+        send_list_changed_notification("prompts") if @prompts_list_changed
       end
 
       # Resets the `roots_list_changed` flag to false.
@@ -66,22 +51,7 @@ module VectorMCP
       # Notifies connected clients that the list of available roots has changed.
       # @return [void]
       def notify_roots_list_changed
-        return unless transport && @roots_list_changed
-
-        notification_method = "notifications/roots/list_changed"
-        begin
-          if transport.respond_to?(:broadcast_notification)
-            logger.debug("Broadcasting roots list changed notification.")
-            transport.broadcast_notification(notification_method)
-          elsif transport.respond_to?(:send_notification)
-            logger.debug("Sending roots list changed notification (transport may broadcast or send to first client).")
-            transport.send_notification(notification_method)
-          else
-            logger.warn("Transport does not support sending notifications/roots/list_changed.")
-          end
-        rescue StandardError => e
-          logger.error("Failed to send roots list changed notification: #{e.class.name}: #{e.message}")
-        end
+        send_list_changed_notification("roots") if @roots_list_changed
       end
 
       # Registers a session as a subscriber to prompt list changes.
@@ -93,6 +63,26 @@ module VectorMCP
 
       private
 
+      # Sends a `notifications/<kind>/list_changed` notification to the transport.
+      # No-op if no transport is attached. Logs a warning if the transport does not
+      # implement `send_notification` (intentional extension point for alternate
+      # transports).
+      # @api private
+      # @param kind [String] One of "prompts" or "roots".
+      def send_list_changed_notification(kind)
+        return unless transport
+
+        notification_method = "notifications/#{kind}/list_changed"
+        if transport.respond_to?(:send_notification)
+          logger.debug("Sending #{kind} list changed notification.")
+          transport.send_notification(notification_method)
+        else
+          logger.warn("Transport does not support sending #{notification_method}.")
+        end
+      rescue StandardError => e
+        logger.error("Failed to send #{kind} list changed notification: #{e.class.name}: #{e.message}")
+      end
+
       # Configures sampling capabilities based on provided configuration.
       # @api private
       def configure_sampling_capabilities(config)

data/lib/vector_mcp/server/message_handling.rb

@@ -20,17 +20,18 @@ module VectorMCP
         method = message["method"]
         params = message["params"] || {}
 
-        if id && method # Request
+        case classify_message(id, method)
+        when :request
           logger.debug("[#{session_id}] Request [#{id}]: #{method} with params: #{VectorMCP::LogFilter.filter_hash(params).inspect}")
           handle_request(id, method, params, session)
-        elsif method # Notification
+        when :notification
           logger.debug("[#{session_id}] Notification: #{method} with params: #{VectorMCP::LogFilter.filter_hash(params).inspect}")
           handle_notification(method, params, session)
-          nil # Notifications do not have a return value to send back to client
-        elsif id # Invalid: Has ID but no method
+          nil
+        when :invalid_missing_method
           logger.warn("[#{session_id}] Invalid message: Has ID [#{id}] but no method. #{message.inspect}")
           raise VectorMCP::InvalidRequestError.new("Request object must include a 'method' member.", request_id: id)
-        else # Invalid: No ID and no method
+        when :invalid_missing_both
           logger.warn("[#{session_id}] Invalid message: Missing both 'id' and 'method'. #{message.inspect}")
           raise VectorMCP::InvalidRequestError.new("Invalid message format", request_id: nil)
         end
@@ -60,6 +61,16 @@ module VectorMCP
 
       private
 
+      # Classify a JSON-RPC message based on presence of id and method fields.
+      # @api private
+      def classify_message(id, method)
+        return :request if id && method
+        return :notification if method
+        return :invalid_missing_method if id
+
+        :invalid_missing_both
+      end
+
       # Internal handler for JSON-RPC requests.
       # @api private
       def handle_request(id, method, params, session)
@@ -72,11 +83,11 @@ module VectorMCP
       end
 
       # Validates that the session is properly initialized for the given request.
+      # Transports are contractually required to pass a VectorMCP::Session here —
+      # never the SessionManager wrapper struct.
       # @api private
       def validate_session_initialization(id, method, _params, session)
-        # Handle both direct VectorMCP::Session and BaseSessionManager::Session wrapper
-        actual_session = session.respond_to?(:context) ? session.context : session
-        return if actual_session.initialized?
+        return if session.initialized?
 
         # Allow "initialize" even if not marked initialized yet by server
         return if method == "initialize"
@@ -115,9 +126,7 @@ module VectorMCP
       # Internal handler for JSON-RPC notifications.
       # @api private
       def handle_notification(method, params, session)
-        # Handle both direct VectorMCP::Session and BaseSessionManager::Session wrapper
-        actual_session = session.respond_to?(:context) ? session.context : session
-        unless actual_session.initialized? || method == "initialized"
+        unless session.initialized? || method == "initialized"
           logger.warn("Ignoring notification '#{method}' before session is initialized. Params: #{params.inspect}")
           return
         end
@@ -162,9 +171,7 @@ module VectorMCP
       # @api private
       def session_method(method_name)
         lambda do |params, session, _server|
-          # Handle both direct VectorMCP::Session and BaseSessionManager::Session wrapper
-          actual_session = session.respond_to?(:context) ? session.context : session
-          actual_session.public_send(method_name, params)
+          session.public_send(method_name, params)
         end
       end
     end