actionmcp 0.80.1 → 0.82.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6251e9ce3e87878bf86bb3ca1bbfd3363fb4fedccd9567a0b9b6c42fbc87241a
-  data.tar.gz: ee8f4bdd5ad42c611f7f652f836e40ce0477510e9c0e856a0a32eaa447b77718
+  metadata.gz: b0ca96b3275c9dcece973bd75cc7eb4585fea06f6a99d8dec6a7603817c28b69
+  data.tar.gz: a188765f7176684ee0875a9eecf25cf07ff4c2338c93be7fc5fe29954f26bbb0
 SHA512:
-  metadata.gz: 80712d1d14d91fb087bf8bd35c4cedb61ea22015a958dc5c66df64dfa7872d0755ea08a4ecbe02c1b577bb14eff8bcd30aaaa78ffba61c4b6e16ea37c336c313
-  data.tar.gz: '0920ffdcb46a86910789282365a7ff6391ec4a1bf424be3dee7b8174497953df4aa73098e89a58559bb59d8157791d7620045339e763b3b27c885037b5e420fd'
+  metadata.gz: 678b6231e5c2df59dc9b90c26d5135cfb2ceb2aaa45ed55e774dc9700cf15f634d8a796fa2c9d3e2a78896bf21f41a86d303f2ca97db4445d289f8a24a8892b5
+  data.tar.gz: 2d1458519c3b69045a8f885be8da811544de78e793cc191ca2145d08ebc41a019a209b3f51fc9bcc9138e72b75f6b1fcc11428e01a06b1b6326f7bcc902d7dee

data/README.md

@@ -154,9 +154,9 @@ class CalculateSumTool < ApplicationMCPTool
     render(text: "Calculating #{a} + #{b}...")
     render(text: "The sum is #{sum}")
 
-    # You can render errors if needed
+    # You can report errors if needed
     if sum > 1000
-      render(error: ["Warning: Sum exceeds recommended limit"])
+      report_error("Warning: Sum exceeds recommended limit")
     end
 
     # Or even images
@@ -279,6 +279,65 @@ end
 
 Resource templates are automatically registered and used when LLMs request resources matching their patterns.
 
