vector_mcp 0.3.1 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c251e50dd9545c58cb748a420426193de3d8b2ccc5c110b340f79ff305ad769
-  data.tar.gz: d19ebc22fe53066a8113eea7e7219093fc0fe546a960aa392add005ae5bb1fa8
+  metadata.gz: 64b4dac9a0a1e9c782d3b5d693e7582803621ac81555f992031f9edbdd3f5b6b
+  data.tar.gz: 571e540ac540859b1fefaadc5e2b3cda39a1415c3496af38cee46cb839316c85
 SHA512:
-  metadata.gz: c7e6d56309c8e30ef4cdc20d2db4c9a74750508ea6c035dfe2ac64ae3759174d4c6c8b20b8726037318b5f5a14dee59e1a81097160c8df6b43a1d302f7e05f33
-  data.tar.gz: f8a32dbeadb7d17459745edefd7ebbdf784e7d9dc646a3362fe3ddd2ae3ae8d3c20f9d2374e6905d31a0bfcddbc369d5cb1ef583c544cffadc37fb6ed38ae8d1
+  metadata.gz: cc7c13562e31070ce7aef3d0d20801e4a7368a44b22ea58d01ec872f7f9191e7b70d96e72c3cdcd42b9ecc40dc9b7ea30e63ce12b5b54987734a933402269b71
+  data.tar.gz: 6f989302cbd97c00aa5f2dfe28950cffb5c2c53c204c3ab10eb886a9dc680e0db6a704fef54229488910c837ebe3857c7e493ae5aa8729d8d6677fe048c223e1

data/CHANGELOG.md

