legion-mcp 0.6.3 → 0.6.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bfce8f2adcb9e23e5ed0f4cbeef3cd1b9652b9e75e8ed9220ecbed03cd062a3b
-  data.tar.gz: 1ea9a7387eed8be7ea87adee85017837306bca5abd41fdf546c3452e8e196ea3
+  metadata.gz: 4a7b64b46eca9c059cbfa5fd95b354479914f48f22ecf109900cd3494a044ff3
+  data.tar.gz: 1877e520d1c814e6006247d1ff2745633aa866a13233829aa9a7b61a1082c87e
 SHA512:
-  metadata.gz: b8aa048bf6f665695e4588b31018ea849903a004149b56d0bd0032194c1cd474dc2086c2bb934205fbf85116ff90e58f6bfec9d8c524b270c4624c0607b56b0e
-  data.tar.gz: 47bd47cf386c0b89ddc415abbf36aa5554ddad5cdd6165a937750f2307e46e19bda219bffda2bd9ce4faa6fd5be3db50b284f66b885684cc9e1c4c15e98534c6
+  metadata.gz: 4c616de66d0815a7fbfbbeebd1d3a803fa22e9f96a23aabdf5645b3abf0e59390473b0f773daf37a9abb412ff111d451b8fba207950606856e0aa661c7b859c7
+  data.tar.gz: b019a72aec60a83fdb7a0a7c13ef688166cca65ddebdb5e644e63c45da1501c31a6743569bf96de97e88e66184231e1894fa404453570bc70f8372fcb43063e8

data/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [0.6.4] - 2026-03-28
+
+### Changed
+- `FunctionDiscovery`: prefer `definition[:mcp_exposed]` over deprecated `expose_as_mcp_tool` class method; fall back to legacy path when definition is absent
+- `FunctionDiscovery#build_tool_class`: stores `mcp_category` and `mcp_tier` as singleton methods on dynamically built tool classes so downstream consumers can read them
+- `ContextCompiler#compressed_catalog` and `#category_tools` now call `merged_categories`, which supplements the `CATEGORIES` constant with any tool classes that declare `mcp_category:` via the definition DSL
+- `ToolGovernance#filter_tools`: prefers definition-level `mcp_tier` singleton method on the tool class over `DEFAULT_TOOL_TIERS` fallback; `DEFAULT_TOOL_TIERS` and `custom_tiers` (Settings) remain as fallbacks
+- `FunctionDiscovery#register_function` refactored into `resolve_exposed` + `build_tool_opts` helpers to reduce perceived complexity
+
+### Added
+- `FunctionDiscovery#definition_for` — reads `runner_module.definition_for(method)` if available, returns nil otherwise
+- `FunctionDiscovery#should_expose_from_definition?` — exposure check that treats `definition[:mcp_exposed]` as highest precedence
+- `FunctionDiscovery#build_tool_opts` — builds the options hash passed to `build_tool_class`
+- `FunctionDiscovery#wire_call_method` — wires the `call` singleton method onto the built tool class
+- `ContextCompiler#merged_categories` — merges `CATEGORIES` with definition-declared categories from registered tool classes
+- `ToolGovernance#definition_tier` — extracts `mcp_tier` from a tool class singleton method (returns nil when absent)
+
 ## [0.6.3] - 2026-03-27
 
 ### Added

data/lib/legion/mcp/context_compiler.rb

@@ -49,9 +49,12 @@ module Legion
       module_function
 
       # Returns a compressed summary of all categories with tool counts and tool name lists.
+      # Merges CATEGORIES (hardcoded fallback) with any categories declared via the definition DSL
+      # (mcp_category: on dynamically discovered tool classes).
       # @return [Array<Hash>] array of { category:, summary:, tool_count:, tools: }
       def compressed_catalog
-        CATEGORIES.map do |category, config|
+        merged = merged_categories
+        merged.map do |category, config|
           tool_names = config[:tools]
           {
             category:   category,
@@ -63,10 +66,11 @@ module Legion
       end
 
       # Returns tools for a specific category, filtered to only those present in Server.tool_registry.
-      # @param category_sym [Symbol] one of the CATEGORIES keys
+      # Checks CATEGORIES (hardcoded fallback) as well as definition-declared mcp_category on tool classes.
+      # @param category_sym [Symbol] one of the CATEGORIES keys (or a definition-declared category)
       # @return [Hash, nil] { category:, summary:, tools: [{ name:, description:, params: }] } or nil
       def category_tools(category_sym)
-        config = CATEGORIES[category_sym]
+        config = merged_categories[category_sym]
         return nil unless config
 
         index = tool_index
@@ -80,6 +84,28 @@ module Legion
         }
       end
 
