legion-mcp 0.6.6 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e1c1371cb216ffb1b47a924ec9fd5d65b352b94a87e0103ef28d2f96aee77b1
-  data.tar.gz: 0e96367cb8c743f2408f95c9ccdf051ecd1ba991302963b4e5b5c500db5eb136
+  metadata.gz: ee9fe829857bd0a2546ea95daf827d33fe60084094e665a78f7fe78742064978
+  data.tar.gz: cc57fd55347d9a541b382d7ca8a92d4a2d9094e674142e4336cfaadf46f4071c
 SHA512:
-  metadata.gz: ab78e2afd0d736017b922a12010c3feb9ca519a82599e163e6cdf187d448978b40a62a5efc2f0ebe7991424af5593effa6dfe89c17192eb721b809216ba80f01
-  data.tar.gz: 4ee7a30af588af08bf7090748dd700ff40863150bf4cbdaf147e5f073cb60c7bff82ac26758c650e325c4833b24fc5a2e4bd17ca341c8bbfede8e24e9d037677
+  metadata.gz: 15839e1d0bda42420e4734eef4a550a8b8b163453ec68a5eaf75aeb33b1d931625a5da8b30449db7627d2965ad7306d2a2c00633f559895ee442da35e5d5cee4
+  data.tar.gz: 77b1a31f1c5a24bc4c36b537500dfe849f9ff413a14de994032551d3161e52dee33729bd292ebb1a69fbe2625eeda682c985aa0c3937ed9d97ea30da7d0049d9

data/AGENTS.md