@@ -1,3 +1,125 @@
+## [0.3.3] – 2025-07-29
+
+### Fixed
+
+* **Critical Security Fix - SSE Transport Session Isolation**: Fixed default behavior where SSE transport shared session state across all clients
+  - **BREAKING CHANGE**: SSE transport now defaults to secure session isolation mode
+  - Session manager is now enabled by default to prevent race conditions and data leakage
+  - Legacy shared session mode available via `disable_session_manager: true` option (deprecated with warning)
+  - Enhanced security tests to prevent regression of this critical vulnerability
+
+* **Critical Security Fix - Path Traversal Vulnerability**: Replaced naive path traversal validation with robust canonicalization
+  - **Path Validation Enhancement**: Now uses `File.expand_path` for proper path canonicalization
+  - **Attack Prevention**: Eliminates false positives from simple string-based `.` checks
+  - **Security Monitoring**: Added warnings for potential path traversal attempts
+  - **Bypass Protection**: Prevents sophisticated path traversal attacks through encoding or complex patterns
+
+* **Session Compatibility**: Fixed session object type detection across different transports
+  - **Transport Compatibility**: Added automatic detection between `BaseSessionManager::Session` and `VectorMCP::Session` types
+  - **Method Resolution**: Fixed `undefined method 'initialized?'` and `'initialize!'` errors
+  - **Transport Layer**: Enhanced stdio, SSE, and HTTP stream transports for consistent session handling
+
+* **Race Condition Fix**: Resolved concurrent session creation test failures in SSE transport
+  - **Thread Safety**: Implemented `Concurrent::Array` for thread-safe session tracking
+  - **Test Stability**: Enhanced test reliability for concurrent operations
+
+* **Code Quality**: Fixed RuboCop style and linting violations
+  - **Naming Conventions**: Updated method names to follow Ruby conventions (removed `get_` prefixes)
+  - **Style Compliance**: Fixed line length violations and predicate method naming
+  - **Consistency**: Applied consistent coding standards across the codebase
+
+### Security
+
+* **Defense in Depth**: Major security improvements addressing critical vulnerabilities
+  - **Multi-Client Security**: Eliminated shared state vulnerabilities in SSE transport
+  - **Path Security**: Comprehensive path traversal protection using canonical path resolution
+  - **Session Isolation**: Proper session boundary enforcement across all transport types
+
+* **Backward Compatibility**: Security fixes maintain API compatibility while improving defaults
+  - **Opt-in Legacy Mode**: Deprecated insecure modes available for gradual migration
+  - **Migration Path**: Clear deprecation warnings guide users to secure configurations
+
+### Testing
+
+* **Enhanced Security Test Coverage**: Comprehensive test suites for critical security fixes
+  - **Path Traversal Tests**: 20+ test cases covering legitimate paths, attack vectors, and edge cases
+  - **SSE Security Tests**: Verification of default secure behavior and session isolation
+  - **Integration Tests**: Cross-transport compatibility and session handling validation
+
+### Technical Details
+
+* **Session Architecture**: Improved session management layer for better transport compatibility
+* **Security Monitoring**: Enhanced logging and warning systems for security events
+* **Error Handling**: Better error messages and debugging information for session-related issues
+
+## [0.3.2] – 2025-07-02
+
+### Added
+
+* **Comprehensive Middleware System**: Pluggable hook system for custom behavior around all MCP operations
+  * **Hook Points**: Support for all major operations including tools, resources, prompts, sampling, transport, and authentication
+  * **Priority-Based Execution**: Control middleware execution order with configurable priorities
+  * **Conditional Execution**: Run middleware only for specific operations, users, or conditions
+  * **Context Management**: Rich execution context with operation metadata and session information
+  * **Error Handling**: Graceful error recovery with middleware-specific error hooks
+  * **Built-in Middleware**: PII redaction, request retry, rate limiting, and enhanced logging examples
+
+* **Enhanced Examples Organization**: Comprehensive example reorganization for better developer experience
+  * **Getting Started Examples**: `examples/getting_started/` with basic server implementations
+  * **Core Features Examples**: `examples/core_features/` demonstrating key capabilities
+  * **Use Cases Examples**: `examples/use_cases/` with real-world application scenarios
+  * **Logging Examples**: `examples/logging/` showcasing structured logging capabilities
+  * **Middleware Examples**: `examples/middleware_examples.rb` and `examples/simple_middleware_demo.rb`
+
+* **Refactored Logging System**: Enhanced logging architecture with better performance and flexibility
+  * **Simplified API**: Streamlined `VectorMCP.logger_for(component)` interface
+  * **Performance Improvements**: Optimized log formatting and output handling
+  * **Better Component Organization**: Hierarchical logger management with cleaner separation
+
+### Changed
+
+* **Middleware Integration**: Core server architecture enhanced to support middleware hooks
+  * **Server Methods**: New `use_middleware`, `middleware_stats`, `remove_middleware`, and `clear_middleware` methods
+  * **Handler Integration**: All core handlers now support middleware execution around operations
+  * **Session Context**: Enhanced session context with middleware metadata and execution tracking
+
+* **Example Structure**: Major reorganization of examples for better discoverability
+  * **Categorized Examples**: Logical grouping by functionality and use case
+  * **Enhanced Documentation**: Each example category includes detailed README files
+  * **Use Case Focus**: Real-world scenarios like data analysis, file operations, and web scraping
+
+* **Backward Compatibility**: All middleware features are opt-in with zero impact on existing servers
+  * **Default Behavior**: Servers without middleware continue working exactly as before
+  * **Optional Integration**: Middleware can be added incrementally to existing applications
+
+### Fixed
+
+* **Ruby Version Compatibility**: Enhanced support for older Ruby versions
+* **Code Quality**: Multiple bug fixes and improvements identified through expanded test coverage
+* **Performance**: Optimized middleware execution path for minimal overhead when no middleware is registered
+
+### Security
+
+* **Middleware Security**: Security-aware middleware execution
+  * **Session Context Integration**: Middleware has access to authentication and authorization context
+  * **Secure Error Handling**: Middleware errors handled securely without information leakage
+  * **Permission-Aware Hooks**: Middleware can respect user permissions and security policies
+
+### Testing
+
+* **Comprehensive Middleware Tests**: 50+ tests covering all middleware functionality
+  * **Hook Execution Tests**: Verification of all hook types and execution order
+  * **Priority and Condition Tests**: Complex scenario testing for middleware orchestration
+  * **Integration Tests**: End-to-end testing with real server operations
+  * **Performance Tests**: Overhead measurement and resource usage validation
+
+### Technical Details
+
+* **API Compatibility**: All middleware features maintain full backward compatibility
+* **Performance**: Minimal overhead when middleware is not used, efficient execution when enabled
+* **Memory Management**: Proper cleanup and resource management for long-running servers
+* **Thread Safety**: Concurrent middleware execution with proper synchronization
+
 ## [0.3.1] – 2025-06-25
 
 ### Added

