legionio 1.4.70 → 1.4.72

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f924192ddb882e9dd08fa0ada9088c4f9f468ef8d782df7a06888774ebe5b9d
-  data.tar.gz: f7eab58ceaf4f9119dad859f9b5d47945b57854a2e65e7f68484660da9c2f3a9
+  metadata.gz: d9c2f9048a25ea9cff5f0b8db43aaaf49ab40bb6c388b2f892c3f952fb7233f4
+  data.tar.gz: 02225b7029518b45f1d78f632cce4fdbaee631efb9c03cade5e575ac3c96e3cf
 SHA512:
-  metadata.gz: 5b120a8843d8626da5508cfef24fa2791539c135d090a83a1519e9db99d3fb78aac7b52fde48b2c844435687114dada9b9622d73f6ab204607e73f422f2a9b90
-  data.tar.gz: 6965a20d9389f2b8e16be7e83fdac2835c6b18d47269bb9bf9f102588d03ed7df72b62cc119afeb1f7b0c29695efd0654e60af093bff4e00d3e2eefc76f76723
+  metadata.gz: 758ee671a15875e26a60fe87b10b3499c5ef47f766d5cd3d43498b7c362be4a791defe79b99bda56ccbf263558fa7a4e8450b307f3bc29734c3c3d279bba4dd4
+  data.tar.gz: 2c04803613fe2a2ba39ef4aa29865f66b96b237ba7c3f74920cd784bedfebc9bc90df91042714a016f06587a6d234ed722cf29a5727c039e8f09fbddfb322184

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Legion Changelog
 
+## [1.4.72] - 2026-03-19
+
+### Added
+- TBI Phase 0+2: MCP tool observation pipeline and usage-based filtering
+- `Legion::MCP::Observer` module: in-memory tool call recording with counters, ring buffer, and intent tracking
+- `Legion::MCP::UsageFilter` module: scores tools by frequency, recency, and keyword match; prunes dead tools
+- MCP `instrumentation_callback` wiring: automatically records all `tools/call` invocations via Observer
+- MCP `tools_list_handler` wiring: dynamically filters and ranks tools per-request based on usage data
+- `legion observe` CLI command: `stats`, `recent`, `reset` subcommands for MCP tool usage inspection
+- 96 new specs covering Observer, UsageFilter, CLI command, and integration wiring
+
+## [1.4.71] - 2026-03-19
+
+### Added
+- `POST /api/llm/chat` daemon endpoint with async (202) and sync (201) response paths
+- `ContextCompiler` module: categorizes 35 MCP tools into 9 groups with keyword matching
+- `legion.do` meta-tool: natural language intent routing to best-matching MCP tool
+- `legion.tools` meta-tool: compressed catalog, category browsing, and intent-matched discovery
+
+### Fixed
+- `ContextCompiler.build_tool_index` now handles `MCP::Tool::InputSchema` objects (not just hashes)
+
 ## [1.4.70] - 2026-03-19
 
 ### Added

data/CLAUDE.md

@@ -9,7 +9,7 @@ The primary gem for the LegionIO framework. An extensible async job engine for s
 
 **GitHub**: https://github.com/LegionIO/LegionIO
 **Gem**: `legionio`
-**Version**: 1.4.67
+**Version**: 1.4.70
 **License**: Apache-2.0
 **Docker**: `legionio/legion`
 **Ruby**: >= 3.4