@@ -0,0 +1,37 @@
+# legion-mcp Agent Notes
+
+## Scope
+
+`legion-mcp` is the standalone MCP server gem for Legion. It owns tool/resource registration, tier routing, tool governance, semantic matching, and observation/pattern promotion.
+
+## Fast Start
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop -A
+bundle exec rubocop
+```
+
+## Primary Entry Points
+
+- `lib/legion/mcp.rb`
+- `lib/legion/mcp/server.rb`
+- `lib/legion/mcp/context_compiler.rb`
+- `lib/legion/mcp/tier_router.rb`
+- `lib/legion/mcp/pattern_store.rb`
+- `lib/legion/mcp/observer.rb`
+- `lib/legion/mcp/tools/`
+
+## Guardrails
+
+- Keep optional dependencies guarded (`legion-cache`, `legion-llm`, `Data::Local`); this gem must degrade cleanly.
+- Tier confidence behavior is core contract: Tier 0 (>= 0.8), Tier 1 (0.6-0.8), Tier 2 (< 0.6).
+- Pattern storage failures must not block tool execution.
+- Tool registration remains centralized through server builder/registry; avoid ad hoc registration paths.
+- Preserve governance checks and audit trails for tool invocation.
+
+## Validation
+
+- Run specs for changed tools/router/compiler paths.
+- Before handoff, run `bundle exec rspec`, `bundle exec rubocop -A`, then `bundle exec rubocop`.

data/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-03-31
+
+### Added
+- `DeferredRegistry` module for deferred tool loading — tools not in the always-loaded set return name and description only (no `inputSchema`) in `tools/list`, reducing token footprint by ~75% for standard MCP clients (closes #19)
+- `legion.tools` now accepts `tool_names` (array) + `schema: true` parameters to load full JSON schemas for specific deferred tools on demand
+- `Settings.deferred_loading_defaults` — configurable `enabled` (default true) and `always_loaded` (custom tool names merged with built-in defaults)
+- 13 always-loaded tools: `legion.do`, `legion.tools`, `legion.run_task`, `legion.list_tasks`, `legion.get_task`, `legion.get_status`, `legion.describe_runner`, `legion.plan_action`, `legion.query_knowledge`, `legion.knowledge_context`, `legion.knowledge_health`, `legion.absorb`, `legion.get_task_logs`
+
+- `CatalogDispatcher` module — thin dispatch layer routing MCP tool calls through `Legion::Ingress` for RBAC, audit, and sandbox enforcement; auto-generates tool classes from `Catalog::Registry` entries (closes #20)
+- `DynamicInjector` module — context-aware tool injection/removal using `ContextCompiler.match_tools`; sends `notifications/tools/list_changed` when active tool set changes based on conversation context
+- `CatalogBridge.register_catalog_tools` — auto-generates and registers catalog-sourced tools through `CatalogDispatcher` at server boot
+- `Settings.dynamic_tools_defaults` — configurable `enabled` (default false) and `max_injected` (default 10)
+- `StructuralIndex` module — precomputed static index of all extensions, runners, actors, and tools with JSON cache at `~/.legionio/cache/structural_index.json`; supports filtering by extension name or type (closes #18)
+- `legion.structural_index` MCP tool (61st tool) — query the structural index with optional `extension`, `type`, and `refresh` parameters
+- `ToolQuality` module — docstring quality gate (min description length, param descriptions), category resolution across `CATEGORIES` and `EXPANDED_CATEGORIES`, reads/writes capability matrix, and audit summary (closes #17)
+- `legion.tool_audit` MCP tool (62nd tool) — audit all registered tools with modes: `summary` (default), `matrix` (capability matrix), `issues` (quality warnings only)
+- `ContextCompiler::CATEGORIES` expanded from 9 to 16 categories: added `knowledge`, `mesh`, `mind_growth`, `prompts`, `datasets`, `evals`, `meta` — all 62 tools now have category assignments
+- `StateTracker` module — in-memory state snapshots with timestamps and delta diff computation; tracks tool count, observer stats, pattern count, and extension count (closes #16)
+- `legion.state_diff` MCP tool (63rd tool) — return only changed system state since a given timestamp; supports `snapshot: true` to take a baseline and `since:` for delta polling
+- `legion.search_sessions` MCP tool (64th tool) — search across past conversation sessions by keyword or topic with relevance-sorted results and context snippets (closes #15)
+
+### Changed
+- `Server.build` now installs a custom `tools/list` handler via `install_deferred_tools_list_handler` for mcp gem 0.10 compatibility (replaces removed `tools_list_handler` block API)
+- `Server.build` now calls `register_catalog_tools` to auto-generate Ingress-dispatched tool classes from Catalog entries
+
 ## [0.6.6] - 2026-03-28
 
 ### Added

data/Gemfile

@@ -6,5 +6,6 @@ gemspec
 gem 'rake'
 gem 'rspec'
 gem 'rubocop'
+gem 'rubocop-legion'
 gem 'rubocop-rspec'
 gem 'simplecov'

data/lib/legion/mcp/catalog_bridge.rb

@@ -37,6 +37,10 @@ module Legion
         { status: :error, error: e.message, source: :catalog }
       end
 
+      def register_catalog_tools
+        CatalogDispatcher.generate_tools_from_catalog.each { |tc| Server.register_tool(tc) }
+      end
+
       def dynamic_tool_list
         static = Server.tool_registry.map do |klass|
           { name: klass.tool_name, description: klass.description,

data/lib/legion/mcp/catalog_dispatcher.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Legion
+  module MCP
+    module CatalogDispatcher
+      module_function
+
+      def dispatch(runner_class:, function:, params:, source: :mcp)
+        return nil unless defined?(Legion::Ingress)
+
+        Legion::Ingress.run(
+          payload:       params,
+          runner_class:  runner_class,
+          function:      function.to_sym,
+          source:        source,
+          check_subtask: true,
+          generate_task: true
+        )
+      end
+
+      def build_tool_class(entry)
+        runner_class_str = entry[:runner_class]
+        function_name    = entry[:function]
+        tool_name_val    = entry[:tool_name]
+        desc             = entry[:description]
+        schema           = entry[:input_schema] || { properties: {} }
+        category         = entry[:category]
+        tier             = entry[:tier]
+
+        klass = Class.new(::MCP::Tool) do
+          tool_name tool_name_val
+          description desc
+          input_schema(schema)
+          define_singleton_method(:mcp_category) { category }
+          define_singleton_method(:mcp_tier)     { tier }
+          define_singleton_method(:catalog_entry) { true }
+        end
+
+        wire_dispatch(klass, runner_class_str, function_name)
+        klass
+      end
+
+      def wire_dispatch(klass, runner_class_str, function_name)
+        klass.define_singleton_method(:call) do |**params|
+          result = CatalogDispatcher.dispatch(
+            runner_class: runner_class_str,
+            function:     function_name,
+            params:       params
+          )
+
+          if result.nil?
+            text = Legion::JSON.dump({ error: 'Ingress not available' })
+            ::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 }])
+          end
+        rescue StandardError => e
+          Legion::Logging.warn("CatalogDispatcher: #{function_name} failed: #{e.message}") if defined?(Legion::Logging)
+          text = Legion::JSON.dump({ error: e.message })
+          ::MCP::Tool::Response.new([{ type: 'text', text: text }], error: true)
+        end
+      end
+
+      def generate_tools_from_catalog
+        return [] unless defined?(Legion::Extensions::Catalog::Registry)
+        return [] unless Legion::Extensions::Catalog::Registry.respond_to?(:for_mcp)
+
+        Legion::Extensions::Catalog::Registry.for_mcp.filter_map do |cap|
+          build_tool_class(
+            runner_class: resolve_runner_class(cap),
+            function:     cap.function,
+            tool_name:    cap.respond_to?(:mcp_name) ? cap.mcp_name : "legion.catalog.#{cap.function}",
+            description:  cap.respond_to?(:description) ? cap.description : "Auto-generated: #{cap.function}",
+            input_schema: cap.respond_to?(:input_schema) ? cap.input_schema : { properties: {} },
+            category:     cap.respond_to?(:category) ? cap.category : nil,
+            tier:         cap.respond_to?(:tier) ? cap.tier : nil
+          )
+        rescue StandardError => e
+          Legion::Logging.debug("CatalogDispatcher: skipping #{cap}: #{e.message}") if defined?(Legion::Logging)
+          nil
+        end
+      end
+
+      def resolve_runner_class(cap)
+        segments = cap.extension.delete_prefix('lex-').split('-')
+        (%w[Legion Extensions] + segments.map(&:capitalize) + ['Runners', cap.runner]).join('::')
+      end
+    end
+  end
+end

data/lib/legion/mcp/context_compiler.rb

@@ -43,6 +43,37 @@ module Legion
         describe:      {
           tools:   %w[legion.describe_runner],
           summary: 'Inspect a specific runner function - parameters, return type, metadata.'
+        },
+        knowledge:     {
+          tools:   %w[legion.query_knowledge legion.knowledge_health legion.knowledge_context legion.absorb],
+          summary: 'Knowledge base operations - query, health, context retrieval, content absorption.'
+        },
+        mesh:          {
+          tools:   %w[legion.ask_peer legion.list_peers legion.notify_peer legion.broadcast_peers
+                      legion.mesh_status],
+          summary: 'Agent mesh communication - peer queries, notifications, broadcasts, and topology.'
+        },
+        mind_growth:   {
+          tools:   %w[legion.mind_growth_status legion.mind_growth_propose legion.mind_growth_approve
+                      legion.mind_growth_build_queue legion.mind_growth_cognitive_profile
+                      legion.mind_growth_health],
+          summary: 'Cognitive growth - proposals, approvals, build queue, profiling, fitness scores.'
+        },
+        prompts:       {
+          tools:   %w[legion.prompt_list legion.prompt_show legion.prompt_run],
+          summary: 'Prompt template management - list, view, and render prompt templates.'
+        },
+        datasets:      {
+          tools:   %w[legion.dataset_list legion.dataset_show legion.experiment_results],
+          summary: 'Dataset and experiment browsing - list datasets, view rows, compare results.'
+        },
+        evals:         {
+          tools:   %w[legion.eval_list legion.eval_run legion.eval_results],
+          summary: 'Evaluation management - list evaluators, run evaluations, view results.'
+        },
+        meta:          {
+          tools:   %w[legion.do legion.tools legion.plan_action legion.structural_index],
+          summary: 'Meta-tools - natural language routing, tool discovery, planning, structural index.'
         }
       }.freeze
 

data/lib/legion/mcp/deferred_registry.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Legion
+  module MCP
+    module DeferredRegistry
+      # Tools that are ALWAYS fully loaded (never deferred).
+      # These are high-frequency entry points or meta-tools.
+      ALWAYS_LOADED = %w[
+        legion.do
+        legion.tools
+        legion.run_task
+        legion.list_tasks
+        legion.get_task
+        legion.get_status
+        legion.describe_runner
+        legion.plan_action
+        legion.query_knowledge
+        legion.knowledge_context
+        legion.knowledge_health
+        legion.absorb
+        legion.get_task_logs
+      ].freeze
+
+      module_function
+
+      def enabled?
+        setting = Legion::Settings.dig(:mcp, :deferred_loading, :enabled)
+        setting.nil? || setting
+      end
+
+      def always_loaded_tools
+        custom = Legion::Settings.dig(:mcp, :deferred_loading, :always_loaded)
+        custom.is_a?(Array) ? (ALWAYS_LOADED | custom) : ALWAYS_LOADED
+      end
+
+      def deferred?(tool_class)
+        return false unless enabled?
+
+        name = tool_class.respond_to?(:tool_name) ? tool_class.tool_name : tool_class.name
+        !always_loaded_tools.include?(name)
+      end
+
+      def deferred_entry(tool_class)
+        { name: tool_class.tool_name, description: tool_class.description }
+      end
+
+      def full_entry(tool_class)
+        tool_class.to_h
+      end
+
+      def build_tools_list(tool_classes)
+        tool_classes.map do |tc|
+          if deferred?(tc)
+            deferred_entry(tc)
+          else
+            full_entry(tc)
+          end
+        end
+      end
+
+      def resolve_schemas(tool_names, tool_classes)
+        tool_names.filter_map do |name|
+          tc = tool_classes.find { |klass| klass.tool_name == name }
+          next unless tc
+
+          tc.to_h
+        end
+      end
+    end
+  end
+end

data/lib/legion/mcp/dynamic_injector.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Legion
+  module MCP
+    module DynamicInjector
+      MAX_INJECTED = 10
+
+      module_function
+
+      def enabled?
+        Legion::Settings.dig(:mcp, :dynamic_tools, :enabled) == true
+      end
+
+      def max_injected
+        Legion::Settings.dig(:mcp, :dynamic_tools, :max_injected) || MAX_INJECTED
+      end
+
+      def context_tools(intent_string)
+        return [] unless enabled?
+        return [] if intent_string.nil? || intent_string.strip.empty?
+
+        matches = ContextCompiler.match_tools(intent_string, limit: max_injected)
+        return [] if matches.empty?
+
+        always = DeferredRegistry.always_loaded_tools
+        matches.filter_map do |match|
+          next if always.include?(match[:name])
+          next if match[:score] <= 0
+
+          Server.tool_registry.find { |tc| tc.tool_name == match[:name] }
+        end
+      end
+
+      def active_tool_set(intent_string)
+        always = always_loaded_classes
+        injected = context_tools(intent_string)
+        (always + injected).uniq(&:tool_name)
+      end
+
+      def always_loaded_classes
+        names = DeferredRegistry.always_loaded_tools
+        Server.tool_registry.select { |tc| names.include?(tc.tool_name) }
+      end
+
+      def tools_changed?(previous_names, current_names)
+        previous_names.sort != current_names.sort
+      end
+
+      def notify_if_changed(server, previous_names, current_names)
+        return unless tools_changed?(previous_names, current_names)
+        return unless server.respond_to?(:notify_tools_list_changed)
+
+        server.notify_tools_list_changed
+      rescue StandardError => e
+        Legion::Logging.debug("DynamicInjector: notify failed: #{e.message}") if defined?(Legion::Logging)
+      end
+
+      def inject_for_context(server, intent_string, previous_names: [])
+        return previous_names unless enabled?
+
+        tools = active_tool_set(intent_string)
+        current_names = tools.map(&:tool_name)
+
+        notify_if_changed(server, previous_names, current_names)
+        current_names
+      end
+    end
+  end
+end

data/lib/legion/mcp/server.rb

@@ -68,6 +68,16 @@ require_relative 'tools/query_knowledge'
 require_relative 'tools/knowledge_health'
 require_relative 'tools/knowledge_context'
 require_relative 'tools/absorb'
+require_relative 'tools/structural_index'
+require_relative 'tools/tool_audit'
+require_relative 'tools/state_diff'
+require_relative 'tools/search_sessions'
+require_relative 'structural_index'
+require_relative 'state_tracker'
+require_relative 'tool_quality'
+require_relative 'deferred_registry'
+require_relative 'catalog_dispatcher'
+require_relative 'dynamic_injector'
 require_relative 'catalog_bridge'
 require_relative 'resources/runner_catalog'
 require_relative 'resources/extension_info'
@@ -135,7 +145,11 @@ module Legion
         Tools::QueryKnowledge,
         Tools::KnowledgeHealth,
         Tools::KnowledgeContext,
-        Tools::Absorb
+        Tools::Absorb,
+        Tools::StructuralIndexTool,
+        Tools::ToolAudit,
+        Tools::StateDiff,
+        Tools::SearchSessions
       ].freeze
 
       @tool_registry = Concurrent::Array.new(STATIC_TOOLS)
@@ -189,21 +203,12 @@ module Legion
             end
           end
 
-          server.tools_list_handler do |_params|
-            build_filtered_tool_list.map(&:to_h)
-          end
+          install_deferred_tools_list_handler(server)
 
-          # Hydrate pattern store from L2 persistence (SQLite) on boot
           PatternStore.hydrate_from_l2 if defined?(PatternStore)
-
-          # Cold-start: load community patterns if store is still empty after hydration
           ColdStart.load_community_patterns if defined?(ColdStart)
-
-          # Discover and register runner functions before building the embedding index
-          # so all tools are present when embeddings are populated
           FunctionDiscovery.discover_and_register if defined?(Legion::Extensions)
-
-          # Populate embedding index for semantic tool matching (lazy — no-op if LLM unavailable)
+          register_catalog_tools
           populate_embedding_index
 
           Resources::RunnerCatalog.register(server)
@@ -262,6 +267,15 @@ module Legion
 
         private
 
+        def install_deferred_tools_list_handler(server)
+          handlers = server.instance_variable_get(:@handlers)
+          return unless handlers
+
+          handlers[::MCP::Methods::TOOLS_LIST] = lambda { |_request|
+            DeferredRegistry.build_tools_list(build_filtered_tool_list)
+          }
+        end
+
         def instructions
           <<~TEXT
             Legion is an async job engine. You can run tasks, create chains and relationships between services, manage extensions, and query system status.

data/lib/legion/mcp/settings.rb

@@ -13,10 +13,19 @@ module Legion
           connect_timeout: 10,
           call_timeout:    30,
           codegen:         { self_generate: self_generate_defaults },
-          mcp:             { auto_expose_runners: false }
+          mcp:             { auto_expose_runners: false, deferred_loading: deferred_loading_defaults,
+                             dynamic_tools: dynamic_tools_defaults }
         }
       end
 
+      def deferred_loading_defaults
+        { enabled: true, always_loaded: [] }
+      end
+
+      def dynamic_tools_defaults
+        { enabled: false, max_injected: 10 }
+      end
+
       def self_generate_defaults
         {
           enabled:            false,

data/lib/legion/mcp/state_tracker.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Legion
+  module MCP
+    module StateTracker
+      MAX_SNAPSHOTS = 50
+
+      module_function
+
+      def snapshot
+        state = collect_state
+        timestamp = Time.now.floor
+
+        snapshots_mutex.synchronize do
+          snapshots << { state: state, timestamp: timestamp }
+          snapshots.shift if snapshots.size > MAX_SNAPSHOTS
+        end
+
+        { state: state, timestamp: timestamp.iso8601 }
+      end
+
+      def diff(since:)
+        since_time = parse_time(since)
+        return { error: 'invalid timestamp' } unless since_time
+
+        baseline = find_baseline(since_time)
+        current = collect_state
+
+        if baseline.nil?
+          return { full_state: current, reason: 'no baseline found for given timestamp',
+                   timestamp: Time.now.iso8601 }
+        end
+
+        changes = compute_diff(baseline[:state], current)
+        { changes: changes, since: since_time.iso8601, timestamp: Time.now.iso8601 }
+      end
+
+      def collect_state
+        {
+          tool_count:     Server.tool_registry.size,
+          observer_stats: collect_observer_stats,
+          pattern_count:  collect_pattern_count,
+          extensions:     collect_extension_count
+        }
+      end
+
+      def collect_observer_stats
+        return {} unless defined?(Observer)
+
+        stats = Observer.stats
+        { total_calls: stats[:total_calls], tool_count: stats[:tool_count], failure_rate: stats[:failure_rate] }
+      rescue StandardError
+        {}
+      end
+
+      def collect_pattern_count
+        return 0 unless defined?(PatternStore)
+
+        PatternStore.respond_to?(:size) ? PatternStore.size : 0
+      rescue StandardError
+        0
+      end
+
+      def collect_extension_count
+        return 0 unless defined?(Legion::Extensions)
+
+        extensions = if Legion::Extensions.respond_to?(:extensions)
+                       Legion::Extensions.extensions
+                     else
+                       Legion::Extensions.instance_variable_get(:@extensions)
+                     end
+        extensions&.size || 0
+      rescue StandardError
+        0
+      end
+
+      def compute_diff(baseline, current)
+        changes = {}
+        all_keys = (baseline.keys | current.keys).uniq
+
+        all_keys.each do |key|
+          old_val = baseline[key]
+          new_val = current[key]
+
+          next if old_val == new_val
+
+          if old_val.is_a?(Hash) && new_val.is_a?(Hash)
+            nested = compute_diff(old_val, new_val)
+            changes[key] = nested unless nested.empty?
+          else
+            changes[key] = { before: old_val, after: new_val }
+          end
+        end
+
+        changes
+      end
+
+      def find_baseline(since_time)
+        snapshots_mutex.synchronize do
+          snapshots.reverse.find { |s| s[:timestamp] <= since_time }
+        end
+      end
+
+      def parse_time(value)
+        case value
+        when Time
+          value
+        when String
+          Time.parse(value)
+        when Numeric
+          Time.at(value)
+        end
+      rescue ArgumentError
+        nil
+      end
+
+      def snapshots
+        @snapshots ||= []
+      end
+
+      def snapshots_mutex
+        @snapshots_mutex ||= Mutex.new
+      end
+
+      def reset!
+        snapshots_mutex.synchronize { snapshots.clear }
+      end
+    end
+  end
+end

data/lib/legion/mcp/structural_index.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Legion
+  module MCP
+    module StructuralIndex
+      CACHE_PATH = File.expand_path('~/.legionio/cache/structural_index.json')
+
+      module_function
+
+      def build
+        {
+          extensions:   scan_extensions,
+          tools:        scan_tools,
+          generated_at: Time.now.iso8601
+        }
+      end
+
+      def scan_extensions
+        return [] unless defined?(Legion::Extensions)
+
+        extensions = if Legion::Extensions.respond_to?(:extensions)
+                       Legion::Extensions.extensions || []
+                     else
+                       Legion::Extensions.instance_variable_get(:@extensions) || []
+                     end
+
+        extensions.filter_map do |ext|
+          build_extension_entry(ext)
+        rescue StandardError => e
+          Legion::Logging.debug("StructuralIndex: skipping #{ext}: #{e.message}") if defined?(Legion::Logging)
+          nil
+        end
+      end
+
+      def build_extension_entry(ext)
+        runners = if ext.respond_to?(:runner_modules)
+                    ext.runner_modules.filter_map { |rm| build_runner_entry(rm) }
+                  else
+                    []
+                  end
+
+        actors = if ext.respond_to?(:actor_modules)
+                   ext.actor_modules.filter_map { |am| build_actor_entry(am) }
+                 else
+                   []
+                 end
+
+        name = ext.respond_to?(:extension_name) ? ext.extension_name : ext.class.name
+
+        {
+          name:    name,
+          runners: runners,
+          actors:  actors
+        }
+      end
+
+      def build_runner_entry(runner_mod)
+        settings = runner_mod.respond_to?(:settings) ? runner_mod.settings : {}
+        functions = settings.is_a?(Hash) ? (settings[:functions] || {}) : {}
+
+        {
+          name:      runner_mod.respond_to?(:name) ? runner_mod.name : runner_mod.to_s,
+          functions: functions.keys.map(&:to_s)
+        }
+      end
+
+      def build_actor_entry(actor_mod)
+        {
+          name: actor_mod.respond_to?(:name) ? actor_mod.name : actor_mod.to_s,
+          type: actor_mod.respond_to?(:actor_type) ? actor_mod.actor_type : 'unknown'
+        }
+      end
+
+      def scan_tools
+        Server.tool_registry.map do |tc|
+          {
+            name:        tc.tool_name,
+            description: tc.description,
+            catalog:     tc.respond_to?(:catalog_entry) && tc.catalog_entry ? true : false
+          }
+        end
+      end
+
+      def cached
+        return nil unless File.exist?(CACHE_PATH)
+
+        data = File.read(CACHE_PATH)
+        Legion::JSON.load(data)
+      rescue StandardError
+        nil
+      end
+
+      def save_cache(index = nil)
+        index ||= build
+        dir = File.dirname(CACHE_PATH)
+        FileUtils.mkdir_p(dir) unless File.directory?(dir)
+        File.write(CACHE_PATH, Legion::JSON.dump(index))
+        index
+      end
+
+      def invalidate_cache
+        FileUtils.rm_f(CACHE_PATH)
+      end
+
+      def load_or_build
+        cached || save_cache(build)
+      end
+
+      def filter(index, extension: nil, type: nil)
+        result = index.dup
+        result[:extensions] = result[:extensions]&.select { |e| e[:name]&.include?(extension) } || [] if extension
+        apply_type_filter(result, type) if type
+        result
+      end
+
+      def apply_type_filter(result, type)
+        case type
+        when 'tools'
+          result.delete(:extensions)
+        when 'extensions'
+          result.delete(:tools)
+        when 'runners'
+          result[:extensions]&.each { |e| e.delete(:actors) }
+          result.delete(:tools)
+        when 'actors'
+          result[:extensions]&.each { |e| e.delete(:runners) }
+          result.delete(:tools)
+        end
+      end
+    end
+  end
+end

data/lib/legion/mcp/tool_quality.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Legion
+  module MCP
+    module ToolQuality
+      MIN_DESCRIPTION_LENGTH = 20
+      MIN_PARAM_DESCRIPTION_LENGTH = 5
+
+      module_function
+
+      def audit_all
+        Server.tool_registry.map { |tc| audit_tool(tc) }
+      end
+
+      def audit_tool(tool_class)
+        issues = []
+        issues.concat(check_description(tool_class))
+        issues.concat(check_params(tool_class))
+
+        {
+          name:        tool_class.tool_name,
+          description: tool_class.description,
+          category:    resolve_category(tool_class),
+          issues:      issues,
+          quality:     issues.empty? ? :pass : :warn
+        }
+      end
+
+      def check_description(tool_class)
+        issues = []
+        desc = tool_class.description.to_s
+        issues << 'description missing' if desc.empty?
+        issues << "description too short (#{desc.length} chars, min #{MIN_DESCRIPTION_LENGTH})" if desc.length < MIN_DESCRIPTION_LENGTH
+        issues
+      end
+
+      def check_params(tool_class)
+        issues = []
+        raw_schema = tool_class.input_schema
+        schema = raw_schema.is_a?(Hash) ? raw_schema : raw_schema.to_h
+        properties = schema[:properties] || {}
+
+        properties.each do |param_name, meta|
+          meta_hash = meta.is_a?(Hash) ? meta : {}
+          desc = meta_hash[:description].to_s
+          issues << "param '#{param_name}' missing or short description" if desc.length < MIN_PARAM_DESCRIPTION_LENGTH
+        end
+
+        issues
+      end
+
+      def resolve_category(tool_class)
+        return tool_class.mcp_category.to_sym if tool_class.respond_to?(:mcp_category) && tool_class.mcp_category
+
+        ContextCompiler::CATEGORIES.each do |cat, config|
+          return cat if config[:tools].include?(tool_class.tool_name)
+        end
+
+        EXPANDED_CATEGORIES.each do |cat, config|
+          return cat if config[:tools].include?(tool_class.tool_name)
+        end
+
+        :uncategorized
+      end
+
+      def capability_matrix
+        Server.tool_registry.map do |tc|
+          raw_schema = tc.input_schema
+          schema = raw_schema.is_a?(Hash) ? raw_schema : raw_schema.to_h
+          properties = schema[:properties] || {}
+          required = schema[:required] || []
+
+          {
+            name:        tc.tool_name,
+            category:    resolve_category(tc),
+            param_count: properties.size,
+            required:    required.map(&:to_s),
+            reads:       reads?(tc),
+            writes:      writes?(tc),
+            catalog:     tc.respond_to?(:catalog_entry) && tc.catalog_entry
+          }
+        end
+      end
+
+      def reads?(tool_class)
+        name = tool_class.tool_name
+        name.start_with?('legion.list_', 'legion.get_', 'legion.show_') ||
+          name.include?('query') || name.include?('search') ||
+          name.include?('status') || name.include?('health') ||
+          name.include?('stats') || name.include?('describe')
+      end
+
+      def writes?(tool_class)
+        name = tool_class.tool_name
+        name.start_with?('legion.create_', 'legion.update_', 'legion.delete_') ||
+          name.start_with?('legion.enable_', 'legion.disable_') ||
+          name.include?('run') || name.include?('approve') ||
+          name.include?('propose') || name.include?('absorb') ||
+          name.include?('broadcast') || name.include?('notify')
+      end
+
+      def summary
+        results = audit_all
+        pass_count = results.count { |r| r[:quality] == :pass }
+        warn_count = results.count { |r| r[:quality] == :warn }
+        categories = results.group_by { |r| r[:category] }
+
+        {
+          total_tools: results.size,
+          passing:     pass_count,
+          warnings:    warn_count,
+          by_category: categories.transform_values(&:size),
+          issues:      results.select { |r| r[:quality] == :warn }
+        }
+      end
+
+      EXPANDED_CATEGORIES = {
+        knowledge:   {
+          tools:   %w[legion.query_knowledge legion.knowledge_health legion.knowledge_context legion.absorb],
+          summary: 'Knowledge base operations — query, health, context retrieval, content absorption.'
+        },
+        mesh:        {
+          tools:   %w[legion.ask_peer legion.list_peers legion.notify_peer legion.broadcast_peers legion.mesh_status],
+          summary: 'Agent mesh communication — peer queries, notifications, broadcasts, and mesh topology.'
+        },
+        mind_growth: {
+          tools:   %w[legion.mind_growth_status legion.mind_growth_propose legion.mind_growth_approve
+                      legion.mind_growth_build_queue legion.mind_growth_cognitive_profile legion.mind_growth_health],
+          summary: 'Cognitive growth — proposals, approvals, build queue, cognitive profiling, fitness scores.'
+        },
+        prompts:     {
+          tools:   %w[legion.prompt_list legion.prompt_show legion.prompt_run],
+          summary: 'Prompt template management — list, view, and render prompt templates.'
+        },
+        datasets:    {
+          tools:   %w[legion.dataset_list legion.dataset_show legion.experiment_results],
+          summary: 'Dataset and experiment browsing — list datasets, view rows, compare experiment results.'
+        },
+        evals:       {
+          tools:   %w[legion.eval_list legion.eval_run legion.eval_results],
+          summary: 'Evaluation management — list evaluators, run evaluations, view results.'
+        },
+        meta:        {
+          tools:   %w[legion.do legion.tools legion.plan_action legion.structural_index],
+          summary: 'Meta-tools — natural language routing, tool discovery, planning, structural index.'
+        }
+      }.freeze
+    end
+  end
+end

data/lib/legion/mcp/tools/discover_tools.rb

@@ -5,28 +5,37 @@ module Legion
     module Tools
       class DiscoverTools < ::MCP::Tool
         tool_name 'legion.tools'
-        description 'Discover available Legion tools by category or intent. Returns compressed definitions to reduce context.'
+        description 'Discover available Legion tools by category or intent. Returns compressed definitions to reduce context. ' \
+                    'Use tool_names with schema: true to load full schemas for deferred tools.'
 
         input_schema(
           properties: {
-            category: {
+            category:   {
               type:        'string',
               description: 'Tool category: tasks, chains, relationships, extensions, schedules, workers, rbac, status, describe'
             },
-            intent:   {
+            intent:     {
               type:        'string',
               description: 'Describe what you want to do and relevant tools will be ranked'
+            },
+            tool_names: {
+              type:        'array',
+              items:       { type: 'string' },
+              description: 'Specific tool names to retrieve full schemas for (e.g., ["legion.ask_peer", "legion.list_peers"])'
+            },
+            schema:     {
+              type:        'boolean',
+              description: 'When true with tool_names, returns full JSON schemas for the specified tools'
             }
           }
         )
 
         class << self
-          def call(category: nil, intent: nil)
-            if category
-              result = ContextCompiler.category_tools(category.to_sym)
-              return error_response("Unknown category: #{category}") if result.nil?
-
-              text_response(result)
+          def call(category: nil, intent: nil, tool_names: nil, schema: nil)
+            if tool_names && schema
+              resolve_schemas(tool_names)
+            elsif category
+              lookup_category(category)
             elsif intent
               results = ContextCompiler.match_tools(intent, limit: 5)
               text_response({ matched_tools: results })
@@ -40,6 +49,22 @@ module Legion
 
           private
 
+          def resolve_schemas(tool_names)
+            schemas = DeferredRegistry.resolve_schemas(tool_names, Server.tool_registry)
+            if schemas.empty?
+              error_response("No tools found matching: #{tool_names.join(', ')}")
+            else
+              text_response({ schemas: schemas })
+            end
+          end
+
+          def lookup_category(category)
+            result = ContextCompiler.category_tools(category.to_sym)
+            return error_response("Unknown category: #{category}") if result.nil?
+
+            text_response(result)
+          end
+
           def text_response(data)
             ::MCP::Tool::Response.new([{ type: 'text', text: Legion::JSON.dump(data) }])
           end

data/lib/legion/mcp/tools/search_sessions.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Legion
+  module MCP
+    module Tools
+      class SearchSessions < ::MCP::Tool
+        tool_name 'legion.search_sessions'
+        description 'Search across past conversation sessions by keyword or topic. Returns matching ' \
+                    'sessions with context snippets sorted by relevance.'
+
+        SESSIONS_DIR = File.expand_path('~/.legion/sessions')
+
+        input_schema(
+          properties: {
+            query: {
+              type:        'string',
+              description: 'Search query — keywords or topic to find in past sessions'
+            },
+            limit: {
+              type:        'integer',
+              description: 'Maximum number of results to return (default 5)'
+            }
+          },
+          required:   ['query']
+        )
+
+        class << self
+          def call(query:, limit: 5)
+            return error_response('query cannot be empty') if query.to_s.strip.empty?
+
+            results = search(query, limit: limit)
+            text_response({ query: query, results: results, total: results.size })
+          rescue StandardError => e
+            Legion::Logging.warn("SearchSessions#call failed: #{e.message}") if defined?(Legion::Logging)
+            error_response("Failed: #{e.message}")
+          end
+
+          private
+
+          def search(query, limit: 5)
+            sessions_dir = resolve_sessions_dir
+            return [] unless sessions_dir && Dir.exist?(sessions_dir)
+
+            pattern = query.downcase
+            matches = Dir.glob(File.join(sessions_dir, '*.json')).filter_map do |path|
+              match_session(path, pattern)
+            rescue StandardError
+              nil
+            end
+            matches.sort_by { |r| -r[:matches] }.first(limit)
+          end
+
+          def match_session(path, pattern)
+            data = Legion::JSON.load(File.read(path))
+            messages = data[:messages] || data['messages'] || []
+            matches = messages.count { |m| content_matches?(m, pattern) }
+            return nil if matches.zero?
+
+            first_match = messages.find { |m| content_matches?(m, pattern) }
+            context = extract_context(first_match, pattern)
+
+            {
+              session: data[:name] || data['name'] || File.basename(path, '.json'),
+              file:    File.basename(path),
+              matches: matches,
+              context: context
+            }
+          end
+
+          def content_matches?(message, pattern)
+            content = message[:content] || message['content']
+            content.to_s.downcase.include?(pattern)
+          end
+
+          def extract_context(message, pattern)
+            content = (message[:content] || message['content']).to_s
+            idx = content.downcase.index(pattern)
+            return content[0..200] unless idx
+
+            start = [idx - 50, 0].max
+            content[start, 200]
+          end
+
+          def resolve_sessions_dir
+            custom = Legion::Settings.dig(:chat, :sessions_dir) if defined?(Legion::Settings)
+            custom || SESSIONS_DIR
+          end
+
+          def text_response(data)
+            ::MCP::Tool::Response.new([{ type: 'text', text: Legion::JSON.dump(data) }])
+          end
+
+          def error_response(msg)
+            ::MCP::Tool::Response.new([{ type: 'text', text: Legion::JSON.dump({ error: msg }) }], error: true)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/mcp/tools/state_diff.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Legion
+  module MCP
+    module Tools
+      class StateDiff < ::MCP::Tool
+        tool_name 'legion.state_diff'
+        description 'Return only changed system state since a given timestamp. Token-efficient polling ' \
+                    'for agents monitoring system state without re-fetching everything.'
+
+        input_schema(
+          properties: {
+            since:    {
+              type:        'string',
+              description: 'ISO 8601 timestamp to diff against (e.g., "2026-03-31T12:00:00Z")'
+            },
+            snapshot: {
+              type:        'boolean',
+              description: 'When true, takes a state snapshot and returns it (use before polling with since:)'
+            }
+          }
+        )
+
+        class << self
+          def call(since: nil, snapshot: nil)
+            if snapshot
+              result = StateTracker.snapshot
+              text_response(result)
+            elsif since
+              result = StateTracker.diff(since: since)
+              text_response(result)
+            else
+              text_response(StateTracker.collect_state.merge(timestamp: Time.now.iso8601))
+            end
+          rescue StandardError => e
+            Legion::Logging.warn("StateDiff#call failed: #{e.message}") if defined?(Legion::Logging)
+            error_response("Failed: #{e.message}")
+          end
+
+          private
+
+          def text_response(data)
+            ::MCP::Tool::Response.new([{ type: 'text', text: Legion::JSON.dump(data) }])
+          end
+
+          def error_response(msg)
+            ::MCP::Tool::Response.new([{ type: 'text', text: Legion::JSON.dump({ error: msg }) }], error: true)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/mcp/tools/structural_index.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Legion
+  module MCP
+    module Tools
+      class StructuralIndexTool < ::MCP::Tool
+        tool_name 'legion.structural_index'
+        description 'Return the precomputed structural index of all extensions, runners, actors, and tools. ' \
+                    'Filter by extension name or type (tools, extensions, runners, actors).'
+
+        input_schema(
+          properties: {
+            extension: {
+              type:        'string',
+              description: 'Filter by extension name (partial match)'
+            },
+            type:      {
+              type:        'string',
+              description: 'Filter by type: tools, extensions, runners, actors',
+              enum:        %w[tools extensions runners actors]
+            },
+            refresh:   {
+              type:        'boolean',
+              description: 'Force rebuild of the index (ignores cache)'
+            }
+          }
+        )
+
+        class << self
+          def call(extension: nil, type: nil, refresh: nil)
+            index = if refresh
+                      StructuralIndex.save_cache(StructuralIndex.build)
+                    else
+                      StructuralIndex.load_or_build
+                    end
+
+            result = StructuralIndex.filter(index, extension: extension, type: type)
+            text_response(result)
+          rescue StandardError => e
+            Legion::Logging.warn("StructuralIndexTool#call failed: #{e.message}") if defined?(Legion::Logging)
+            error_response("Failed: #{e.message}")
+          end
+
+          private
+
+          def text_response(data)
+            ::MCP::Tool::Response.new([{ type: 'text', text: Legion::JSON.dump(data) }])
+          end
+
+          def error_response(msg)
+            ::MCP::Tool::Response.new([{ type: 'text', text: Legion::JSON.dump({ error: msg }) }], error: true)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/mcp/tools/tool_audit.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Legion
+  module MCP
+    module Tools
+      class ToolAudit < ::MCP::Tool
+        tool_name 'legion.tool_audit'
+        description 'Audit MCP tools for quality, categorization, and capability matrix. ' \
+                    'Returns issues, category assignments, and read/write capabilities.'
+
+        input_schema(
+          properties: {
+            mode: {
+              type:        'string',
+              description: 'Audit mode: summary (default), matrix (capability matrix), issues (quality issues only)',
+              enum:        %w[summary matrix issues]
+            }
+          }
+        )
+
+        class << self
+          def call(mode: 'summary')
+            result = case mode
+                     when 'matrix'
+                       ToolQuality.capability_matrix
+                     when 'issues'
+                       ToolQuality.audit_all.select { |r| r[:quality] == :warn }
+                     else
+                       ToolQuality.summary
+                     end
+
+            text_response(result)
+          rescue StandardError => e
+            Legion::Logging.warn("ToolAudit#call failed: #{e.message}") if defined?(Legion::Logging)
+            error_response("Failed: #{e.message}")
+          end
+
+          private
+
+          def text_response(data)
+            ::MCP::Tool::Response.new([{ type: 'text', text: Legion::JSON.dump(data) }])
+          end
+
+          def error_response(msg)
+            ::MCP::Tool::Response.new([{ type: 'text', text: Legion::JSON.dump({ error: msg }) }], error: true)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/mcp/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module MCP
-    VERSION = '0.6.6'
+    VERSION = '0.7.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-mcp
 version: !ruby/object:Gem::Version
-  version: 0.6.6
+  version: 0.7.0
 platform: ruby
 authors:
 - Esity
@@ -110,6 +110,7 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
+- AGENTS.md
 - CHANGELOG.md
 - CLAUDE.md
 - CODEOWNERS
@@ -122,6 +123,7 @@ files:
 - lib/legion/mcp/actors/self_generate_cycle.rb
 - lib/legion/mcp/auth.rb
 - lib/legion/mcp/catalog_bridge.rb
+- lib/legion/mcp/catalog_dispatcher.rb
 - lib/legion/mcp/client.rb
 - lib/legion/mcp/client/connection.rb
 - lib/legion/mcp/client/pool.rb
@@ -129,6 +131,8 @@ files:
 - lib/legion/mcp/cold_start.rb
 - lib/legion/mcp/context_compiler.rb
 - lib/legion/mcp/context_guard.rb
+- lib/legion/mcp/deferred_registry.rb
+- lib/legion/mcp/dynamic_injector.rb
 - lib/legion/mcp/embedding_index.rb
 - lib/legion/mcp/function_discovery.rb
 - lib/legion/mcp/gap_detector.rb
@@ -144,8 +148,11 @@ files:
 - lib/legion/mcp/self_generate.rb
 - lib/legion/mcp/server.rb
 - lib/legion/mcp/settings.rb
+- lib/legion/mcp/state_tracker.rb
+- lib/legion/mcp/structural_index.rb
 - lib/legion/mcp/tier_router.rb
 - lib/legion/mcp/tool_governance.rb
+- lib/legion/mcp/tool_quality.rb
 - lib/legion/mcp/tools/absorb.rb
 - lib/legion/mcp/tools/ask_peer.rb
 - lib/legion/mcp/tools/broadcast_peers.rb
@@ -199,8 +206,12 @@ files:
 - lib/legion/mcp/tools/rbac_grants.rb
 - lib/legion/mcp/tools/routing_stats.rb
 - lib/legion/mcp/tools/run_task.rb
+- lib/legion/mcp/tools/search_sessions.rb
 - lib/legion/mcp/tools/show_worker.rb
+- lib/legion/mcp/tools/state_diff.rb
+- lib/legion/mcp/tools/structural_index.rb
 - lib/legion/mcp/tools/team_summary.rb
+- lib/legion/mcp/tools/tool_audit.rb
 - lib/legion/mcp/tools/update_chain.rb
 - lib/legion/mcp/tools/update_relationship.rb
 - lib/legion/mcp/tools/update_schedule.rb