data/lib/vector_mcp/definitions.rb

@@ -242,17 +242,33 @@ module VectorMCP
         # Currently, only file:// scheme is supported per MCP spec
         raise ArgumentError, "Only file:// URIs are supported for roots, got: #{parsed_uri.scheme}://" unless parsed_uri.scheme == "file"
 
-        # Validate path exists and is a directory
-        path = parsed_uri.path
-        raise ArgumentError, "Root directory does not exist: #{path}" unless File.exist?(path)
-
-        raise ArgumentError, "Root path is not a directory: #{path}" unless File.directory?(path)
+        # Validate and canonicalize path for security
+        raw_path = parsed_uri.path
+
+        # Canonicalize the path to resolve any relative components (., .., etc.)
+        # This prevents path traversal attacks and normalizes the path
+        begin
+          canonical_path = File.expand_path(raw_path)
+        rescue ArgumentError => e
+          raise ArgumentError, "Invalid path format: #{raw_path} (#{e.message})"
+        end
 
-        # Security check: ensure we can read the directory
+        # Security check: Verify the canonical path exists and is a directory
+        raise ArgumentError, "Root directory does not exist: #{canonical_path}" unless File.exist?(canonical_path)
+        raise ArgumentError, "Root path is not a directory: #{canonical_path}" unless File.directory?(canonical_path)
+        raise ArgumentError, "Root directory is not readable: #{canonical_path}" unless File.readable?(canonical_path)
+
+        # Additional security: Check if the canonical path differs significantly from raw path
+        # This can indicate potential path traversal attempts
+        if raw_path != canonical_path && raw_path.include?("..")
+          # Log the canonicalization for security monitoring
+          # Note: This is informational - the canonical path is what we'll actually use
+          warn "[SECURITY] Path canonicalized from '#{raw_path}' to '#{canonical_path}'. " \
+               "This may indicate a path traversal attempt."
+        end
 
-        raise ArgumentError, "Root directory is not readable: #{path}" unless File.readable?(path)
-        # Validate against path traversal attempts in the URI itself
-        raise ArgumentError, "Root path contains unsafe traversal patterns: #{path}" if path.include?("..") || path.include?("./")
+        # Update the URI to use the canonical path for consistency
+        self.uri = "file://#{canonical_path}"
 
         true
       end

data/lib/vector_mcp/errors.rb

@@ -28,7 +28,6 @@ module VectorMCP
     # @param details [Hash, nil] Additional details for the error (optional).
     # @param request_id [String, Integer, nil] The ID of the originating request.
     def initialize(message, code: -32_600, details: nil, request_id: nil)
-      VectorMCP.logger.debug("Initializing ProtocolError with code: #{code}")
       @code = code
       @message = message
       @details = details # NOTE: `data` in JSON-RPC is often used for this purpose.
@@ -104,7 +103,7 @@ module VectorMCP
     # @param details [Hash, nil] Additional details for the error (optional).
     # @param request_id [String, Integer, nil] The ID of the originating request.
     def initialize(message = "Server error", code: -32_000, details: nil, request_id: nil)
-      VectorMCP.logger.debug("Initializing ServerError with code: #{code}")
+      # ServerError initialization
       unless (-32_099..-32_000).cover?(code)
         warn "Server error code #{code} is outside of the reserved range (-32099 to -32000). Using -32000 instead."
         code = -32_000