@@ -39,21 +39,26 @@ Before any Legion code loads, `exe/legion` applies three performance optimizatio
 ```
 Legion.start
   └── Legion::Service.new
-      ├── 1. setup_logging      (legion-logging)
-      ├── 2. setup_settings     (legion-settings, loads /etc/legionio, ~/legionio, ./settings)
-      ├── 3. Legion::Crypt.start (legion-crypt, Vault connection)
-      ├── 4. setup_transport    (legion-transport, RabbitMQ connection)
-      ├── 5. require legion-cache
-      ├── 6. setup_data         (legion-data, MySQL/SQLite + migrations, optional)
-      ├── 7. setup_llm          (legion-llm, optional)
-      ├── 8. setup_supervision  (process supervision)
-      ├── 9. load_extensions    (discover + load LEX gems, filtered by role profile)
-      ├── 10. Legion::Crypt.cs  (distribute cluster secret)
-      └── 11. setup_api         (start Sinatra/Puma on port 4567)
+      ├── 1.  setup_logging      (legion-logging)
+      ├── 2.  setup_settings     (legion-settings, loads /etc/legionio, ~/legionio, ./settings)
+      ├── 3.  Legion::Crypt.start (legion-crypt, Vault connection)
+      ├── 4.  setup_transport    (legion-transport, RabbitMQ connection)
+      ├── 5.  require legion-cache
+      ├── 6.  setup_data         (legion-data, MySQL/SQLite + migrations, optional)
+      ├── 7.  setup_rbac         (legion-rbac, optional)
+      ├── 8.  setup_llm          (legion-llm, optional)
+      ├── 9.  setup_gaia         (legion-gaia, cognitive layer, optional)
+      ├── 10. setup_telemetry    (OpenTelemetry, optional)
+      ├── 11. setup_supervision  (process supervision)
+      ├── 12. load_extensions    (two-phase: require+autobuild all, then hook_all_actors)
+      ├── 13. Legion::Crypt.cs   (distribute cluster secret)
+      └── 14. setup_api          (start Sinatra/Puma on port 4567)
 ```
 
 Each phase calls `Legion::Readiness.mark_ready(:component)`. All phases are individually toggleable via `Service.new(transport: false, ...)`.
 
+Extension loading is two-phase: all extensions are `require`d and `autobuild` runs first, collecting actors into `@pending_actors`. After all extensions are loaded, `hook_all_actors` starts AMQP subscriptions, timers, and other actor types. This prevents race conditions where early extensions start ticking while later ones haven't loaded yet.
+
 ### Reload Sequence
 
 `Legion.reload` shuts down all subsystems in reverse order, waits for them to drain, then re-runs setup from settings onward. Extensions and API are re-loaded fresh.
@@ -66,7 +71,7 @@ Legion (lib/legion.rb)
 │                      # Entry points: Legion.start, .shutdown, .reload
 ├── Process            # Daemonization: PID management, signal traps (SIGINT=quit), main loop
 ├── Readiness          # Startup readiness tracking
-│                      # COMPONENTS: settings, crypt, transport, cache, data, extensions, api
+│                      # COMPONENTS: settings, crypt, transport, cache, data, gaia, extensions, api
 │                      # Readiness.ready? checks all; /api/ready returns JSON status
 ├── Events             # In-process pub/sub event bus
 │                      # Events.on(name) / .emit(name, **payload) / .once / .off
@@ -723,8 +728,8 @@ rack-test, rake, rspec, rubocop, rubocop-rspec, simplecov
 
 ```bash
 bundle install
-bundle exec rspec       # 1379 examples, 0 failures
-bundle exec rubocop     # 396 files, 0 offenses
+bundle exec rspec       # 1433 examples, 0 failures
+bundle exec rubocop     # 418 files, 0 offenses
 ```
 
 Specs use `rack-test` for API testing. `Legion::JSON.load` returns symbol keys — use `body[:data]` not `body['data']` in specs.

data/lib/legion/api/llm.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  class API < Sinatra::Base
+    module Routes
+      module Llm
+        def self.registered(app)
+          app.helpers do
+            define_method(:require_llm!) do
+              return if defined?(Legion::LLM) &&
+                        Legion::LLM.respond_to?(:started?) &&
+                        Legion::LLM.started?
+
+              halt 503, { 'Content-Type' => 'application/json' },
+                   Legion::JSON.dump({ error: { code:    'llm_unavailable',
+                                                message: 'LLM subsystem is not available' } })
+            end
+
+            define_method(:cache_available?) do
+              defined?(Legion::Cache) &&
+                Legion::Cache.respond_to?(:connected?) &&
+                Legion::Cache.connected?
+            end
+          end
+
+          register_chat(app)
+        end
+
+        def self.register_chat(app)
+          app.post '/api/llm/chat' do # rubocop:disable Metrics/BlockLength
+            require_llm!
+
+            body = parse_request_body
+            validate_required!(body, :message)
+
+            request_id = body[:request_id] || SecureRandom.uuid
+            message    = body[:message]
+            model      = body[:model]
+            provider   = body[:provider]
+
+            if cache_available?
+              llm = Legion::LLM
+              rc  = Legion::LLM::ResponseCache
+              rc.init_request(request_id)
+
+              Thread.new do
+                session  = llm.chat_direct(model: model, provider: provider)
+                response = session.ask(message)
+                rc.complete(
+                  request_id,
+                  response: response.content,
+                  meta:     {
+                    model:      session.model.to_s,
+                    tokens_in:  response.respond_to?(:input_tokens) ? response.input_tokens : nil,
+                    tokens_out: response.respond_to?(:output_tokens) ? response.output_tokens : nil
+                  }
+                )
+              rescue StandardError => e
+                rc.fail_request(request_id, code: 'llm_error', message: e.message)
+              end
+
+              json_response({ request_id: request_id, poll_key: "llm:#{request_id}:status" },
+                            status_code: 202)
+            else
+              session  = Legion::LLM.chat_direct(model: model, provider: provider)
+              response = session.ask(message)
+              json_response(
+                {
+                  response: response.content,
+                  meta:     {
+                    model:      session.model.to_s,
+                    tokens_in:  response.respond_to?(:input_tokens) ? response.input_tokens : nil,
+                    tokens_out: response.respond_to?(:output_tokens) ? response.output_tokens : nil
+                  }
+                },
+                status_code: 201
+              )
+            end
+          end
+        end
+
+        class << self
+          private :register_chat
+        end
+      end
+    end
+  end
+end