+## 📚 Documentation
+
+ActionMCP provides comprehensive documentation across multiple specialized guides. Each guide focuses on specific aspects to keep information organized and prevent context overload:
+
+### Getting Started & Setup
+- **[Installation & Configuration](README.md#installation)** - Initial setup, database migrations, and basic configuration
+- **[Authentication with Gateway](README.md#authentication-with-gateway)** - User authentication and authorization patterns
+
+### Component Development  
+- **[📋 TOOLS.MD](TOOLS.MD)** - Complete guide to developing MCP tools
+  - Generator usage and best practices
+  - Property definitions, validation, and consent management
+  - Output schemas for structured responses
+  - Error handling, testing, and security considerations
+  - Advanced features like additional properties and authentication context
+
+- **[📝 PROMPTS.MD](PROMPTS.MD)** - Prompt template development guide
+  - Creating reusable prompt templates
+  - Multi-step conversations and mixed content types
+  - Argument validation and prompt chaining
+
+- **[🔗 RESOURCE_TEMPLATES.md](RESOURCE_TEMPLATES.md)** - Resource template implementation
+  - URI template patterns and parameter extraction
+  - Dynamic resource resolution and collections
+  - Callbacks and validation patterns
+
+### Client & Integration
+- **[🔌 CLIENTUSAGE.MD](CLIENTUSAGE.MD)** - Complete client implementation guide
+  - Session management and resumability
+  - Transport configuration and connection handling
+  - Tool, prompt, and resource collections
+  - Production deployment patterns
+
+### Protocol & Technical Details
+- **[🚀 The Hitchhiker's Guide to MCP](The_Hitchhikers_Guide_to_MCP.md)** - Protocol versions and migration
+  - Comprehensive comparison of MCP protocol versions (2024-11-05, 2025-03-26, 2025-06-18)
+  - Design decisions and architectural rationale
+  - Migration paths and compatibility considerations
+  - Feature evolution and technical specifications (*Don't Panic!*)
+
+### Advanced Configuration
+- **[Session Storage](README.md#session-storage)** - Volatile vs ActiveRecord vs custom session stores
+- **[Thread Pool Management](README.md#thread-pool-management)** - Performance tuning and graceful shutdown
+- **[Profiles System](README.md#profiles)** - Multi-tenant capability filtering
+- **[Production Deployment](README.md#production-deployment-of-mcps0)** - Falcon, Unix sockets, and reverse proxy setup
+
+### Development & Testing
+- **[Generators](README.md#generators)** - Rails generators for scaffolding components
+- **[Testing with TestHelper](README.md#testing-with-testhelper)** - Comprehensive testing strategies
+- **[Development Commands](README.md#development-commands)** - Rake tasks for debugging and inspection
+- **[MCP Inspector Integration](README.md#inspecting-your-mcp-server)** - Interactive testing and validation
+
+### Troubleshooting & Production
+- **[Error Handling](README.md#error-handling-and-troubleshooting)** - JSON-RPC error codes and debugging
+- **[Production Considerations](README.md#production-considerations)** - Security, performance, and monitoring
+- **[Middleware Conflicts](README.md#dealing-with-middleware-conflicts)** - Using `mcp_vanilla.ru` for production
+
+> **💡 Pro Tip**: Start with the component-specific guides (TOOLS.MD, PROMPTS.MD, RESOURCE_TEMPLATES.md) for hands-on development, then reference the Hitchhiker's Guide for protocol details and CLIENTUSAGE.MD for integration patterns.
+
 ## Configuration
 
 ActionMCP is configured via `config.action_mcp` in your Rails application.
@@ -871,7 +930,7 @@ class MyTool < ApplicationMCPTool
   def perform
     # Check for error conditions and return clear messages
     if some_error_condition?
-      render(error: ["Clear error message for the LLM"])
+      report_error("Clear error message for the LLM")
       return
     end
     

data/lib/action_mcp/capability.rb

@@ -8,7 +8,6 @@ module ActionMCP
     include ActiveModel::Attributes
     include Callbacks
     include Instrumentation::Instrumentation
-    include Logging
     include Renderable
 
     class_attribute :_capability_name, instance_accessor: false

data/lib/action_mcp/client/base.rb

@@ -13,7 +13,6 @@ module ActionMCP
       include Resources
       include Roots
       include Elicitation
-      include Logging
 
       attr_reader :logger, :transport,
                   :connection_error, :server,

data/lib/action_mcp/client/transport.rb

@@ -71,7 +71,6 @@ module ActionMCP
     # Base class for transport implementations
     class TransportBase
       include Transport
-      include Logging
 
       attr_reader :url, :options, :session_store
 

data/lib/action_mcp/configuration.rb

@@ -51,9 +51,9 @@ module ActionMCP
                   :connects_to
 
     def initialize
-      @logging_enabled = true
+      @logging_enabled = false
       @list_changed = true
-      @logging_level = :info
+      @logging_level = :warning
       @resources_subscribe = false
       @elicitation_enabled = false
       @verbose_logging = false
@@ -269,8 +269,8 @@ module ActionMCP
           resources: [ "all" ],
           options: {
             list_changed: false,
-            logging_enabled: true,
-            logging_level: :info,
+            logging_enabled: false,
+            logging_level: :warning,
             resources_subscribe: false
           }
         },

data/lib/action_mcp/engine.rb

@@ -53,6 +53,11 @@ module ActionMCP
       ActionMCP.configuration.load_profiles
     end
 
+    # Initialize MCP logging system
+    initializer "action_mcp.initialize_logging" do
+      ActionMCP::Logging.initialize_from_config!
+    end
+
 
     # Configure autoloading for the mcp/tools directory and identifiers
     initializer "action_mcp.autoloading", before: :set_autoload_paths do |app|

data/lib/action_mcp/json_rpc_handler_base.rb

@@ -25,6 +25,9 @@ module ActionMCP
       TOOLS_LIST = "tools/list"
       TOOLS_CALL = "tools/call"
 
+      # Logging methods
+      LOGGING_SET_LEVEL = "logging/setLevel"
+
       # Notification methods
       NOTIFICATIONS_INITIALIZED = "notifications/initialized"
       NOTIFICATIONS_CANCELLED = "notifications/cancelled"

data/lib/action_mcp/logging/level.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module Logging
+    # RFC 5424 log levels for MCP logging
+    # @see https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1
+    class Level
+      # Log levels in order of severity (ascending)
+      LEVELS = {
+        debug: 0,
+        info: 1,
+        notice: 2,
+        warning: 3,
+        error: 4,
+        critical: 5,
+        alert: 6,
+        emergency: 7
+      }.freeze
+
+      # Reverse mapping for converting integers back to symbols
+      LEVEL_NAMES = LEVELS.invert.freeze
+
+      class << self
+        # Check if a level is valid
+        # @param level [String, Symbol, Integer] The level to check
+        # @return [Boolean] true if valid, false otherwise
+        def valid?(level)
+          case level
+          when String, Symbol
+            LEVELS.key?(level.to_sym)
+          when Integer
+            LEVEL_NAMES.key?(level)
+          else
+            false
+          end
+        end
+
+        # Coerce a level to its integer value
+        # @param level [String, Symbol, Integer] The level to coerce
+        # @return [Integer] The integer severity value
+        # @raise [ArgumentError] if level is invalid
+        def coerce(level)
+          case level
+          when String, Symbol
+            symbol_level = level.to_sym
+            LEVELS.fetch(symbol_level) do
+              raise ArgumentError, "Invalid log level: #{level}. Valid levels: #{LEVELS.keys.join(', ')}"
+            end
+          when Integer
+            unless LEVEL_NAMES.key?(level)
+              raise ArgumentError, "Invalid log level: #{level}. Valid levels: 0-7"
+            end
+            level
+          else
+            raise ArgumentError, "Invalid log level type: #{level.class}. Expected String, Symbol, or Integer"
+          end
+        end
+
+        # Convert integer level back to symbol
+        # @param level_int [Integer] The integer level
+        # @return [Symbol] The symbol name
+        def name_for(level_int)
+          LEVEL_NAMES.fetch(level_int) do
+            raise ArgumentError, "Invalid log level integer: #{level_int}"
+          end
+        end
+
+        # Get all valid level names as symbols
+        # @return [Array<Symbol>] Array of level symbols
+        def all_levels
+          LEVELS.keys
+        end
+
+        # Check if level_a is more severe than level_b
+        # @param level_a [String, Symbol, Integer] First level
+        # @param level_b [String, Symbol, Integer] Second level
+        # @return [Boolean] true if level_a >= level_b in severity
+        def more_severe_or_equal?(level_a, level_b)
+          coerce(level_a) >= coerce(level_b)
+        end
+      end
+    end
+  end
+end

data/lib/action_mcp/logging/logger.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module Logging
+    # MCP Logger that sends notifications/message to the MCP client
+    class Logger
+      attr_reader :name, :session, :state
+
+      # Initialize a new MCP logger
+      # @param name [String, nil] Optional logger name
+      # @param session [ActionMCP::Session] The MCP session for transport
+      # @param state [ActionMCP::Logging::State] The global logging state
+      def initialize(name: nil, session:, state:)
+        @name = name
+        @session = session
+        @state = state
+      end
+
+      # Log a debug message
+      # @param message [String, nil] The message (if no block given)
+      # @param data [Object] Additional structured data
+      # @yield Block that returns the message (evaluated only if logging)
+      # @return [void]
+      def debug(message = nil, data: nil, &block)
+        log(:debug, message, data: data, &block)
+      end
+
+      # Log an info message
+      # @param message [String, nil] The message (if no block given)
+      # @param data [Object] Additional structured data
+      # @yield Block that returns the message (evaluated only if logging)
+      # @return [void]
+      def info(message = nil, data: nil, &block)
+        log(:info, message, data: data, &block)
+      end
+
+      # Log a notice message
+      # @param message [String, nil] The message (if no block given)
+      # @param data [Object] Additional structured data
+      # @yield Block that returns the message (evaluated only if logging)
+      # @return [void]
+      def notice(message = nil, data: nil, &block)
+        log(:notice, message, data: data, &block)
+      end
+
+      # Log a warning message
+      # @param message [String, nil] The message (if no block given)
+      # @param data [Object] Additional structured data
+      # @yield Block that returns the message (evaluated only if logging)
+      # @return [void]
+      def warning(message = nil, data: nil, &block)
+        log(:warning, message, data: data, &block)
+      end
+      alias_method :warn, :warning
+
+      # Log an error message
+      # @param message [String, nil] The message (if no block given)
+      # @param data [Object] Additional structured data
+      # @yield Block that returns the message (evaluated only if logging)
+      # @return [void]
+      def error(message = nil, data: nil, &block)
+        log(:error, message, data: data, &block)
+      end
+
+      # Log a critical message
+      # @param message [String, nil] The message (if no block given)
+      # @param data [Object] Additional structured data
+      # @yield Block that returns the message (evaluated only if logging)
+      # @return [void]
+      def critical(message = nil, data: nil, &block)
+        log(:critical, message, data: data, &block)
+      end
+
+      # Log an alert message
+      # @param message [String, nil] The message (if no block given)
+      # @param data [Object] Additional structured data
+      # @yield Block that returns the message (evaluated only if logging)
+      # @return [void]
+      def alert(message = nil, data: nil, &block)
+        log(:alert, message, data: data, &block)
+      end
+
+      # Log an emergency message
+      # @param message [String, nil] The message (if no block given)
+      # @param data [Object] Additional structured data
+      # @yield Block that returns the message (evaluated only if logging)
+      # @return [void]
+      def emergency(message = nil, data: nil, &block)
+        log(:emergency, message, data: data, &block)
+      end
+
+      # Check if debug level is enabled
+      # @return [Boolean] true if debug messages will be logged
+      def debug?
+        state.should_log?(:debug)
+      end
+
+      # Check if info level is enabled
+      # @return [Boolean] true if info messages will be logged
+      def info?
+        state.should_log?(:info)
+      end
+
+      # Check if notice level is enabled
+      # @return [Boolean] true if notice messages will be logged
+      def notice?
+        state.should_log?(:notice)
+      end
+
+      # Check if warning level is enabled
+      # @return [Boolean] true if warning messages will be logged
+      def warning?
+        state.should_log?(:warning)
+      end
+      alias_method :warn?, :warning?
+
+      # Check if error level is enabled
+      # @return [Boolean] true if error messages will be logged
+      def error?
+        state.should_log?(:error)
+      end
+
+      # Check if critical level is enabled
+      # @return [Boolean] true if critical messages will be logged
+      def critical?
+        state.should_log?(:critical)
+      end
+
+      # Check if alert level is enabled
+      # @return [Boolean] true if alert messages will be logged
+      def alert?
+        state.should_log?(:alert)
+      end
+
+      # Check if emergency level is enabled
+      # @return [Boolean] true if emergency messages will be logged
+      def emergency?
+        state.should_log?(:emergency)
+      end
+
+      private
+
+      # Core logging method
+      # @param level [Symbol] The log level
+      # @param message [String, nil] The message
+      # @param data [Object] Additional data
+      # @yield Block that returns message
+      # @return [void]
+      def log(level, message = nil, data: nil, &block)
+        return unless state.should_log?(level)
+
+        # Evaluate message from block if provided
+        final_message = if block_given?
+                          yield
+        else
+                          message
+        end
+
+        # Send MCP notification
+        send_mcp_notification(level, final_message, data)
+      end
+
+      # Send notifications/message to MCP client
+      # @param level [Symbol] The log level
+      # @param message [String] The message
+      # @param data [Object] Additional data
+      # @return [void]
+      def send_mcp_notification(level, message, data)
+        params = {
+          level: level.to_s,
+          data: build_log_data(message, data)
+        }
+
+        # Add logger name if present
+        params[:logger] = name if name
+
+        # Send via session's messaging service
+        session.messaging_service.send_notification("notifications/message", params)
+      rescue StandardError => e
+        # Fallback to Rails logger if MCP transport fails
+        Rails.logger.error "Failed to send MCP log notification: #{e.message}"
+      end
+
+      # Build the data payload for the log message
+      # @param message [String] The primary message
+      # @param additional_data [Object] Additional structured data
+      # @return [Object] The data to send in the notification
+      def build_log_data(message, additional_data)
+        case additional_data
+        when nil
+          message
+        when Hash
+          if message
+            { message: message }.merge(additional_data)
+          else
+            additional_data
+          end
+        else
+          if message
+            { message: message, data: additional_data }
+          else
+            additional_data
+          end
+        end
+      end
+    end
+  end
+end

data/lib/action_mcp/logging/mixin.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module Logging
+    # Mixin to provide easy MCP logging access for tools, prompts, and resources
+    module Mixin
+      extend ActiveSupport::Concern
+
+      # Get the MCP logger for this instance
+      # @return [ActionMCP::Logging::Logger, ActionMCP::Logging::NullLogger] logger instance
+      def mcp_logger
+        @mcp_logger ||= ActionMCP::Logging.logger_for_context(
+          name: logger_name,
+          execution_context: execution_context
+        )
+      end
+
+      # Log a debug message
+      # @param message [String, nil] The message (if no block given)
+      # @param data [Object] Additional structured data
+      # @yield Block that returns the message (evaluated only if logging)
+      # @return [void]
+      def mcp_debug(message = nil, data: nil, &block)
+        mcp_logger.debug(message, data: data, &block)
+      end
+
+      # Log an info message
+      # @param message [String, nil] The message (if no block given)
+      # @param data [Object] Additional structured data
+      # @yield Block that returns the message (evaluated only if logging)
+      # @return [void]
+      def mcp_info(message = nil, data: nil, &block)
+        mcp_logger.info(message, data: data, &block)
+      end
+
+      # Log a notice message
+      # @param message [String, nil] The message (if no block given)
+      # @param data [Object] Additional structured data
+      # @yield Block that returns the message (evaluated only if logging)
+      # @return [void]
+      def mcp_notice(message = nil, data: nil, &block)
+        mcp_logger.notice(message, data: data, &block)
+      end
+
+      # Log a warning message
+      # @param message [String, nil] The message (if no block given)
+      # @param data [Object] Additional structured data
+      # @yield Block that returns the message (evaluated only if logging)
+      # @return [void]
+      def mcp_warning(message = nil, data: nil, &block)
+        mcp_logger.warning(message, data: data, &block)
+      end
+      alias_method :mcp_warn, :mcp_warning
+
+      # Log an error message
+      # @param message [String, nil] The message (if no block given)
+      # @param data [Object] Additional structured data
+      # @yield Block that returns the message (evaluated only if logging)
+      # @return [void]
+      def mcp_error(message = nil, data: nil, &block)
+        mcp_logger.error(message, data: data, &block)
+      end
+
+      # Log a critical message
+      # @param message [String, nil] The message (if no block given)
+      # @param data [Object] Additional structured data
+      # @yield Block that returns the message (evaluated only if logging)
+      # @return [void]
+      def mcp_critical(message = nil, data: nil, &block)
+        mcp_logger.critical(message, data: data, &block)
+      end
+
+      # Log an alert message
+      # @param message [String, nil] The message (if no block given)
+      # @param data [Object] Additional structured data
+      # @yield Block that returns the message (evaluated only if logging)
+      # @return [void]
+      def mcp_alert(message = nil, data: nil, &block)
+        mcp_logger.alert(message, data: data, &block)
+      end
+
+      # Log an emergency message
+      # @param message [String, nil] The message (if no block given)
+      # @param data [Object] Additional structured data
+      # @yield Block that returns the message (evaluated only if logging)
+      # @return [void]
+      def mcp_emergency(message = nil, data: nil, &block)
+        mcp_logger.emergency(message, data: data, &block)
+      end
+
+      # Check if debug level is enabled
+      # @return [Boolean] true if debug messages will be logged
+      def mcp_debug?
+        mcp_logger.debug?
+      end
+
+      # Check if info level is enabled
+      # @return [Boolean] true if info messages will be logged
+      def mcp_info?
+        mcp_logger.info?
+      end
+
+      # Check if notice level is enabled
+      # @return [Boolean] true if notice messages will be logged
+      def mcp_notice?
+        mcp_logger.notice?
+      end
+
+      # Check if warning level is enabled
+      # @return [Boolean] true if warning messages will be logged
+      def mcp_warning?
+        mcp_logger.warning?
+      end
+      alias_method :mcp_warn?, :mcp_warning?
+
+      # Check if error level is enabled
+      # @return [Boolean] true if error messages will be logged
+      def mcp_error?
+        mcp_logger.error?
+      end
+
+      # Check if critical level is enabled
+      # @return [Boolean] true if critical messages will be logged
+      def mcp_critical?
+        mcp_logger.critical?
+      end
+
+      # Check if alert level is enabled
+      # @return [Boolean] true if alert messages will be logged
+      def mcp_alert?
+        mcp_logger.alert?
+      end
+
+      # Check if emergency level is enabled
+      # @return [Boolean] true if emergency messages will be logged
+      def mcp_emergency?
+        mcp_logger.emergency?
+      end
+
+      private
+
+      # Generate logger name from class name
+      # @return [String] the logger name
+      def logger_name
+        self.class.name&.underscore || "unknown"
+      end
+    end
+  end
+end