@@ -131,7 +130,7 @@ module VectorMCP
     # @param details [Hash, nil] Additional details for the error (optional).
     # @param request_id [String, Integer, nil] The ID of the originating request.
     def initialize(message = "Not Found", details: nil, request_id: nil)
-      VectorMCP.logger.debug("Initializing NotFoundError with code: -32001")
+      # NotFoundError initialization
       super(message, code: -32_001, details: details, request_id: request_id)
     end
   end

data/lib/vector_mcp/handlers/core.rb

@@ -3,6 +3,7 @@
 require "json"
 require "uri"
 require "json-schema"
+require_relative "../middleware"
 
 module VectorMCP
   module Handlers
@@ -21,7 +22,6 @@ module VectorMCP
       # @param _server [VectorMCP::Server] The server instance (ignored).
       # @return [Hash] An empty hash, as per MCP spec for ping.
       def self.ping(_params, _session, _server)
-        VectorMCP.logger.debug("Handling ping request")
         {}
       end
 
@@ -54,27 +54,23 @@ module VectorMCP
         tool_name = params["name"]
         arguments = params["arguments"] || {}
 
-        tool = server.tools[tool_name]
-        raise VectorMCP::NotFoundError.new("Not Found", details: "Tool not found: #{tool_name}") unless tool
+        context = create_tool_context(tool_name, params, session, server)
+        context = server.middleware_manager.execute_hooks(:before_tool_call, context)
+        return handle_middleware_error(context) if context.error?
 
-        # Security check: authenticate and authorize the request
-        security_result = check_tool_security(session, tool, server)
-        handle_security_failure(security_result) unless security_result[:success]
+        begin
+          tool = find_tool!(tool_name, server)
+          security_result = validate_tool_security!(session, tool, server)
+          validate_input_arguments!(tool_name, tool, arguments)
 
-        # Validate arguments against the tool's input schema
-        validate_input_arguments!(tool_name, tool, arguments)
+          result = execute_tool_handler(tool, arguments, security_result, session)
+          context.result = build_tool_result(result)
 
-        # Let StandardError propagate to Server#handle_request
-        # Pass session_context only if the handler supports it (for backward compatibility)
-        result = if [1, -1].include?(tool.handler.arity)
-                   tool.handler.call(arguments)
-                 else
-                   tool.handler.call(arguments, security_result[:session_context])
-                 end
-        {
-          isError: false,
-          content: VectorMCP::Util.convert_to_mcp_content(result)
-        }
+          context = server.middleware_manager.execute_hooks(:after_tool_call, context)
+          context.result
+        rescue StandardError => e
+          handle_tool_error(e, context, server)
+        end
       end
 
       # Handles the `resources/list` request.
@@ -103,27 +99,24 @@ module VectorMCP
       # @raise [VectorMCP::ForbiddenError] if authorization fails.
       def self.read_resource(params, session, server)
         uri_s = params["uri"]
-        raise VectorMCP::NotFoundError.new("Not Found", details: "Resource not found: #{uri_s}") unless server.resources[uri_s]
 
-        resource = server.resources[uri_s]
+        context = create_resource_context(uri_s, params, session, server)
+        context = server.middleware_manager.execute_hooks(:before_resource_read, context)
+        return handle_middleware_error(context) if context.error?
 
-        # Security check: authenticate and authorize the request
-        security_result = check_resource_security(session, resource, server)
-        handle_security_failure(security_result) unless security_result[:success]
+        begin
+          resource = find_resource!(uri_s, server)
+          security_result = validate_resource_security!(session, resource, server)
 
-        # Let StandardError propagate to Server#handle_request
-        # Pass session_context only if the handler supports it (for backward compatibility)
-        content_raw = if [1, -1].include?(resource.handler.arity)
-                        resource.handler.call(params)
-                      else
-                        resource.handler.call(params, security_result[:session_context])
-                      end
-        contents = VectorMCP::Util.convert_to_mcp_content(content_raw, mime_type: resource.mime_type)
-        contents.each do |item|
-          # Add URI to each content item if not already present
-          item[:uri] ||= uri_s
+          content_raw = execute_resource_handler(resource, params, security_result)
+          contents = process_resource_content(content_raw, resource, uri_s)
+
+          context.result = { contents: contents }
+          context = server.middleware_manager.execute_hooks(:after_resource_read, context)
+          context.result
+        rescue StandardError => e
+          handle_resource_error(e, context, server)
         end