data/lib/legion/api.rb

@@ -33,6 +33,7 @@ require_relative 'api/auth_kerberos'
 require_relative 'api/capacity'
 require_relative 'api/audit'
 require_relative 'api/metrics'
+require_relative 'api/llm'
 
 module Legion
   class API < Sinatra::Base
@@ -108,6 +109,7 @@ module Legion
     register Routes::Capacity
     register Routes::Audit
     register Routes::Metrics
+    register Routes::Llm
 
     use Legion::Rbac::Middleware if defined?(Legion::Rbac::Middleware)
 

data/lib/legion/cli/observe_command.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'thor'
+require 'legion/mcp/observer'
+
+module Legion
+  module CLI
+    class ObserveCommand < Thor
+      namespace :observe
+
+      desc 'stats', 'Show MCP tool usage statistics'
+      def stats
+        data = Legion::MCP::Observer.stats
+
+        if options['json']
+          puts ::JSON.pretty_generate(serialize_stats(data))
+          return
+        end
+
+        puts 'MCP Tool Observation Stats'
+        puts '=' * 40
+        puts "Total Calls:  #{data[:total_calls]}"
+        puts "Tools Used:   #{data[:tool_count]}"
+        puts "Failure Rate: #{(data[:failure_rate] * 100).round(1)}%"
+        puts "Since:        #{data[:since]&.strftime('%Y-%m-%d %H:%M:%S')}"
+        puts
+
+        return if data[:top_tools].empty?
+
+        puts 'Top Tools:'
+        puts '-' * 60
+        puts 'Tool                            Calls  Avg(ms)  Fails'
+        puts '-' * 60
+        data[:top_tools].each do |tool|
+          puts format('%-30<name>s %6<calls>d %8<avg>d %6<fails>d',
+                      name: tool[:name], calls: tool[:call_count],
+                      avg: tool[:avg_latency_ms], fails: tool[:failure_count])
+        end
+      end
+
+      desc 'recent', 'Show recent MCP tool calls'
+      method_option :limit, type: :numeric, default: 20, aliases: '-n'
+      def recent
+        calls = Legion::MCP::Observer.recent(options['limit'] || 20)
+
+        if options['json']
+          puts ::JSON.pretty_generate(calls.map { |c| serialize_call(c) })
+          return
+        end
+
+        if calls.empty?
+          puts 'No recent tool calls recorded.'
+          return
+        end
+
+        puts 'Tool                           Duration  Status Time'
+        puts '-' * 70
+        calls.reverse_each do |call|
+          status = call[:success] ? 'OK' : 'FAIL'
+          time = call[:timestamp]&.strftime('%H:%M:%S')
+          puts format('%-30<tool>s %6<dur>dms %7<st>s %<tm>s',
+                      tool: call[:tool_name], dur: call[:duration_ms], st: status, tm: time)
+        end
+      end
+
+      desc 'reset', 'Clear all observation data'
+      def reset
+        print 'Clear all observation data? (yes/no): '
+        return unless $stdin.gets&.strip&.downcase == 'yes'
+
+        Legion::MCP::Observer.reset!
+        puts 'Observation data cleared.'
+      end
+
+      private
+
+      def serialize_stats(data)
+        {
+          total_calls:  data[:total_calls],
+          tool_count:   data[:tool_count],
+          failure_rate: data[:failure_rate],
+          since:        data[:since]&.iso8601,
+          top_tools:    data[:top_tools].map { |t| t.transform_keys(&:to_s) }
+        }
+      end
+
+      def serialize_call(call)
+        call.transform_keys(&:to_s).tap do |c|
+          c['timestamp'] = c['timestamp']&.iso8601 if c['timestamp']
+        end
+      end
+    end
+  end
+end

