legion-mcp 0.8.1 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dbc548bee22e23b6829490dcb7df334ae19c470f4f0d5d9148831b125083e323
-  data.tar.gz: 56bc136cb3b5801dce2d7fed3ba947ff9de1abd64c3dd996caa67cdffca49cd1
+  metadata.gz: 79ba0ac270a1e93bfb9558d37194307398336a43d759c7a9457daa28ca2e01a6
+  data.tar.gz: d97d87371fe9b4127d07a907abbd3b623015ce58be95425229eb17f9ad1885d6
 SHA512:
-  metadata.gz: 62db181395833185ab2e9b11b7ef3281a2e49761aab8d61feabce4fd19389fe768af86b26d0e24501ebb0ca2237ec87bd820ca18417b4eda3e77921fade69508
-  data.tar.gz: f5f1429b9cd74bcfaaf61083a38c5c5245644beee9e6ae3910ccb947f0f6809b8e9ef664bdce3d6a4ad3b9ec493788d92bb587c0d53bde7b75d7bed3b5a0fef0
+  metadata.gz: 633cef5680447266ec2276df835d4f571f3d3d7ece699c857e26cf2f2208d1823d655d2c9d8ecdf3a0431beaea0761d6c0fa0752fe92e134c7d82bede4f62c79
+  data.tar.gz: 66ccd7b86d37ecb681c1fe83dd719c2fff4daa45a6b67bf4c9cd8eef5d51aa444068d8cb6f4edf24bf7271cdadb6eced92cc91eccaabe4326c6bc92b8cef1b54

data/.gitignore

@@ -5,3 +5,4 @@ pkg/
 .bundle/
 vendor/
 .worktrees
+tmp/

data/CHANGELOG.md

@@ -1,5 +1,48 @@
 # legion-mcp Changelog
 
+## [0.9.1] - 2026-04-30
+
+### Fixed
+- `Audit.transport_connected?` rescue block now calls `handle_exception` at `:debug` level instead of silently swallowing the error
+- `ToolAdapter.dispatch_tool_instance` `rescue ArgumentError` (keyword-to-positional fallback) now calls `handle_exception` at `:debug` level
+- `SkillInvoke.invoke_skill` cleanup rescue now calls `handle_exception` at `:warn` level before re-raising
+- `Client::Connection.verify_connection!` rescue now calls `handle_exception` at `:error` level before re-raising as `ConnectionError`
+- `Client::Connection.fetch_tools` rescue now calls `handle_exception` at `:warn` level before re-raising as `ConnectionError`
+- `Client::Connection.execute_tool_call` `RequestHandlerError` rescue now calls `handle_exception` at `:warn` level before re-raising as `ConnectionError`
+
+### Changed
+- Added debug-level logging to `Client.register`, `Client.deregister`, `ServerRegistry.deregister`, and `ServerRegistry.mark_healthy` for full action traceability
+- Updated README.md to reflect 0.9.x architecture: DeferredRegistry, Client pool, Settings::Extensions integration, correct version, dependency floors, and file map
+
+## [0.9.0] - 2026-04-29
+
+### Removed
+- 38 hardcoded tool files that duplicated dynamic extension discovery (extensions, workers, RBAC, status, config, prompts, datasets, evals, mind-growth, knowledge, mesh, absorb) — these are now auto-discovered via `Settings::Extensions`
+- `LoggingSupport` module — replaced by direct `Legion::Logging::Helper` + `Utils` module
+
+### Changed
+- `FunctionDiscovery.discover_and_register` now prefers reading tools from `Legion::Settings::Extensions` (the centralized registry in `legion-settings`) when available and populated, falling back to existing `Legion::Tools::Discovery` and runner-module discovery paths for backward compatibility
+- `ToolAdapter.from_registry_entry` builds MCP tool classes from registry entry hashes; delegates to `from_legion_tool` when the entry contains a loaded tool class, otherwise builds a thin metadata-driven adapter
+- `ToolAdapter.build_from_metadata` handles `:mcp_remote` dispatch type by proxying calls through `MCP::Client::Pool` instead of dispatching to a local tool class
+- `Resources::RunnerCatalog#catalog_json` reads from `Settings::Extensions.runners` when available, falling back to the existing `legion-data` database query path
+- `tools_loader.rb` now requires only 8 MCP-specific and 18 legion-data CRUD tool files (down from 65)
+- All logging in server, catalog_dispatcher, observer, pattern_store, tier_router, do_action, and client/connection migrated from `LoggingSupport` to direct `log.*` calls with `Utils.format_fields`
+- Bumped `legion-settings` dependency floor to `>= 1.4.0` (requires `Settings::Extensions` module)
+
+### Added
+- `Utils` module (`lib/legion/mcp/utils.rb`) — pure-function summarization and formatting helpers extracted from `LoggingSupport`
+- `Client::Pool.refresh_tools!` — re-fetches and re-registers all remote server tools
+- `Client::Pool.all_tools` now registers each remote tool into `Settings::Extensions` with `dispatch_type: :mcp_remote`
+- `Server.register_mcp_tools_in_settings_extensions` — registers `MCP_SPECIFIC_TOOLS` into `Settings::Extensions` with `dispatch_type: :class_call` after build
+- `patterns.rb` barrel file — requires all 13 Tier 0 pattern routing modules
+- `discovery.rb` barrel file — requires all 12 tool discovery and adaptation modules
+- `FunctionDiscovery.settings_extensions_available?` — guard method checking if `Settings::Extensions` is defined and populated
+- `FunctionDiscovery.register_from_settings_extensions` — registers tools from the centralized registry into the MCP server
+- `ToolAdapter.from_registry_entry` — factory method to build MCP tools from registry entry hashes
+- `ToolAdapter.build_from_metadata` — builds thin MCP tool adapters from metadata when no tool class is loaded
+- `RunnerCatalog#settings_extensions_runners_available?` — guard for registry-based runner catalog
+- `RunnerCatalog#catalog_from_settings_extensions` — builds runner catalog JSON from the centralized registry
+
 ## [0.8.1] - 2026-04-14
 
 ### Fixed