+      # Builds a merged category map: CATEGORIES constant as fallback, augmented by tool classes
+      # that declare mcp_category: via the definition DSL.
+      # @return [Hash<Symbol, Hash>] { category_sym => { tools: [...], summary: '...' } }
+      def merged_categories
+        result = CATEGORIES.transform_values do |config|
+          { tools: config[:tools].dup, summary: config[:summary] }
+        end
+
+        Server.tool_registry.each do |klass|
+          next unless klass.respond_to?(:mcp_category) && klass.mcp_category
+
+          cat = klass.mcp_category.to_sym
+          if result.key?(cat)
+            result[cat][:tools] |= [klass.tool_name]
+          else
+            result[cat] = { tools: [klass.tool_name], summary: cat.to_s.tr('_', ' ').capitalize }
+          end
+        end
+
+        result
+      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_registry or nil

data/lib/legion/mcp/function_discovery.rb

@@ -34,6 +34,7 @@ module Legion
       end
 
       def runner_expose_opts(runner_module)
+        # @deprecated class_expose/prefix — prefer definition DSL (mcp_exposed:, mcp_tool_prefix:)
         class_expose = runner_module.respond_to?(:expose_as_mcp_tool) ? runner_module.expose_as_mcp_tool : nil
         global_expose = defined?(Legion::Settings) ? (Legion::Settings.dig(:mcp, :auto_expose_runners) || false) : false
         prefix = runner_module.respond_to?(:mcp_tool_prefix) ? runner_module.mcp_tool_prefix : nil
@@ -41,18 +42,50 @@ module Legion
       end
 
       def register_function(runner_module, func_name, meta, opts)
-        return unless should_expose?(meta, opts[:class_expose], opts[:global_expose])
-        return unless deps_satisfied?(meta[:requires])
+        defn = definition_for(runner_module, func_name)
+        return unless resolve_exposed(defn, meta, opts)
 
-        tool_class = build_tool_class(
-          name:          derive_tool_name(func_name, opts[:prefix]),
-          description:   meta[:desc] || "Auto-discovered: #{func_name}",
+        requires = defn&.dig(:requires)&.map(&:to_s) || meta[:requires]
+        return unless deps_satisfied?(requires)
+
+        Server.register_tool(build_tool_class(build_tool_opts(runner_module, func_name, meta, opts, defn)))
+      end
+
+      def resolve_exposed(defn, meta, opts)
+        if defn.nil?
+          should_expose?(meta, opts[:class_expose], opts[:global_expose])
+        else
+          should_expose_from_definition?(defn, meta, opts[:class_expose], opts[:global_expose])
+        end
+      end
+
+      def build_tool_opts(runner_module, func_name, meta, opts, defn)
+        prefix = defn&.dig(:mcp_prefix) || opts[:prefix]
+        {
+          name:          derive_tool_name(func_name, prefix),
+          description:   meta[:desc] || defn&.dig(:desc) || "Auto-discovered: #{func_name}",
           input_schema:  meta[:options] || { properties: {} },
           runner_module: runner_module,
-          function_name: func_name
-        )
+          function_name: func_name,
+          mcp_category:  defn&.dig(:mcp_category),
+          mcp_tier:      defn&.dig(:mcp_tier)
+        }
+      end
+
+      # Returns the definition hash for a method on a runner module, or nil if not available.
+      def definition_for(runner_module, func_name)
+        return nil unless runner_module.respond_to?(:definition_for)
+
+        runner_module.definition_for(func_name)
+      end
+
+      # Exposure check when a definition is present.
+      # definition[:mcp_exposed] takes highest precedence; falls back to legacy path.
+      def should_expose_from_definition?(defn, func_meta, class_level, global_default)
+        mcp_exposed = defn[:mcp_exposed]
+        return mcp_exposed unless mcp_exposed.nil?
 