data/lib/legion/cli.rb

@@ -43,7 +43,8 @@ module Legion
     autoload :Marketplace, 'legion/cli/marketplace_command'
     autoload :Notebook,    'legion/cli/notebook_command'
     autoload :Llm,         'legion/cli/llm_command'
-    autoload :Tty,         'legion/cli/tty_command'
+    autoload :Tty,            'legion/cli/tty_command'
+    autoload :ObserveCommand, 'legion/cli/observe_command'
     autoload :Interactive, 'legion/cli/interactive'
 
     class Main < Thor
@@ -241,6 +242,9 @@ module Legion
       desc 'tty', 'Rich terminal UI (onboarding, AI chat, dashboard)'
       subcommand 'tty', Legion::CLI::Tty
 
+      desc 'observe SUBCOMMAND', 'MCP tool observation stats'
+      subcommand 'observe', Legion::CLI::ObserveCommand
+
       desc 'tree', 'Print a tree of all available commands'
       def tree
         legion_print_command_tree(self.class, 'legion', '')

data/lib/legion/mcp/context_compiler.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Legion
+  module MCP
+    module ContextCompiler
+      CATEGORIES = {
+        tasks:         {
+          tools:   %w[legion.run_task legion.list_tasks legion.get_task legion.delete_task legion.get_task_logs],
+          summary: 'Create, list, query, and delete tasks. Run functions via dot-notation task identifiers.'
+        },
+        chains:        {
+          tools:   %w[legion.list_chains legion.create_chain legion.update_chain legion.delete_chain],
+          summary: 'Manage task chains - ordered sequences of tasks that execute in series.'
+        },
+        relationships: {
+          tools:   %w[legion.list_relationships legion.create_relationship legion.update_relationship
+                      legion.delete_relationship],
+          summary: 'Manage trigger-action relationships between functions.'
+        },
+        extensions:    {
+          tools:   %w[legion.list_extensions legion.get_extension legion.enable_extension
+                      legion.disable_extension],
+          summary: 'Manage LEX extensions - list installed, inspect details, enable/disable.'
+        },
+        schedules:     {
+          tools:   %w[legion.list_schedules legion.create_schedule legion.update_schedule legion.delete_schedule],
+          summary: 'Manage scheduled tasks - cron-style recurring task execution.'
+        },
+        workers:       {
+          tools:   %w[legion.list_workers legion.show_worker legion.worker_lifecycle legion.worker_costs],
+          summary: 'Manage digital workers - list, inspect, lifecycle transitions, cost tracking.'
+        },
+        rbac:          {
+          tools:   %w[legion.rbac_check legion.rbac_assignments legion.rbac_grants],
+          summary: 'Role-based access control - check permissions, view assignments and grants.'
+        },
+        status:        {
+          tools:   %w[legion.get_status legion.get_config legion.team_summary legion.routing_stats],
+          summary: 'System status, configuration, team overview, and routing statistics.'
+        },
+        describe:      {
+          tools:   %w[legion.describe_runner],
+          summary: 'Inspect a specific runner function - parameters, return type, metadata.'
+        }
+      }.freeze
+
+      module_function
+
+      # Returns a compressed summary of all categories with tool counts and tool name lists.
+      # @return [Array<Hash>] array of { category:, summary:, tool_count:, tools: }
+      def compressed_catalog
+        CATEGORIES.map do |category, config|
+          tool_names = config[:tools]
+          {
+            category:   category,
+            summary:    config[:summary],
+            tool_count: tool_names.length,
+            tools:      tool_names
+          }
+        end
+      end
+
+      # Returns tools for a specific category, filtered to only those present in TOOL_CLASSES.
+      # @param category_sym [Symbol] one of the CATEGORIES keys
+      # @return [Hash, nil] { category:, summary:, tools: [{ name:, description:, params: }] } or nil
+      def category_tools(category_sym)
+        config = CATEGORIES[category_sym]
+        return nil unless config
+
+        index = tool_index
+        tools = config[:tools].filter_map { |name| index[name] }
+        return nil if tools.empty?
+
+        {
+          category: category_sym,
+          summary:  config[:summary],
+          tools:    tools
+        }
+      end
+
+      # Keyword-match intent against tool names and descriptions.
+      # @param intent_string [String] natural language intent
+      # @return [Class, nil] best matching tool CLASS from Server::TOOL_CLASSES or nil
+      def match_tool(intent_string)
+        scored = scored_tools(intent_string)
+        return nil if scored.empty?
+
+        best = scored.max_by { |entry| entry[:score] }
+        return nil if best[:score].zero?
+
+        Server::TOOL_CLASSES.find { |klass| klass.tool_name == best[:name] }
+      end
+
+      # Returns top N keyword-matched tools ranked by score.
+      # @param intent_string [String] natural language intent
+      # @param limit [Integer] max results (default 5)
+      # @return [Array<Hash>] array of { name:, description:, score: }
+      def match_tools(intent_string, limit: 5)
+        scored = scored_tools(intent_string)
+                 .select { |entry| entry[:score].positive? }
+                 .sort_by { |entry| -entry[:score] }
+        scored.first(limit)
+      end
+
+      # Returns a hash keyed by tool_name with compressed param info.
+      # Memoized — call reset! to clear.
+      # @return [Hash<String, Hash>] { name:, description:, params: [String] }
+      def tool_index
+        @tool_index ||= build_tool_index
+      end
+
+      # Clears the memoized tool_index.
+      def reset!
+        @tool_index = nil
+      end
+
+      def build_tool_index
+        Server::TOOL_CLASSES.each_with_object({}) do |klass, idx|
+          raw_schema = klass.input_schema
+          schema = raw_schema.is_a?(Hash) ? raw_schema : raw_schema.to_h
+          properties = schema[:properties] || {}
+          idx[klass.tool_name] = {
+            name:        klass.tool_name,
+            description: klass.description,
+            params:      properties.keys.map(&:to_s)
+          }
+        end
+      end
+
+      def scored_tools(intent_string)
+        keywords = intent_string.downcase.split
+        return [] if keywords.empty?
+
+        tool_index.values.map do |entry|
+          haystack = "#{entry[:name].downcase} #{entry[:description].downcase}"
+          score    = keywords.count { |kw| haystack.include?(kw) }
+          { name: entry[:name], description: entry[:description], score: score }
+        end
+      end
+    end
+  end
+end

