legion-mcp 0.7.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ee9fe829857bd0a2546ea95daf827d33fe60084094e665a78f7fe78742064978
-  data.tar.gz: cc57fd55347d9a541b382d7ca8a92d4a2d9094e674142e4336cfaadf46f4071c
+  metadata.gz: 30a63f2232747773e34419533d0b0ef00b6c10c396885a976b322702281f5062
+  data.tar.gz: f7191a38ce628ffc0c61a46010ce8c7f6ac4188c213c5462de449c9a118fe0c1
 SHA512:
-  metadata.gz: 15839e1d0bda42420e4734eef4a550a8b8b163453ec68a5eaf75aeb33b1d931625a5da8b30449db7627d2965ad7306d2a2c00633f559895ee442da35e5d5cee4
-  data.tar.gz: 77b1a31f1c5a24bc4c36b537500dfe849f9ff413a14de994032551d3161e52dee33729bd292ebb1a69fbe2625eeda682c985aa0c3937ed9d97ea30da7d0049d9
+  metadata.gz: 1bf54172fb099fb382a8d4921990b47ad005d545163656de251c2e025bc28dbcebc789752009298dc8cab87a539651b0ec56a440e1209d27cb619c66ea95e8dd
+  data.tar.gz: 246f2c244d3e4429017e5ccdf339d2b0a00033a8d49df8f652ab8ca52c7ed9b0e1f1d6eb1cf765971d7ab3cebd7f410ebb8733e42f840bad931b2e4397c55933

data/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## [Unreleased]
 
+## [0.7.1] - 2026-04-02
+
+### Added
+- `LoggingSupport` helper for structured MCP event logging with request, parameter, and result summarization
+
+### Changed
+- Uplifted non-Sinatra `lib/**/*.rb` logging paths to use `Legion::Logging::Helper` instead of direct `Legion::Logging.*` calls
+- Added `handle_exception` coverage across MCP tool, resource, router, client, observer, and pattern-store rescue paths
+- Added `info`-level tracing for MCP tool/resource entrypoints and key client, routing, and pattern lifecycle actions
+- Removed the custom fallback logger from `Actor::SelfGenerateCycle` in favor of the shared logging helper
+- Added explicit `require 'legion/logging'` at the main MCP entrypoint
+- Raised the minimum `legion-logging` dependency to `>= 1.4.3` for helper support
+
 ## [0.7.0] - 2026-03-31
 
 ### Added

data/legion-mcp.gemspec

@@ -29,7 +29,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'concurrent-ruby', '>= 1.2'
   spec.add_dependency 'legion-data', '>= 1.4.19'
   spec.add_dependency 'legion-json', '>= 1.2.0'
-  spec.add_dependency 'legion-logging', '>= 1.2.8'
+  spec.add_dependency 'legion-logging', '>= 1.4.3'
   spec.add_dependency 'legion-settings', '>= 1.3.12'
   spec.add_dependency 'mcp', '~> 0.8'
 end

data/lib/legion/mcp/actors/self_generate_cycle.rb

@@ -6,6 +6,8 @@ module Legion
   module MCP
     module Actor
       class SelfGenerateCycle < Legion::Extensions::Actors::Every
+        include Legion::Logging::Helper
+
         def runner_class    = self.class
         def runner_function = 'action'
         def check_subtask?  = false
@@ -18,6 +20,7 @@ module Legion
             300
           end
         rescue StandardError => e
+          handle_exception(e, level: :warn, operation: 'legion.mcp.actors.self_generate_cycle.time')
           log.warn(e.message)
           300
         end
@@ -25,6 +28,7 @@ module Legion
         def enabled?
           SelfGenerate.enabled?
         rescue StandardError => e
+          handle_exception(e, level: :warn, operation: 'legion.mcp.actors.self_generate_cycle.enabled?')
           log.warn(e.message)
           false
         end
@@ -32,16 +36,6 @@ module Legion
         def action(_payload = nil)
           SelfGenerate.run_cycle
         end
-
-        private
-
-        def log
-          return Legion::Logging if defined?(Legion::Logging)
-
-          @log ||= Object.new.tap do |nl|
-            %i[debug info warn error fatal].each { |m| nl.define_singleton_method(m) { |*| nil } }
-          end
-        end
       end
     end
   end

data/lib/legion/mcp/auth.rb

@@ -3,9 +3,12 @@
 module Legion
   module MCP
     module Auth