data/CLAUDE.md

@@ -7,7 +7,7 @@
 Standalone gem providing the Model Context Protocol (MCP) server for LegionIO. Extracted from LegionIO to enable independent versioning and reuse. Includes semantic tool matching, observation pipeline, context compilation, tiered inference (Tier 0/1/2), and tool governance.
 
 **GitHub**: https://github.com/LegionIO/legion-mcp
-**Version**: 0.7.4
+**Version**: 0.9.0
 **License**: Apache-2.0
 **Ruby**: >= 3.4
 
@@ -15,29 +15,27 @@ Standalone gem providing the Model Context Protocol (MCP) server for LegionIO. E
 
 ```
 Legion::MCP
-├── Server              # MCP::Server builder, governance-aware build; tool list sourced from Legion::Tools::Registry via DeferredRegistry
+├── Server              # MCP::Server builder, governance-aware build; tool list sourced from Legion::Settings::Extensions via DeferredRegistry
 ├── Auth                # JWT + API key authentication
+├── Utils               # Pure-function summarization and formatting helpers (extracted from LoggingSupport)
 ├── ToolGovernance      # Risk-tier tool filtering + invocation audit
-├── ContextCompiler     # Keyword + semantic tool matching, blended scoring (60% semantic + 40% keyword)
-├── EmbeddingIndex      # Semantic tool matching; delegates embedding persistence to Tools::EmbeddingCache (L0-L4)
-├── Observer            # Instrumentation pipeline: counters, ring buffer, pattern promotion
-├── UsageFilter         # Frequency/recency/keyword scoring for dynamic tool filtering
-├── PatternStore        # 4-layer degrading storage (L0 memory, L1 cache, L2 local SQLite)
-├── TierRouter          # Confidence-gated tier selection (Tier 0/1/2)
-├── ContextGuard        # Staleness, rapid-fire, anomaly detection guards
-├── ToolAdapter         # Adapts Legion::Tools::Base subclasses to MCP SDK format (McpToolAdapter kept as alias)
-├── DeferredRegistry    # Reads deferred tools from Legion::Tools::Registry at request time
-├── Tools/              # MCP_SPECIFIC_TOOLS only (6 registered); remaining tool files exist but are not registered in Server.tool_registry — extension tools discovered via Legion::Tools::Discovery
+├── ToolAdapter         # Adapts Legion::Tools::Base to MCP SDK format; handles :mcp_remote dispatch
+├── DeferredRegistry    # Reads deferred/always-loaded tools from Legion::Settings::Extensions at request time
+├── Client::Pool        # Remote MCP server connections; registers tools into Settings::Extensions
+├── Client::Connection  # stdio and HTTP transport connections with TTL-cached tool lists
+├── Client::ServerRegistry # Static and dynamic server registration with health tracking
+├── patterns.rb         # Barrel: PatternStore, TierRouter, ContextGuard, Observer, etc. (13 modules)
+├── discovery.rb        # Barrel: FunctionDiscovery, ToolAdapter, ToolGovernance, etc. (12 modules)
+├── Tools/              # MCP_SPECIFIC_TOOLS (10) + legion-data CRUD tools (18); extension tools via Settings::Extensions
 └── Resources/          # RunnerCatalog, ExtensionInfo
 ```
 
-### Tool Registry Migration Notes
+### Tool Registry
 