-        { contents: contents }
       end
 
       # Handles the `prompts/list` request.
@@ -184,20 +177,51 @@ module VectorMCP
       # @raise [VectorMCP::NotFoundError] if the prompt name is not found.
       # @raise [VectorMCP::InvalidParamsError] if arguments are invalid.
       # @raise [VectorMCP::InternalError] if the prompt handler returns an invalid data structure.
-      def self.get_prompt(params, _session, server)
+      def self.get_prompt(params, session, server)
         prompt_name = params["name"]
-        prompt      = fetch_prompt(prompt_name, server)
 
-        arguments = params["arguments"] || {}
-        validate_arguments!(prompt_name, prompt, arguments)
+        # Create middleware context
+        context = VectorMCP::Middleware::Context.new(
+          operation_type: :prompt_get,
+          operation_name: prompt_name,
+          params: params,
+          session: session,
+          server: server,
+          metadata: { start_time: Time.now }
+        )
+
+        # Execute before_prompt_get hooks
+        context = server.middleware_manager.execute_hooks(:before_prompt_get, context)
+        return handle_middleware_error(context) if context.error?
+
+        begin
+          prompt = fetch_prompt(prompt_name, server)
+
+          arguments = params["arguments"] || {}
+          validate_arguments!(prompt_name, prompt, arguments)
 
-        # Call the registered handler after arguments were validated
-        result_data = prompt.handler.call(arguments)
+          # Call the registered handler after arguments were validated
+          result_data = prompt.handler.call(arguments)
 
-        validate_prompt_response!(prompt_name, result_data, server)
+          validate_prompt_response!(prompt_name, result_data, server)
 
-        # Return the handler response directly (must match GetPromptResult schema)
-        result_data
+          # Set result in context
+          context.result = result_data
+
+          # Execute after_prompt_get hooks
+          context = server.middleware_manager.execute_hooks(:after_prompt_get, context)
+
+          context.result
+        rescue StandardError => e
+          # Set error in context and execute error hooks
+          context.error = e
+          context = server.middleware_manager.execute_hooks(:on_prompt_error, context)
+
+          # Re-raise unless middleware handled the error
+          raise e unless context.result
+
+          context.result
+        end
       end
 
       # --- Notification Handlers ---
@@ -400,12 +424,16 @@ module VectorMCP
       # @param session [VectorMCP::Session] The current session
       # @return [Hash] Request context for security middleware
       def self.extract_request_from_session(session)
-        # Extract security context from session
-        # This will be enhanced as we integrate with transport layers
+        # All sessions should have a request_context - this is enforced by Session initialization
+        unless session.respond_to?(:request_context) && session.request_context
+          raise VectorMCP::InternalError,
+                "Session missing request_context - transport layer integration error. Session ID: #{session.id}"
+        end
+
         {
-          headers: session.instance_variable_get(:@request_headers) || {},
-          params: session.instance_variable_get(:@request_params) || {},
-          session_id: session.respond_to?(:id) ? session.id : "test-session"
+          headers: session.request_context.headers,
+          params: session.request_context.params,
+          session_id: session.id
         }
       end
       private_class_method :extract_request_from_session
@@ -427,6 +455,134 @@ module VectorMCP
         end
       end
       private_class_method :handle_security_failure