data/lib/legion/mcp/observer.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require 'concurrent-ruby'
+
+module Legion
+  module MCP
+    module Observer
+      RING_BUFFER_MAX   = 500
+      INTENT_BUFFER_MAX = 200
+
+      module_function
+
+      def record(tool_name:, duration_ms:, success:, params_keys: [], error: nil)
+        now = Time.now
+
+        counters_mutex.synchronize do
+          entry = counters[tool_name] || { call_count: 0, total_latency_ms: 0.0, failure_count: 0,
+                                           last_used: nil, last_error: nil }
+          counters[tool_name] = {
+            call_count:       entry[:call_count] + 1,
+            total_latency_ms: entry[:total_latency_ms] + duration_ms.to_f,
+            failure_count:    entry[:failure_count] + (success ? 0 : 1),
+            last_used:        now,
+            last_error:       success ? entry[:last_error] : error
+          }
+        end
+
+        buffer_mutex.synchronize do
+          ring_buffer << {
+            tool_name:   tool_name,
+            duration_ms: duration_ms,
+            success:     success,
+            params_keys: params_keys,
+            error:       error,
+            recorded_at: now
+          }
+          ring_buffer.shift if ring_buffer.size > RING_BUFFER_MAX
+        end
+      end
+
+      def record_intent(intent, matched_tool_name)
+        intent_mutex.synchronize do
+          intent_buffer << { intent: intent, matched_tool: matched_tool_name, recorded_at: Time.now }
+          intent_buffer.shift if intent_buffer.size > INTENT_BUFFER_MAX
+        end
+      end
+
+      def tool_stats(tool_name)
+        entry = counters_mutex.synchronize { counters[tool_name] }
+        return nil unless entry
+
+        count = entry[:call_count]
+        avg   = count.positive? ? (entry[:total_latency_ms] / count).round(2) : 0.0
+
+        {
+          name:           tool_name,
+          call_count:     count,
+          avg_latency_ms: avg,
+          failure_count:  entry[:failure_count],
+          last_used:      entry[:last_used],
+          last_error:     entry[:last_error]
+        }
+      end
+
+      def all_tool_stats
+        names = counters_mutex.synchronize { counters.keys.dup }
+        names.to_h { |name| [name, tool_stats(name)] }
+      end
+
+      def stats
+        all_names = counters_mutex.synchronize { counters.keys.dup }
+        total     = all_names.sum { |n| counters_mutex.synchronize { counters[n][:call_count] } }
+        failures  = all_names.sum { |n| counters_mutex.synchronize { counters[n][:failure_count] } }
+        rate      = total.positive? ? (failures.to_f / total).round(4) : 0.0
+
+        top = all_names
+              .map { |n| tool_stats(n) }
+              .sort_by { |s| -s[:call_count] }
+              .first(10)
+
+        {
+          total_calls:  total,
+          tool_count:   all_names.size,
+          failure_rate: rate,
+          top_tools:    top,
+          since:        started_at
+        }
+      end
+
+      def recent(limit = 10)
+        buffer_mutex.synchronize { ring_buffer.last(limit) }
+      end
+
+      def recent_intents(limit = 10)
+        intent_mutex.synchronize { intent_buffer.last(limit) }
+      end
+
+      def reset!
+        counters_mutex.synchronize { counters.clear }
+        buffer_mutex.synchronize { ring_buffer.clear }
+        intent_mutex.synchronize { intent_buffer.clear }
+        @started_at = Time.now
+      end
+
+      # Internal state accessors
+      def counters
+        @counters ||= {}
+      end
+
+      def counters_mutex
+        @counters_mutex ||= Mutex.new
+      end
+
+      def ring_buffer
+        @ring_buffer ||= []
+      end
+
+      def buffer_mutex
+        @buffer_mutex ||= Mutex.new
+      end
+
+      def intent_buffer
+        @intent_buffer ||= []
+      end
+
+      def intent_mutex
+        @intent_mutex ||= Mutex.new
+      end
+
+      def started_at
+        @started_at ||= Time.now
+      end
+    end
+  end
+end

