vector_mcp 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c251e50dd9545c58cb748a420426193de3d8b2ccc5c110b340f79ff305ad769
-  data.tar.gz: d19ebc22fe53066a8113eea7e7219093fc0fe546a960aa392add005ae5bb1fa8
+  metadata.gz: edd8f7804cea74064b13b6432daa19149d4b2d6c34efbd7ccfbae393870b648a
+  data.tar.gz: bd04d07372ef947498c39021adfba055d8030b94bf76b567fc8b5cb73aae994b
 SHA512:
-  metadata.gz: c7e6d56309c8e30ef4cdc20d2db4c9a74750508ea6c035dfe2ac64ae3759174d4c6c8b20b8726037318b5f5a14dee59e1a81097160c8df6b43a1d302f7e05f33
-  data.tar.gz: f8a32dbeadb7d17459745edefd7ebbdf784e7d9dc646a3362fe3ddd2ae3ae8d3c20f9d2374e6905d31a0bfcddbc369d5cb1ef583c544cffadc37fb6ed38ae8d1
+  metadata.gz: 3a47a3ad028e39de9bd8d4973779040fd0c571067e4c3588ad406d26dd138cdfad06921d497a3922d1eb2406df3ede02379df7f24620539cb1170ac6fdb1bed5
+  data.tar.gz: ad1d3d147c3b4ef8624651aeabb0809f689bbfb5c4ae702dcc0c5fa458cc500ff7ffd54e46a4ea02ae995d908af0122f5a88b7ab895eeaab8c1d780e6eec8043

data/CHANGELOG.md

@@ -1,3 +1,71 @@
+## [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/errors.rb

@@ -28,7 +28,8 @@ 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}")
+      logger = VectorMCP.logger_for("errors")
+      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 +105,8 @@ 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}")
+      logger = VectorMCP.logger_for("errors")
+      logger.debug("Initializing ServerError with code: #{code}")
       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 +133,8 @@ 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")
+      logger = VectorMCP.logger_for("errors")
+      logger.debug("Initializing NotFoundError with code: -32001")
       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,8 @@ 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")
+        logger = VectorMCP.logger_for("handlers.core")
+        logger.debug("Handling ping request")
         {}
       end
 
@@ -54,27 +56,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)
+          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 +101,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 +179,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)
 
-        # Call the registered handler after arguments were validated
-        result_data = prompt.handler.call(arguments)
+          arguments = params["arguments"] || {}
+          validate_arguments!(prompt_name, prompt, arguments)
 
-        validate_prompt_response!(prompt_name, result_data, server)
+          # Call the registered handler after arguments were validated
+          result_data = prompt.handler.call(arguments)
 
-        # Return the handler response directly (must match GetPromptResult schema)
-        result_data
+          validate_prompt_response!(prompt_name, result_data, server)
+
+          # 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 ---
@@ -427,6 +453,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)
+        if [1, -1].include?(tool.handler.arity)
+          tool.handler.call(arguments)
+        else
+          tool.handler.call(arguments, security_result[:session_context])
+        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