+
+      # Handle middleware error by returning appropriate response or raising error
+      # @api private
+      # @param context [VectorMCP::Middleware::Context] The middleware context with error
+      # @return [Hash, nil] Response hash if middleware provided one
+      # @raise [StandardError] Re-raises the original error if not handled
+      def self.handle_middleware_error(context)
+        # If middleware provided a result, return it
+        return context.result if context.result
+
+        # Otherwise, re-raise the middleware error
+        raise context.error
+      end
+
+      # Tool helper methods
+
+      # Create middleware context for tool operations
+      def self.create_tool_context(tool_name, params, session, server)
+        VectorMCP::Middleware::Context.new(
+          operation_type: :tool_call,
+          operation_name: tool_name,
+          params: params,
+          session: session,
+          server: server,
+          metadata: { start_time: Time.now }
+        )
+      end
+
+      # Find and validate tool exists
+      def self.find_tool!(tool_name, server)
+        tool = server.tools[tool_name]
+        raise VectorMCP::NotFoundError.new("Not Found", details: "Tool not found: #{tool_name}") unless tool
+
+        tool
+      end
+
+      # Validate tool security
+      def self.validate_tool_security!(session, tool, server)
+        security_result = check_tool_security(session, tool, server)
+        handle_security_failure(security_result) unless security_result[:success]
+        security_result
+      end
+
+      # Execute tool handler with proper arity handling
+      def self.execute_tool_handler(tool, arguments, _security_result, session)
+        if [1, -1].include?(tool.handler.arity)
+          tool.handler.call(arguments)
+        else
+          tool.handler.call(arguments, session)
+        end
+      end
+
+      # Build tool result response
+      def self.build_tool_result(result)
+        {
+          isError: false,
+          content: VectorMCP::Util.convert_to_mcp_content(result)
+        }
+      end
+
+      # Handle tool execution errors
+      def self.handle_tool_error(error, context, server)
+        context.error = error
+        context = server.middleware_manager.execute_hooks(:on_tool_error, context)
+        raise error unless context.result
+
+        context.result
+      end
+
+      # Resource helper methods
+
+      # Create middleware context for resource operations
+      def self.create_resource_context(uri_s, params, session, server)
+        VectorMCP::Middleware::Context.new(
+          operation_type: :resource_read,
+          operation_name: uri_s,
+          params: params,
+          session: session,
+          server: server,
+          metadata: { start_time: Time.now }
+        )
+      end
+
+      # Find and validate resource exists
+      def self.find_resource!(uri_s, server)
+        raise VectorMCP::NotFoundError.new("Not Found", details: "Resource not found: #{uri_s}") unless server.resources[uri_s]
+
+        server.resources[uri_s]
+      end
+
+      # Validate resource security
+      def self.validate_resource_security!(session, resource, server)
+        security_result = check_resource_security(session, resource, server)
+        handle_security_failure(security_result) unless security_result[:success]
+        security_result
+      end
+
+      # Execute resource handler with proper arity handling
+      def self.execute_resource_handler(resource, params, security_result)
+        if [1, -1].include?(resource.handler.arity)
+          resource.handler.call(params)
+        else
+          resource.handler.call(params, security_result[:session_context])
+        end
+      end
+
+      # Process resource content and add URI
+      def self.process_resource_content(content_raw, resource, uri_s)
+        contents = VectorMCP::Util.convert_to_mcp_content(content_raw, mime_type: resource.mime_type)
+        contents.each do |item|
+          item[:uri] ||= uri_s
+        end
+        contents
+      end
+
+      # Handle resource execution errors
+      def self.handle_resource_error(error, context, server)
+        context.error = error
+        context = server.middleware_manager.execute_hooks(:on_resource_error, context)
+        raise error unless context.result
+
+        context.result
+      end
+
+      private_class_method :handle_middleware_error, :create_tool_context, :find_tool!, :validate_tool_security!,
+                           :execute_tool_handler, :build_tool_result, :handle_tool_error, :create_resource_context,
+                           :find_resource!, :validate_resource_security!, :execute_resource_handler,
+                           :process_resource_content, :handle_resource_error
     end
   end
 end