+      extend Legion::Logging::Helper
+
       module_function
 
       def authenticate(token)
+        log.info('Starting legion.mcp.auth.authenticate')
         return { authenticated: false, error: 'missing_token' } unless token
 
         if jwt_token?(token)
@@ -34,7 +37,8 @@ module Legion
         { authenticated: true, identity: { user_id: claims[:sub], risk_tier: claims[:risk_tier]&.to_sym,
                                             tenant_id: claims[:tenant_id], worker_id: claims[:worker_id] } }
       rescue StandardError => e
-        Legion::Logging.warn("Auth#verify_jwt failed: #{e.message}") if defined?(Legion::Logging)
+        handle_exception(e, level: :warn, operation: 'legion.mcp.auth.verify_jwt')
+        log.warn("Auth#verify_jwt failed: #{e.message}")
         { authenticated: false, error: e.message }
       end
 

data/lib/legion/mcp/catalog_bridge.rb

@@ -3,6 +3,8 @@
 module Legion
   module MCP
     module CatalogBridge
+      include Legion::Logging::Helper
+
       def hydrate_override_confidence
         return unless defined?(Legion::LLM::OverrideConfidence)
         return unless Legion::LLM::OverrideConfidence.respond_to?(:hydrate_from_l2)
@@ -19,6 +21,7 @@ module Legion
       end
 
       def dispatch_catalog_tool(tool_name, arguments)
+        log.info('Starting legion.mcp.catalog_bridge.dispatch_catalog_tool')
         return nil unless defined?(Legion::Extensions::Catalog::Registry)
 
         cap = Legion::Extensions::Catalog::Registry.find_by_mcp_name(tool_name)
@@ -31,13 +34,16 @@ module Legion
         result = runner.send(fn, **(arguments || {}).transform_keys(&:to_sym))
         { status: :success, result: result, source: :catalog }
       rescue NameError => e
-        Legion::Logging.warn("Catalog dispatch failed: #{e.message}") if defined?(Legion::Logging)
+        handle_exception(e, level: :warn, operation: 'legion.mcp.catalog_bridge.dispatch_catalog_tool')
+        log.warn("Catalog dispatch failed: #{e.message}")
         nil
       rescue StandardError => e
+        handle_exception(e, level: :error, operation: 'legion.mcp.catalog_bridge.dispatch_catalog_tool')
         { status: :error, error: e.message, source: :catalog }
       end
 
       def register_catalog_tools
+        log.info('Starting legion.mcp.catalog_bridge.register_catalog_tools')
         CatalogDispatcher.generate_tools_from_catalog.each { |tc| Server.register_tool(tc) }
       end
 

data/lib/legion/mcp/catalog_dispatcher.rb

@@ -1,14 +1,33 @@
 # frozen_string_literal: true
 
+require_relative 'logging_support'
+
 module Legion
   module MCP
     module CatalogDispatcher
+      extend Legion::Logging::Helper
+
       module_function
 
-      def dispatch(runner_class:, function:, params:, source: :mcp)
-        return nil unless defined?(Legion::Ingress)
+      def dispatch(runner_class:, function:, params:, source: :mcp) # rubocop:disable Metrics/MethodLength
+        LoggingSupport.info(
+          'catalog.dispatch.start',
+          runner_class: runner_class,
+          function:     function,
+          source:       source,
+          params:       LoggingSupport.summarize_params(params)
+        )
+        unless defined?(Legion::Ingress)
+          LoggingSupport.warn(
+            'catalog.dispatch.skipped',
+            runner_class: runner_class,
+            function:     function,
+            reason:       'ingress unavailable'
+          )
+          return nil
+        end
 