-- **Before**: legion-mcp owned 57+ individual `Tools/*.rb` files registered in `TOOL_CLASSES`.
-- **After**: Tools discovered dynamically via `Legion::Tools::Discovery` from extension `runner_modules` at boot. `Legion::Tools::Registry` classifies each as `:always` or `:deferred`. `DeferredRegistry` resolves the deferred set at request time.
-- `MCP_SPECIFIC_TOOLS` (6 tools) covers MCP-only concerns not owned by any extension.
-- `CatalogBridge` removed — bridged old `Extensions::Capability` / `Catalog::Registry` which no longer exist.
-- `EmbeddingIndex` uses `Legion::Tools::EmbeddingCache` (5-tier L0–L4) instead of its own in-memory store.
+- **MCP_SPECIFIC_TOOLS** (10 tools): do_action, discover_tools, plan_action, structural_index, tool_audit, state_diff, search_sessions, skill_list, skill_describe, skill_invoke, skill_cancel
+- **legion-data CRUD** (18 tools): run_task, describe_runner, list/get/delete tasks, get_task_logs, CRUD chains/relationships/schedules
+- **Extension tools**: Auto-discovered via `Legion::Settings::Extensions` at runtime; not shipped as static files
+- **Remote MCP tools**: Fetched from remote servers via `Client::Pool.all_tools`, registered into `Settings::Extensions` with `dispatch_type: :mcp_remote`
 
 ## Dependencies
 
@@ -46,8 +44,8 @@ Legion::MCP
 | `mcp` (~> 0.8) | Yes | MCP server SDK |
 | `legion-data` (>= 1.4) | Yes | Sequel models, migrations |
 | `legion-json` (>= 1.2) | Yes | JSON serialization |
-| `legion-logging` (>= 0.3) | Yes | Logging |
-| `legion-settings` (>= 0.3) | Yes | Configuration |
+| `legion-logging` (>= 1.4.3) | Yes | Logging via Helper |
+| `legion-settings` (>= 1.4.0) | Yes | Configuration + Settings::Extensions |
 | `legion-cache` | Optional | L1 pattern cache (memcached/redis) |
 | `legion-llm` | Optional | Embeddings for semantic matching |
 | `legionio` | Dev only | Full framework for integration testing |
@@ -58,6 +56,7 @@ All optional dependencies use `defined?()` guards:
 - `defined?(Legion::Cache)` for L1 cache operations
 - `defined?(Legion::Data::Local)` for L2 SQLite persistence
 - `defined?(Legion::LLM)` for embedding generation
+- `defined?(Legion::Settings::Extensions)` for central tool registry
 - `defined?(Legion::MCP::EmbeddingIndex)` for semantic matching
 - `defined?(Legion::MCP::TierRouter)` for Tier 0 routing
 - Every storage write wraps in `begin/rescue => nil` -- failed persistence never blocks Tier 0
@@ -68,6 +67,7 @@ All optional dependencies use `defined?()` guards:
 - **Tier routing**: Tier 0 (>= 0.8 confidence, cached), Tier 1 (0.6-0.8, local/fleet), Tier 2 (< 0.6, cloud)
 - **Pattern promotion**: Observer records intent+tool pairs; after 3 successful observations, promotes to PatternStore with seeded confidence 0.5
 - **Context guards**: Staleness (1hr), rapid-fire (5 in 10min), anomaly (2 consecutive misses) prevent stale Tier 0
+- **Settings::Extensions integration**: MCP-specific tools register with `dispatch_type: :class_call`; remote MCP tools register with `dispatch_type: :mcp_remote`
 
 ## File Map
 
@@ -75,33 +75,25 @@ All optional dependencies use `defined?()` guards:
 |------|---------|
 | `lib/legion/mcp.rb` | Entry point: `Legion::MCP.server` singleton factory |
 | `lib/legion/mcp/version.rb` | `Legion::MCP::VERSION` constant |
-| `lib/legion/mcp/server.rb` | MCP::Server builder, governance-aware build; reads tools from Tools::Registry |
+| `lib/legion/mcp/utils.rb` | Pure-function summarization and formatting helpers |
+| `lib/legion/mcp/server.rb` | MCP::Server builder, governance-aware build; reads tools from Settings::Extensions |
 | `lib/legion/mcp/auth.rb` | JWT + API key authentication |