data/lib/legion/mcp/server.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'observer'
+require_relative 'usage_filter'
 require_relative 'tools/run_task'
 require_relative 'tools/describe_runner'
 require_relative 'tools/list_tasks'
@@ -33,6 +35,9 @@ require_relative 'tools/routing_stats'
 require_relative 'tools/rbac_check'
 require_relative 'tools/rbac_assignments'
 require_relative 'tools/rbac_grants'
+require_relative 'context_compiler'
+require_relative 'tools/do_action'
+require_relative 'tools/discover_tools'
 require_relative 'resources/runner_catalog'
 require_relative 'resources/extension_info'
 
@@ -72,7 +77,9 @@ module Legion
         Tools::RoutingStats,
         Tools::RbacCheck,
         Tools::RbacAssignments,
-        Tools::RbacGrants
+        Tools::RbacGrants,
+        Tools::DoAction,
+        Tools::DiscoverTools
       ].freeze
 
       class << self
@@ -92,12 +99,44 @@ module Legion
             resource_templates: Resources::ExtensionInfo.resource_templates
           )
 
+          if defined?(Observer)
+            ::MCP.configure do |c|
+              c.instrumentation_callback = ->(idata) { Server.wire_observer(idata) }
+            end
+          end
+
+          server.tools_list_handler do |_params|
+            build_filtered_tool_list.map(&:to_h)
+          end
+
           Resources::RunnerCatalog.register(server)
           Resources::ExtensionInfo.register_read_handler(server)
 
           server
         end
 
+        def wire_observer(data)
+          return unless data[:method] == 'tools/call' && data[:tool_name]
+
+          duration_ms = (data[:duration].to_f * 1000).to_i
+          params_keys = data[:tool_arguments].respond_to?(:keys) ? data[:tool_arguments].keys : []
+          success     = data[:error].nil?
+
+          Observer.record(
+            tool_name:   data[:tool_name],
+            duration_ms: duration_ms,
+            success:     success,
+            params_keys: params_keys,
+            error:       data[:error]
+          )
+        end
+
+        def build_filtered_tool_list(keywords: [])
+          tool_names = TOOL_CLASSES.map { |tc| tc.respond_to?(:tool_name) ? tc.tool_name : tc.name }
+          ranked     = UsageFilter.ranked_tools(tool_names, keywords: keywords)
+          ranked.filter_map { |name| TOOL_CLASSES.find { |tc| (tc.respond_to?(:tool_name) ? tc.tool_name : tc.name) == name } }
+        end
+
         private
 
         def instructions