-        Legion::Ingress.run(
+        result = Legion::Ingress.run(
           payload:       params,
           runner_class:  runner_class,
           function:      function.to_sym,
@@ -16,6 +35,14 @@ module Legion
           check_subtask: true,
           generate_task: true
         )
+        LoggingSupport.info(
+          'catalog.dispatch.complete',
+          runner_class: runner_class,
+          function:     function,
+          source:       source,
+          result:       LoggingSupport.summarize_result(result)
+        )
+        result
       end
 
       def build_tool_class(entry)
@@ -35,13 +62,21 @@ module Legion
           define_singleton_method(:mcp_tier)     { tier }
           define_singleton_method(:catalog_entry) { true }
         end
+        klass.extend(Legion::Logging::Helper)
 
-        wire_dispatch(klass, runner_class_str, function_name)
+        wire_dispatch(klass, runner_class_str, function_name, tool_name_val)
         klass
       end
 
-      def wire_dispatch(klass, runner_class_str, function_name)
-        klass.define_singleton_method(:call) do |**params|
+      def wire_dispatch(klass, runner_class_str, function_name, tool_name_val) # rubocop:disable Metrics/MethodLength
+        klass.define_singleton_method(:call) do |**params| # rubocop:disable Metrics/BlockLength
+          LoggingSupport.info(
+            'catalog.tool_call.start',
+            tool_name:    tool_name_val,
+            runner_class: runner_class_str,
+            function:     function_name,
+            params:       LoggingSupport.summarize_params(params)
+          )
           result = CatalogDispatcher.dispatch(
             runner_class: runner_class_str,
             function:     function_name,
@@ -53,10 +88,25 @@ module Legion
             ::MCP::Tool::Response.new([{ type: 'text', text: text }], error: true)
           else
             text = defined?(Legion::JSON) ? Legion::JSON.dump(result) : result.to_s
-            ::MCP::Tool::Response.new([{ type: 'text', text: text }])
+            response = ::MCP::Tool::Response.new([{ type: 'text', text: text }])
+            LoggingSupport.info(
+              'catalog.tool_call.complete',
+              tool_name:    tool_name_val,
+              runner_class: runner_class_str,
+              function:     function_name,
+              result:       LoggingSupport.summarize_result(response)
+            )
+            response
           end
         rescue StandardError => e
-          Legion::Logging.warn("CatalogDispatcher: #{function_name} failed: #{e.message}") if defined?(Legion::Logging)
+          handle_exception(e, level: :warn, operation: 'legion.mcp.catalog_dispatcher.call')
+          LoggingSupport.warn(
+            'catalog.tool_call.failed',
+            tool_name:    tool_name_val,
+            runner_class: runner_class_str,
+            function:     function_name,
+            error:        e.message
+          )
           text = Legion::JSON.dump({ error: e.message })
           ::MCP::Tool::Response.new([{ type: 'text', text: text }], error: true)
         end
@@ -77,7 +127,8 @@ module Legion
             tier:         cap.respond_to?(:tier) ? cap.tier : nil
           )
         rescue StandardError => e
-          Legion::Logging.debug("CatalogDispatcher: skipping #{cap}: #{e.message}") if defined?(Legion::Logging)
+          handle_exception(e, level: :debug, operation: 'legion.mcp.catalog_dispatcher.generate_tools_from_catalog')
+          log.debug("CatalogDispatcher: skipping #{cap}: #{e.message}")
           nil
         end
       end

data/lib/legion/mcp/client/connection.rb

@@ -1,9 +1,13 @@
 # frozen_string_literal: true
 
+require_relative '../logging_support'
+
 module Legion
   module MCP
     module Client
-      class Connection
+      class Connection # rubocop:disable Metrics/ClassLength
+        include Legion::Logging::Helper
+
         attr_reader :name, :transport_type, :config
 
         TOOL_CACHE_TTL = 300 # seconds
@@ -26,6 +30,12 @@ module Legion
           @mutex.synchronize do
             return if @connected
 
+            LoggingSupport.info(
+              'client.connect.start',
+              connection: @name,
+              transport:  @transport_type,
+              config:     @config.slice(:url, :command)
+            )
             case @transport_type
             when :stdio
               connect_stdio
@@ -35,9 +45,15 @@ module Legion
               raise ArgumentError, "Unknown transport: #{@transport_type}"
             end
             @connected = true
+            LoggingSupport.info(
+              'client.connect.complete',
+              connection: @name,
+              transport:  @transport_type
+            )
           end
-        rescue StandardError
+        rescue StandardError => e
           @connected = false
+          handle_exception(e, level: :error, operation: 'legion.mcp.client.connection.connect')
           raise
         end
 
@@ -53,18 +69,61 @@ module Legion
           @mutex.synchronize do
             if !force_refresh && @tools_cache && @tools_cached_at &&
                (Time.now - @tools_cached_at) < TOOL_CACHE_TTL
+              LoggingSupport.info(
+                'client.tools.cache_hit',
+                connection: @name,
+                transport:  @transport_type,
+                count:      @tools_cache.size
+              )
               return @tools_cache
             end
 
+            LoggingSupport.info(
+              'client.tools.fetch.start',
+              connection:    @name,
+              transport:     @transport_type,
+              force_refresh: force_refresh
+            )
             @tools_cache = fetch_tools
             @tools_cached_at = Time.now
+            LoggingSupport.info(
+              'client.tools.fetch.complete',
+              connection: @name,
+              transport:  @transport_type,
+              count:      @tools_cache.size
+            )
             @tools_cache
           end
         end
 
         def call_tool(name:, arguments: {})
           connect unless connected?
-          execute_tool_call(name: name, arguments: arguments)
+          LoggingSupport.info(
+            'client.tool_call.start',
+            connection: @name,
+            transport:  @transport_type,
+            tool_name:  name,
+            arguments:  LoggingSupport.summarize_params(arguments)
+          )
+          result = execute_tool_call(name: name, arguments: arguments)
+          LoggingSupport.info(
+            'client.tool_call.complete',
+            connection: @name,
+            transport:  @transport_type,
+            tool_name:  name,
+            result:     LoggingSupport.summarize_result(result)
+          )
+          result
+        rescue StandardError => e
+          handle_exception(e, level: :warn, operation: 'legion.mcp.client.connection.call_tool')
+          LoggingSupport.warn(
+            'client.tool_call.failed',
+            connection: @name,
+            transport:  @transport_type,
+            tool_name:  name,
+            error:      e.message
+          )
+          raise
         end
 
         private

data/lib/legion/mcp/client/pool.rb

@@ -7,6 +7,8 @@ module Legion
         @connections = {}
         @mutex = Mutex.new
 
+        extend Legion::Logging::Helper
+
         module_function
 
         def connection_for(server_name)
@@ -30,7 +32,8 @@ module Legion
               tool.merge(source: { type: :mcp, server: name })
             end
           rescue StandardError => e
-            Legion::Logging.warn("MCP tool discovery failed for #{name}: #{e.message}") if defined?(Legion::Logging)
+            handle_exception(e, level: :warn, operation: 'legion.mcp.client.pool.all_tools')
+            log.warn("MCP tool discovery failed for #{name}: #{e.message}")
             ServerRegistry.mark_unhealthy(name)
             []
           end
@@ -38,7 +41,11 @@ module Legion
 
         def reset!
           @mutex.synchronize do
-            @connections.each_value { |c| c.disconnect rescue nil } # rubocop:disable Style/RescueModifier
+            @connections.each_value do |connection|
+              connection.disconnect
+            rescue StandardError => e
+              handle_exception(e, level: :debug, operation: 'legion.mcp.client.pool.reset!')
+            end
             @connections.clear
           end
         end

data/lib/legion/mcp/client.rb

@@ -3,14 +3,22 @@
 module Legion
   module MCP
     module Client
+      extend Legion::Logging::Helper
+
       module_function
 
       def boot
-        servers = Legion::Settings.dig(:mcp, :servers) rescue nil # rubocop:disable Style/RescueModifier
+        log.info('Starting legion.mcp.client.boot')
+        servers = begin
+          Legion::Settings.dig(:mcp, :servers)
+        rescue StandardError => e
+          handle_exception(e, level: :debug, operation: 'legion.mcp.client.boot')
+          nil
+        end
         return unless servers.is_a?(Hash) && servers.any?
 
         ServerRegistry.load_from_settings(servers)
-        Legion::Logging.info("MCP Client: #{servers.length} servers registered") if defined?(Legion::Logging)
+        log.info("MCP Client: #{servers.length} servers registered")
       end
 
       def shutdown

data/lib/legion/mcp/cold_start.rb

@@ -6,9 +6,12 @@ require_relative 'pattern_exchange'
 module Legion
   module MCP
     module ColdStart
+      extend Legion::Logging::Helper
+
       module_function
 
       def load_community_patterns(path: nil)
+        log.info('Starting legion.mcp.cold_start.load_community_patterns')
         return { skipped: true, reason: 'store not empty' } unless PatternStore.empty?
 
         path ||= configured_path
@@ -16,7 +19,8 @@ module Legion
 
         PatternExchange.import_from_file(path, trust_level: :community)
       rescue StandardError => e
-        Legion::Logging.error("ColdStart#load_community_patterns failed: #{e.message}") if defined?(Legion::Logging)
+        handle_exception(e, level: :error, operation: 'legion.mcp.cold_start.load_community_patterns')
+        log.error("ColdStart#load_community_patterns failed: #{e.message}")
         { error: e.message, imported: 0 }
       end
 
@@ -25,7 +29,8 @@ module Legion
 
         Legion::Settings.dig(:mcp, :cold_start, :patterns_path)
       rescue StandardError => e
-        Legion::Logging.warn("ColdStart#configured_path failed: #{e.message}") if defined?(Legion::Logging)
+        handle_exception(e, level: :warn, operation: 'legion.mcp.cold_start.configured_path')
+        log.warn("ColdStart#configured_path failed: #{e.message}")
         nil
       end
     end

data/lib/legion/mcp/context_guard.rb

@@ -8,6 +8,8 @@ module Legion
       DEFAULT_RAPID_FIRE_WINDOW_SECS = 600
       DEFAULT_ANOMALY_MISS_THRESHOLD = 2
 
+      extend Legion::Logging::Helper
+
       module_function
 
       def check(pattern, _params, _context)
@@ -76,7 +78,8 @@ module Legion
 
         Legion::Settings.dig(:mcp, :tier0, :guards, key)
       rescue StandardError => e
-        Legion::Logging.warn("ContextGuard#setting failed for key #{key}: #{e.message}") if defined?(Legion::Logging)
+        handle_exception(e, level: :warn, operation: 'legion.mcp.context_guard.setting')
+        log.warn("ContextGuard#setting failed for key #{key}: #{e.message}")
         nil
       end
 

data/lib/legion/mcp/dynamic_injector.rb

@@ -5,6 +5,8 @@ module Legion
     module DynamicInjector
       MAX_INJECTED = 10
 
+      extend Legion::Logging::Helper
+
       module_function
 
       def enabled?
@@ -52,7 +54,8 @@ module Legion
 
         server.notify_tools_list_changed
       rescue StandardError => e
-        Legion::Logging.debug("DynamicInjector: notify failed: #{e.message}") if defined?(Legion::Logging)
+        handle_exception(e, level: :debug, operation: 'legion.mcp.dynamic_injector.notify_if_changed')
+        log.debug("DynamicInjector: notify failed: #{e.message}")
       end
 
       def inject_for_context(server, intent_string, previous_names: [])

data/lib/legion/mcp/embedding_index.rb

@@ -3,6 +3,8 @@
 module Legion
   module MCP
     module EmbeddingIndex
+      extend Legion::Logging::Helper
+
       module_function
 
       def build_from_tool_data(tool_data, embedder: default_embedder)
@@ -98,7 +100,8 @@ module Legion
 
         result
       rescue StandardError => e
-        Legion::Logging.debug("EmbeddingIndex#safe_embed failed: #{e.message}") if defined?(Legion::Logging)
+        handle_exception(e, level: :debug, operation: 'legion.mcp.embedding_index.safe_embed')
+        log.debug("EmbeddingIndex#safe_embed failed: #{e.message}")
         nil
       end
 
@@ -107,7 +110,8 @@ module Legion
 
         ->(text) { Legion::LLM.embed(text)[:vector] }
       rescue StandardError => e
-        Legion::Logging.debug("EmbeddingIndex#default_embedder failed: #{e.message}") if defined?(Legion::Logging)
+        handle_exception(e, level: :debug, operation: 'legion.mcp.embedding_index.default_embedder')
+        log.debug("EmbeddingIndex#default_embedder failed: #{e.message}")
         nil
       end
     end

data/lib/legion/mcp/function_discovery.rb

@@ -3,6 +3,8 @@
 module Legion
   module MCP
     module FunctionDiscovery
+      extend Legion::Logging::Helper
+
       module_function
 
       def discover_and_register
@@ -19,7 +21,8 @@ module Legion
 
           ext.runner_modules.each { |runner_mod| build_tools_from_runner(runner_mod) }
         rescue StandardError => e
-          Legion::Logging.debug("FunctionDiscovery: skipping #{ext}: #{e.message}") if defined?(Legion::Logging)
+          handle_exception(e, level: :debug, operation: 'legion.mcp.function_discovery.discover_and_register')
+          log.debug("FunctionDiscovery: skipping #{ext}: #{e.message}")
         end
       end
 
@@ -141,6 +144,7 @@ module Legion
               begin
                 runner_ref.public_send(func_ref, **params)
               rescue StandardError => e
+                handle_exception(e, level: :warn, operation: 'legion.mcp.function_discovery.call')
                 error = true
                 { error: e.message }
               end