-| `lib/legion/mcp/tool_governance.rb` | Risk-tier tool filtering + invocation audit |
-| `lib/legion/mcp/context_compiler.rb` | Keyword + semantic tool matching (60/40 blend) |
-| `lib/legion/mcp/embedding_index.rb` | Semantic tool matching; delegates persistence to Legion::Tools::EmbeddingCache |
-| `lib/legion/mcp/observer.rb` | Instrumentation: counters, ring buffer, pattern promotion |
-| `lib/legion/mcp/usage_filter.rb` | Frequency/recency/keyword scoring for dynamic tool filtering |
-| `lib/legion/mcp/pattern_store.rb` | 4-layer degrading storage (L0/L1/L2) with thread-safe access |
-| `lib/legion/mcp/tier_router.rb` | Confidence-gated tier selection, tool chain execution |
-| `lib/legion/mcp/context_guard.rb` | Staleness, rapid-fire, anomaly detection |
-| `lib/legion/mcp/tool_adapter.rb` | MCP::ToolAdapter — wraps Legion::Tools::Base for MCP SDK (McpToolAdapter kept as alias) |
-| `lib/legion/mcp/deferred_registry.rb` | DeferredRegistry — reads deferred tools from Legion::Tools::Registry at request time |
-| `lib/legion/mcp/tools/` | All tool implementations; only MCP_SPECIFIC_TOOLS (6 tools) registered in Server.tool_registry — extension tools sourced via Legion::Tools::Discovery |
+| `lib/legion/mcp/patterns.rb` | Barrel file for 13 Tier 0 pattern routing modules |
+| `lib/legion/mcp/discovery.rb` | Barrel file for 12 tool discovery and adaptation modules |
+| `lib/legion/mcp/tool_adapter.rb` | MCP::ToolAdapter — wraps tools for MCP SDK; handles :mcp_remote dispatch |
+| `lib/legion/mcp/client.rb` | Client boot/shutdown, server registration |
+| `lib/legion/mcp/client/pool.rb` | Connection pool; all_tools registers into Settings::Extensions |
+| `lib/legion/mcp/client/connection.rb` | stdio/HTTP transport connections |
+| `lib/legion/mcp/client/server_registry.rb` | Server health tracking and registration |
 | `lib/legion/mcp/tools/do_action.rb` | Natural language intent routing with Tier 0 fast path |
 | `lib/legion/mcp/tools/discover_tools.rb` | Dynamic tool discovery with context |
 | `lib/legion/mcp/tools/run_task.rb` | Execute runner function via dot notation |
-| `lib/legion/mcp/tools/query_knowledge.rb` | Query Apollo knowledge store |
-| `lib/legion/mcp/tools/knowledge_health.rb` | Knowledge store health and quality report |
-| `lib/legion/mcp/tools/knowledge_context.rb` | Scoped RAG query (local/global/all) for current-task context |
-| `lib/legion/mcp/tools/eval_*.rb` | Evaluation management (list/run/results) |
-| `lib/legion/mcp/tools/experiment_results.rb` | A/B experiment result comparison |
-| `lib/legion/mcp/tools/dataset_*.rb` | Dataset browsing (list/show) |
-| `lib/legion/mcp/tools/prompt_*.rb` | Prompt template management (list/show/run) |
 | `lib/legion/mcp/tools/plan_action.rb` | Agentic planning with action decomposition |
-| `lib/legion/mcp/tools/ask_peer.rb` / `notify_peer.rb` / `broadcast_peers.rb` / `list_peers.rb` | Agent mesh communication |
-| `lib/legion/mcp/tools/mesh_status.rb` | Mesh topology status |
-| `lib/legion/mcp/tools/mind_growth_*.rb` | Mind growth tools (status/propose/approve/build_queue/cognitive_profile/health) |
+| `lib/legion/mcp/tools/skills.rb` | Skill list/describe/invoke/cancel tools |
+| `lib/legion/mcp/tools/structural_index.rb` | Query precomputed structural index |
+| `lib/legion/mcp/tools/tool_audit.rb` | Audit registered tools quality |
+| `lib/legion/mcp/tools/state_diff.rb` | Changed system state since timestamp |
+| `lib/legion/mcp/tools/search_sessions.rb` | Search past conversation sessions |
 | `lib/legion/mcp/resources/runner_catalog.rb` | `legion://runners` resource |
 | `lib/legion/mcp/resources/extension_info.rb` | `legion://extensions/{name}` resource template |
 

data/README.md

@@ -1,8 +1,10 @@
 # legion-mcp
 
-MCP (Model Context Protocol) server for the LegionIO framework. Provides semantic tool matching, observation pipeline, context compilation, and tiered behavioral intelligence (Tier 0/1/2 routing).
+Model Context Protocol (MCP) server for the LegionIO framework. Provides semantic tool matching, observation pipeline, context compilation, tiered behavioral intelligence (Tier 0/1/2 routing), tool governance, deferred tool loading, and MCP client pooling for remote server federation.
 