data/lib/vector_mcp/logger.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "logger"
+require "json"
+
+module VectorMCP
+  # Simple, environment-driven logger for VectorMCP
+  # Supports JSON and text formats with component-based identification
+  class Logger
+    LEVELS = {
+      "TRACE" => ::Logger::DEBUG,
+      "DEBUG" => ::Logger::DEBUG,
+      "INFO" => ::Logger::INFO,
+      "WARN" => ::Logger::WARN,
+      "ERROR" => ::Logger::ERROR,
+      "FATAL" => ::Logger::FATAL
+    }.freeze
+
+    attr_reader :component, :ruby_logger
+
+    def initialize(component = "vectormcp")
+      @component = component.to_s
+      @ruby_logger = create_ruby_logger
+      @format = ENV.fetch("VECTORMCP_LOG_FORMAT", "text").downcase
+    end
+
+    def self.for(component)
+      new(component)
+    end
+
+    # Log methods with context support and block evaluation
+    def debug(message = nil, **context, &block)
+      log(:debug, message || block&.call, context)
+    end
+
+    def info(message = nil, **context, &block)
+      log(:info, message || block&.call, context)
+    end
+
+    def warn(message = nil, **context, &block)
+      log(:warn, message || block&.call, context)
+    end
+
+    def error(message = nil, **context, &block)
+      log(:error, message || block&.call, context)
+    end
+
+    def fatal(message = nil, **context, &block)
+      log(:fatal, message || block&.call, context)
+    end
+
+    # Security-specific logging
+    def security(message, **context)
+      log(:error, "[SECURITY] #{message}", context.merge(security_event: true))
+    end
+
+    # Performance measurement
+    def measure(description, **context)
+      start_time = Time.now
+      result = yield
+      duration = Time.now - start_time
+
+      info("#{description} completed", **context, duration_ms: (duration * 1000).round(2),
+                                                  success: true)
+
+      result
+    rescue StandardError => e
+      duration = Time.now - start_time
+      error("#{description} failed", **context, duration_ms: (duration * 1000).round(2),
+                                                success: false,
+                                                error: e.class.name,
+                                                error_message: e.message)
+      raise
+    end
+
+    private
+
+    def log(level, message, context)
+      return unless @ruby_logger.send("#{level}?")
+
+      if @format == "json"
+        log_json(level, message, context)
+      else
+        log_text(level, message, context)
+      end
+    end
+
+    def log_json(level, message, context)
+      entry = {
+        timestamp: Time.now.iso8601(3),
+        level: level.to_s.upcase,
+        component: @component,
+        message: message,
+        thread_id: Thread.current.object_id
+      }
+      entry.merge!(context) unless context.empty?
+
+      @ruby_logger.send(level, entry.to_json)
+    end
+
+    def log_text(level, message, context)
+      formatted_message = if context.empty?
+                            "[#{@component}] #{message}"
+                          else
+                            context_str = context.map { |k, v| "#{k}=#{v}" }.join(" ")
+                            "[#{@component}] #{message} (#{context_str})"
+                          end
+
+      @ruby_logger.send(level, formatted_message)
+    end
+
+    def create_ruby_logger
+      output = determine_output
+      logger = ::Logger.new(output)
+      logger.level = determine_level
+      logger.formatter = method(:format_log_entry)
+      logger
+    end
+
+    def determine_output
+      case ENV.fetch("VECTORMCP_LOG_OUTPUT", "stderr").downcase
+      when "stdout"
+        $stdout
+      when "file"
+        file_path = ENV.fetch("VECTORMCP_LOG_FILE", "./vectormcp.log")
+        File.open(file_path, "a")
+      else
+        $stderr
+      end
+    end
+
+    def determine_level
+      level_name = ENV.fetch("VECTORMCP_LOG_LEVEL", "INFO").upcase
+      LEVELS.fetch(level_name, ::Logger::INFO)
+    end
+
+    def format_log_entry(severity, datetime, _progname, msg)
+      if @format == "json"
+        # JSON messages are already formatted
+        "#{msg}\n"
+      else
+        # Text format with timestamp
+        timestamp = datetime.strftime("%Y-%m-%d %H:%M:%S.%3N")
+        "#{timestamp} [#{severity}] #{msg}\n"
+      end
+    end
+  end
+end