-        Server.register_tool(tool_class)
+        should_expose?(func_meta, class_level, global_default)
       end
 
       def should_expose?(func_meta, class_level, global_default)
@@ -84,34 +117,42 @@ module Legion
         end
       end
 
-      def build_tool_class(name:, description:, input_schema:, runner_module:, function_name:)
-        runner_ref = runner_module
-        func_ref = function_name
-
-        Class.new(::MCP::Tool) do
-          tool_name name
-          description description
-          input_schema(input_schema)
-
-          define_singleton_method(:call) do |**params|
-            error = false
-
-            result =
-              if runner_ref.respond_to?(func_ref)
-                begin
-                  runner_ref.public_send(func_ref, **params)
-                rescue StandardError => e
-                  error = true
-                  { error: e.message }
-                end
-              else
+      def build_tool_class(opts)
+        runner_ref         = opts[:runner_module]
+        func_ref           = opts[:function_name]
+        tool_name_value    = opts[:name]
+        description_value  = opts[:description]
+        input_schema_value = opts[:input_schema]
+        mcp_category_value = opts[:mcp_category]
+        mcp_tier_value     = opts[:mcp_tier]
+        klass = Class.new(::MCP::Tool) do
+          tool_name tool_name_value
+          description description_value
+          input_schema(input_schema_value)
+          define_singleton_method(:mcp_category) { mcp_category_value }
+          define_singleton_method(:mcp_tier)     { mcp_tier_value }
+        end
+        wire_call_method(klass, runner_ref, func_ref)
+        klass
+      end
+
+      def wire_call_method(klass, runner_ref, func_ref)
+        klass.define_singleton_method(:call) do |**params|
+          error = false
+          result =
+            if runner_ref.respond_to?(func_ref)
+              begin
+                runner_ref.public_send(func_ref, **params)
+              rescue StandardError => e
                 error = true
-                { error: "function #{func_ref} not found" }
+                { error: e.message }
               end
-
-            text = defined?(Legion::JSON) ? Legion::JSON.dump(result) : result.to_s
-            ::MCP::Tool::Response.new([{ type: 'text', text: text }], error: error)
-          end
+            else
+              error = true
+              { error: "function #{func_ref} not found" }
+            end
+          text = defined?(Legion::JSON) ? Legion::JSON.dump(result) : result.to_s
+          ::MCP::Tool::Response.new([{ type: 'text', text: text }], error: error)
         end
       end
     end

data/lib/legion/mcp/tool_governance.rb

@@ -32,9 +32,11 @@ module Legion
         risk_tier = identity&.dig(:risk_tier) || :low
         tier_value = RISK_TIER_ORDER[risk_tier] || 0
 
-        tool_tiers = DEFAULT_TOOL_TIERS.merge(custom_tiers)
+        # DEFAULT_TOOL_TIERS is the fallback; custom_tiers (from Settings) override it;
+        # definition-level mcp_tier on the tool class takes highest precedence.
+        fallback_tiers = DEFAULT_TOOL_TIERS.merge(custom_tiers)
         tools.select do |tool|
-          tool_tier = tool_tiers[tool_name(tool)] || :low
+          tool_tier = definition_tier(tool) || fallback_tiers[tool_name(tool)] || :low
           (RISK_TIER_ORDER[tool_tier] || 0) <= tier_value
         end
       end
@@ -72,6 +74,20 @@ module Legion
           tool.to_s
         end
       end
+
+      # Returns the mcp_tier declared on the tool class via the definition DSL, or nil if absent.
+      # Tool classes built by FunctionDiscovery expose mcp_tier as a singleton method.
+      def definition_tier(tool)
+        return nil unless tool.respond_to?(:mcp_tier)
+
+        tier = tool.mcp_tier
+        return nil if tier.nil?
+
+        normalized = tier.to_s.downcase.to_sym
+        return nil unless RISK_TIER_ORDER.key?(normalized)
+
+        normalized
+      end
     end
   end
 end

data/lib/legion/mcp/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module MCP
-    VERSION = '0.6.3'
+    VERSION = '0.6.4'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-mcp
 version: !ruby/object:Gem::Version
-  version: 0.6.3
+  version: 0.6.4
 platform: ruby
 authors:
 - Esity