-**Version**: 0.6.1
+**Version**: 0.9.1
+**License**: Apache-2.0
+**Ruby**: >= 3.4
 
 Extracted from [LegionIO](https://github.com/LegionIO/LegionIO) for independent versioning and reuse.
 
@@ -15,27 +17,53 @@ gem 'legion-mcp'
 Or in a Gemfile:
 
 ```ruby
-gem 'legion-mcp', '~> 0.5'
+gem 'legion-mcp', '~> 0.9'
 ```
 
 ## Architecture
 
 ```
 Legion::MCP
-├── Server              # MCP::Server builder, TOOL_CLASSES registration
+├── Server              # MCP::Server builder, governance-aware build; tool list sourced via DeferredRegistry
 ├── Auth                # JWT + API key authentication
+├── Utils               # Pure-function summarization and formatting helpers
 ├── ToolGovernance      # Risk-tier tool filtering + invocation audit
-├── ContextCompiler     # Keyword + semantic tool matching (60/40 blend)
+├── ToolAdapter         # Adapts Legion::Tools::Base to MCP SDK format; handles :mcp_remote dispatch
+├── DeferredRegistry    # Reads deferred/always-loaded tools from Settings::Extensions at request time
+├── ContextCompiler     # Keyword + semantic tool matching (60/40 blend), 17 categories
 ├── EmbeddingIndex      # In-memory vector cache for semantic matching
-├── Observer            # Instrumentation: counters, ring buffer, pattern promotion
+├── Observer            # Instrumentation: counters, ring buffer, intent tracking, pattern promotion
 ├── UsageFilter         # Frequency/recency/keyword scoring for dynamic tool filtering
-├── PatternStore        # 4-layer degrading storage (L0 memory → L1 cache → L2 SQLite)
+├── DynamicInjector     # Context-aware tool injection/removal with tools/list_changed notification
+├── CatalogDispatcher   # Dispatch layer routing MCP calls through Legion::Ingress
+├── Patterns::Store     # 3-layer degrading storage (L0 memory -> L1 cache -> L2 SQLite)
+├── Patterns::Schema    # Portable pattern format with trust-level confidence capping
+├── Patterns::Exchange  # Bulk import/export of patterns via JSON files
+├── Patterns::Gossip    # AMQP-based pattern sharing between instances
+├── Patterns::Compiler  # Compressed tool definitions and compiled workflows
 ├── TierRouter          # Confidence-gated tier selection (0/1/2)
-├── ContextGuard        # Staleness, rapid-fire, anomaly detection
-├── Tools/              # 59 MCP::Tool subclasses (legion.* namespace)
+├── ContextGuard        # Staleness, rapid-fire, anomaly detection guards
+├── StateTracker        # In-memory state snapshots with delta diff computation
+├── StructuralIndex     # Precomputed index of extensions, runners, actors, and tools
+├── ToolQuality         # Docstring quality audit, category resolution, capability matrix
+├── GapDetector         # Unmatched intents, high-failure tools, stale candidate detection
+├── SelfGenerate        # Gap detection + publication cycles with cooldown
+├── OverrideBroadcast   # Mesh-wide override confirmation via RabbitMQ
+├── TracingContext       # Thread-local conversation/request/exchange/trace ID propagation
+├── Client::Pool        # Remote MCP server connections; registers tools into Settings::Extensions
+├── Client::Connection  # stdio and HTTP transport connections with TTL-cached tool lists
+├── Client::ServerRegistry # Static and dynamic server registration with health tracking
+├── Tools/              # 10 MCP-specific + 18 legion-data CRUD tools; extension tools via Settings::Extensions
 └── Resources/          # RunnerCatalog, ExtensionInfo
 ```
 
+### Tool Registry
+
+- **MCP_SPECIFIC_TOOLS** (10 tools): `do_action`, `discover_tools`, `plan_action`, `structural_index`, `tool_audit`, `state_diff`, `search_sessions`, `skill_list`, `skill_describe`, `skill_invoke`, `skill_cancel`
+- **legion-data CRUD** (18 tools): `run_task`, `describe_runner`, list/get/delete tasks, `get_task_logs`, CRUD chains/relationships/schedules
+- **Extension tools**: Auto-discovered via `Legion::Settings::Extensions` at runtime; not shipped as static files
+- **Remote MCP tools**: Fetched from remote servers via `Client::Pool.all_tools`, registered into `Settings::Extensions` with `dispatch_type: :mcp_remote`
+
 ## Tiered Behavioral Intelligence
 
 Requests flow through three tiers, each with increasing latency and capability:
@@ -65,7 +93,7 @@ If any guard triggers, the request escalates to Tier 1.
 
 ### Storage Layers
 
-PatternStore degrades gracefully across 4 layers:
+PatternStore degrades gracefully across 3 layers:
 
 | Layer | Backend | Requirement |
 |-------|---------|-------------|
@@ -73,40 +101,31 @@ PatternStore degrades gracefully across 4 layers:
 | L1 | Legion::Cache (memcached/redis) | `defined?(Legion::Cache)` |
 | L2 | Legion::Data::Local (SQLite) | `defined?(Legion::Data::Local)` |
 
-All persistence wraps in `begin/rescue => nil` — failed writes never block Tier 0.
+All persistence wraps in `begin/rescue => nil` -- failed writes never block Tier 0.
 
 ## Tools
 
-59 MCP tools in the `legion.*` namespace:
+28 built-in MCP tools in the `legion.*` namespace (10 MCP-specific + 18 legion-data CRUD). Extension-owned tools are auto-discovered at runtime via `Legion::Settings::Extensions`.
 
 | Tool | Purpose |
 |------|---------|
 | `legion.do` | Natural language intent routing (Tier 0 fast path) |
-| `legion.discover_tools` | Dynamic tool discovery with context |
+| `legion.tools` | Dynamic tool discovery by category, intent, or schema resolution |
+| `legion.plan` | Multi-step workflow planning with LLM narrative |
+| `legion.structural_index` | Precomputed structural index of extensions/runners/actors/tools |
+| `legion.tool_audit` | Quality audit of registered tools (summary/matrix/issues) |
+| `legion.state_diff` | Delta state polling since a given timestamp |
+| `legion.search_sessions` | Search past conversation sessions by keyword |
+| `legion.skill.list` | List all registered LLM skills |
+| `legion.skill.describe` | Describe a specific skill |
+| `legion.skill.invoke` | Invoke a skill for a conversation |
+| `legion.skill.cancel` | Cancel an active skill run |
 | `legion.run_task` | Execute a runner function via dot notation |
 | `legion.describe_runner` | Runner/function discovery |
-| `legion.list_tasks` / `get_task` / `delete_task` | Task CRUD |
-| `legion.get_task_logs` | Task execution logs |
+| `legion.list_tasks` / `get_task` / `delete_task` / `get_task_logs` | Task CRUD + logs |
 | `legion.list_chains` / `create_chain` / `update_chain` / `delete_chain` | Chain management |
-| `legion.list_relationships` / `create_relationship` / `update_relationship` / `delete_relationship` | Task relationships |
-| `legion.list_extensions` / `get_extension` / `enable_extension` / `disable_extension` | Extension management |
-| `legion.list_schedules` / `create_schedule` / `update_schedule` / `delete_schedule` | Schedule CRUD |
-| `legion.get_status` / `get_config` | System introspection |
-| `legion.list_workers` / `show_worker` / `worker_lifecycle` / `worker_costs` | Worker management |
-| `legion.team_summary` / `routing_stats` | Team and routing metrics |
-| `legion.rbac_assignments` / `rbac_check` / `rbac_grants` | Access control |
-| `legion.mind_growth_status` / `mind_growth_propose` / `mind_growth_approve` | Cognitive architecture growth |
-| `legion.mind_growth_build_queue` / `mind_growth_cognitive_profile` / `mind_growth_health` | Growth analysis and health |
-| `legion.query_knowledge` | Query Apollo knowledge store |
-| `legion.knowledge_health` | Knowledge store health and quality report |
-| `legion.knowledge_context` | Scoped RAG knowledge retrieval (local/global/all) |
-| `legion.eval_list` / `eval_run` / `eval_results` | Evaluation management |
-| `legion.experiment_results` | A/B experiment result comparison |
-| `legion.dataset_list` / `dataset_show` | Dataset browsing |
-| `legion.prompt_list` / `prompt_show` / `prompt_run` | Prompt template management |
-| `legion.plan_action` | Agentic planning with action decomposition |
-| `legion.ask_peer` / `notify_peer` / `broadcast_peers` / `list_peers` | Agent mesh communication |
-| `legion.mesh_status` | Mesh topology status |
+| `legion.list_relationships` / `create_*` / `update_*` / `delete_*` | Relationship CRUD |
+| `legion.list_schedules` / `create_*` / `update_*` / `delete_*` | Schedule CRUD |
 
 ## Resources
 
@@ -115,6 +134,24 @@ All persistence wraps in `begin/rescue => nil` — failed writes never block Tie
 | `legion://runners` | All registered extension.runner.function paths |
 | `legion://extensions/{name}` | Extension detail template |
 
+## MCP Client (Federation)
+
+Connect to remote MCP servers via stdio or HTTP transport:
+
+```ruby
+# Via settings (loaded at boot)
+# settings/mcp.json:
+# { "mcp": { "servers": { "code_server": { "transport": "stdio", "command": "npx @example/mcp-server" } } } }
+
+Legion::MCP::Client.boot
+
+# Or register at runtime
+Legion::MCP::Client.register(:my_server, transport: :http, url: 'http://localhost:9393/mcp')
+
+# All remote tools are registered into Settings::Extensions with dispatch_type: :mcp_remote
+tools = Legion::MCP::Client::Pool.all_tools
+```
+
 ## Usage
 
 ### Standalone MCP server
@@ -123,7 +160,6 @@ All persistence wraps in `begin/rescue => nil` — failed writes never block Tie
 require 'legion/mcp'
 
 server = Legion::MCP.server
-# Start via stdio transport
 server.start
 ```
 
@@ -153,6 +189,13 @@ when 2 then puts "Escalate to cloud LLM"
 end
 ```
 
+### Identity-scoped server
+
+```ruby
+server = Legion::MCP.server_for(token: jwt_token)
+# Returns governance-filtered tool set based on JWT claims
+```
+
 ## Configuration
 
 All configuration is optional and read via `Legion::Settings` when available:
@@ -160,12 +203,40 @@ All configuration is optional and read via `Legion::Settings` when available:
 ```json
 {
   "mcp": {
-    "context_guard": {
-      "max_stale_seconds": 3600,
-      "rapid_fire_threshold": 5,
-      "rapid_fire_window_secs": 600,
-      "anomaly_miss_threshold": 2
-    }
+    "auth": {
+      "enabled": false,
+      "require_auth": false,
+      "jwt_secret": null,
+      "jwt_algorithm": "HS256",
+      "jwt_issuer": "legion",
+      "allowed_api_keys": []
+    },
+    "governance": {
+      "enabled": false,
+      "audit_invocations": true,
+      "tool_risk_tiers": {}
+    },
+    "deferred_loading": {
+      "enabled": true,
+      "always_loaded": []
+    },
+    "dynamic_tools": {
+      "enabled": false,
+      "max_injected": 10
+    },
+    "tier0": {
+      "guards": {
+        "max_stale_seconds": 3600,
+        "rapid_fire_threshold": 5,
+        "rapid_fire_window_seconds": 600
+      }
+    },
+    "auto_expose_runners": false,
+    "servers": {},
+    "cold_start": {
+      "patterns_path": null
+    },
+    "roles": {}
   }
 }
 ```
@@ -177,10 +248,32 @@ All configuration is optional and read via `Legion::Settings` when available:
 | `mcp` (~> 0.8) | Yes | MCP server SDK |
 | `legion-data` (>= 1.4) | Yes | Sequel models, migrations |
 | `legion-json` (>= 1.2) | Yes | JSON serialization |
-| `legion-logging` (>= 0.3) | Yes | Logging |
-| `legion-settings` (>= 0.3) | Yes | Configuration |
-| `legion-cache` | Optional | L1 pattern cache |
-| `legion-llm` | Optional | Embeddings for semantic matching |
+| `legion-logging` (>= 1.4.3) | Yes | Structured logging via Helper |
+| `legion-settings` (>= 1.4.0) | Yes | Configuration + Settings::Extensions |
+| `legion-cache` | Optional | L1 pattern cache (memcached/redis) |
+| `legion-llm` | Optional | Embeddings for semantic matching, Tier 1/2 LLM |
+
+## Guard Strategy
+
+All optional dependencies use `defined?()` guards:
+- `defined?(Legion::Cache)` for L1 cache operations
+- `defined?(Legion::Data::Local)` for L2 SQLite persistence
+- `defined?(Legion::LLM)` for embedding generation and tiered LLM routing
+- `defined?(Legion::Settings::Extensions)` for central tool registry
+- `defined?(Legion::MCP::EmbeddingIndex)` for semantic matching
+- `defined?(Legion::MCP::TierRouter)` for Tier 0 routing
+
+Every storage write wraps in `begin/rescue => nil` -- failed persistence never blocks Tier 0.
+
+## Key Conventions
+
+- `Legion::JSON.load` returns **symbol keys** -- use `body[:data]`, not `body['data']`
+- `Legion::JSON.dump` takes exactly 1 positional arg -- wrap kwargs in explicit `{}`
+- `::Process` and `::JSON` must be explicit inside the `Legion::` namespace
+- `Legion::MCP.server` is a memoized singleton -- call `Legion::MCP.reset!` in tests
+- MCP tool naming: `legion.snake_case_name` (dot namespace)
+- Every rescue block calls `handle_exception(e, level:, handled:, operation:)`
+- Logging via `extend Legion::Logging::Helper` (modules) or `include Legion::Logging::Helper` (classes/class << self)
 
 ## Development
 
@@ -191,6 +284,37 @@ bundle exec rubocop -A  # auto-fix
 bundle exec rubocop     # lint check
 ```
 
+## File Map
+
+| Path | Purpose |
+|------|---------|
+| `lib/legion/mcp.rb` | Entry point: `Legion::MCP.server` singleton factory |
+| `lib/legion/mcp/version.rb` | `Legion::MCP::VERSION` constant |
+| `lib/legion/mcp/utils.rb` | Pure-function summarization and formatting helpers |
+| `lib/legion/mcp/server.rb` | MCP::Server builder, governance-aware build; reads tools from Settings::Extensions |
+| `lib/legion/mcp/auth.rb` | JWT + API key authentication |
+| `lib/legion/mcp/patterns.rb` | Barrel file for 13 Tier 0 pattern routing modules |
+| `lib/legion/mcp/discovery.rb` | Barrel file for 12 tool discovery and adaptation modules |
+| `lib/legion/mcp/tool_adapter.rb` | MCP::ToolAdapter -- wraps tools for MCP SDK; handles :mcp_remote dispatch |
+| `lib/legion/mcp/deferred_registry.rb` | Deferred/always-loaded tool list management |
+| `lib/legion/mcp/catalog_dispatcher.rb` | Dispatch layer routing through Legion::Ingress |
+| `lib/legion/mcp/dynamic_injector.rb` | Context-aware tool injection/removal |
+| `lib/legion/mcp/client.rb` | Client boot/shutdown, server registration |
+| `lib/legion/mcp/client/pool.rb` | Connection pool; all_tools registers into Settings::Extensions |
+| `lib/legion/mcp/client/connection.rb` | stdio/HTTP transport connections |
+| `lib/legion/mcp/client/server_registry.rb` | Server health tracking and registration |
+| `lib/legion/mcp/tools/do_action.rb` | Natural language intent routing with Tier 0 fast path |
+| `lib/legion/mcp/tools/discover_tools.rb` | Dynamic tool discovery with context |
+| `lib/legion/mcp/tools/run_task.rb` | Execute runner function via dot notation |
+| `lib/legion/mcp/tools/plan_action.rb` | Agentic planning with action decomposition |
+| `lib/legion/mcp/tools/skills.rb` | Skill list/describe/invoke/cancel tools |
+| `lib/legion/mcp/tools/structural_index.rb` | Query precomputed structural index |
+| `lib/legion/mcp/tools/tool_audit.rb` | Audit registered tools quality |
+| `lib/legion/mcp/tools/state_diff.rb` | Changed system state since timestamp |
+| `lib/legion/mcp/tools/search_sessions.rb` | Search past conversation sessions |
+| `lib/legion/mcp/resources/runner_catalog.rb` | `legion://runners` resource |
+| `lib/legion/mcp/resources/extension_info.rb` | `legion://extensions/{name}` resource template |
+
 ## License
 
 Apache-2.0

data/legion-mcp.gemspec

@@ -30,6 +30,6 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'legion-data', '>= 1.4.19'
   spec.add_dependency 'legion-json', '>= 1.2.0'
   spec.add_dependency 'legion-logging', '>= 1.4.3'
-  spec.add_dependency 'legion-settings', '>= 1.3.12'
+  spec.add_dependency 'legion-settings', '>= 1.4.0'
   spec.add_dependency 'mcp', '~> 0.8'
 end

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

@@ -14,14 +14,13 @@ module Legion
         def generate_task?  = false
 
         def time
-          if defined?(Legion::Settings) && !Legion::Settings[:codegen].nil?
-            Legion::Settings.dig(:codegen, :self_generate, :cycle_interval) || 300
-          else
+          if Legion::Settings[:codegen].nil?
             300
+          else
+            Legion::Settings.dig(:codegen, :self_generate, :cycle_interval) || 300
           end
         rescue StandardError => e
           handle_exception(e, level: :warn, operation: 'legion.mcp.actors.self_generate_cycle.time')
-          log.warn(e.message)
           300
         end
 
@@ -29,7 +28,6 @@ module Legion
           SelfGenerate.enabled?
         rescue StandardError => e
           handle_exception(e, level: :warn, operation: 'legion.mcp.actors.self_generate_cycle.enabled?')
-          log.warn(e.message)
           false
         end
 

data/lib/legion/mcp/audit.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Legion
+  module MCP
+    module Audit
+      extend Legion::Logging::Helper
+
+      ROUTING_KEYS = {
+        tool_call:   'mcp.audit.tool_call',
+        client_call: 'mcp.audit.client_call',
+        governance:  'mcp.audit.governance'
+      }.freeze
+
+      module_function
+
+      def emit_tool_call(**event)
+        publish(ROUTING_KEYS[:tool_call], event, :ToolCallEvent)
+      end
+
+      def emit_client_call(**event)
+        publish(ROUTING_KEYS[:client_call], event, :ClientCallEvent)
+      end
+
+      def emit_governance(**event)
+        publish(ROUTING_KEYS[:governance], event, :GovernanceEvent)
+      end
+
+      def transport_available?
+        !!(defined?(Legion::Transport::Message) &&
+           defined?(Legion::MCP::Transport::Exchanges::Audit))
+      end
+
+      def transport_connected?
+        Legion::Settings.dig(:transport, :connected) == true
+      rescue StandardError => e
+        handle_exception(e, level: :debug, handled: true, operation: 'mcp.audit.transport_connected?')
+        false
+      end
+
+      def publish(routing_key, event, message_sym)
+        return unless transport_available? && transport_connected?
+
+        message_class = Legion::MCP::Transport::Messages.const_get(message_sym)
+        message_class.new(routing_key: routing_key, **event).publish
+      rescue StandardError => e
+        handle_exception(e, level: :warn, handled: true, operation: 'mcp.audit.publish')
+      end
+    end
+  end
+end