axn-mcp 0.1.0 → 0.2.2

data/lib/axn/mcp.rb

@@ -3,20 +3,113 @@
 require "date"
 require "axn"
 require "mcp"
+require "active_support/deprecation"
+require "active_support/isolated_execution_state"
 
 require_relative "mcp/version"
-require_relative "mcp/config"
-require_relative "mcp/serializer"
-require_relative "mcp/schema_builder"
-require_relative "mcp/field_declarations"
-require_relative "mcp/tool"
+Axn::Extensions.config.register_semantic_hint(:open_world, :closed_world)
 
 module Axn
   module MCP
-    class SchemaError < StandardError; end
+    extend Axn::Configurable
+    extend Axn::Tools::AdapterRoots
+    extend Axn::Tools::AdapterSerialization
+
+    config_namespace :mcp
+
+    # Base error for this gem, marked with core's `Axn::Error` boundary (PRO-2997) so a consumer's
+    # `rescue Axn::Error` catches it alongside axn core's errors and the other adapter gems'.
+    # `Axn::Error` is a marker module -- including it adds no ancestry. New gem errors subclass this.
+    class Error < StandardError
+      include Axn::Error
+    end
+
+    class SchemaError < Error; end
+
+    # `extend Axn::Tools::AdapterRoots` declares a validated `tool_roots` directory list (default
+    # []); the registry reads `Axn::MCP.config.tool_roots` for directory-based tool membership.
+    # Ship the shared `agent_tools` convention as the default root, so an Axn under `app/agent_tools/`
+    # is exposed as an MCP tool out of the box (no explicit `tool :mcp` needed) -- and, since
+    # axn-ruby_llm defaults to the same dir, the same tool is exposed over ruby_llm too.
+    # `tool_roots_default` re-declares the setting through core's own `setting` path -- overriding
+    # AdapterRoots' empty default while reusing its broad-path validation (which rejects widening a
+    # root to `app/`/`.`/`actions`/a `..` traversal), and validating EAGERLY here rather than at the
+    # registry's first read -- so an app's own assignment still wins and `config.reset!(:tool_roots)`
+    # returns to this default rather than core's `[]`.
+    tool_roots_default %w[agent_tools]
+
+    setting :present_as, default: :structured, one_of: %i[structured message], overridable: true
+
+    # When true, serializing a successful result's `exposes` values rejects any value that has no
+    # JSON rendering its author declared -- one that would otherwise ship as an opaque blob like
+    # `"#<User:0x...>"` (or, in Rails, ActiveSupport's generic instance-variable dump). The rejection
+    # raises during serialization; Invocation's guard turns that into an error response (and pages
+    # `on_exception`), so the tool call fails cleanly rather than shipping the blob. Default `false`:
+    # for an LLM tool result an ugly-but-honest string usually beats a failed call, so the opaque
+    # rendering ships. Applies ONLY to outbound `exposes` serialization, not to inbound argument
+    # handling. (Values with no *honest* JSON form -- cycles, non-finite Floats, non-UTF-8-encodable
+    # bytes, colliding Hash keys -- fail regardless of this flag; it governs only the extra "was this
+    # rendering author-declared?" check.)
+    declare_reject_opaque_exposed_values! default: false
 
-    def self.config
-      @config ||= Config.new
+    # Per-tool MCP metadata, declarable on the class via `configure(:mcp) { |c| c.title = "..." }`
+    # so it survives the zero-arg `Axn::MCP.tools` path (which calls `wrap` with no kwargs). Each
+    # defaults to nil -- left at `::MCP::Tool`'s own default unless set -- and an explicit `wrap`
+    # kwarg still wins over the configured value. Loosely typed (no validation here); `::MCP::Tool`
+    # validates the shapes when they're applied.
+    setting :title, default: nil, overridable: true
+    setting :icons, default: nil, overridable: true
+    setting :meta, default: nil, overridable: true
+    setting :annotations, default: nil, overridable: true
+
+    # Shared deprecator for this gem's own deprecated API (e.g. the legacy annotation
+    # bang-methods -- see lib/axn/mcp/tool.rb). A dedicated ActiveSupport::Deprecation instance,
+    # not the old global ActiveSupport::Deprecation.warn, so a consuming Rails app can register it
+    # (`Rails.application.deprecators[:axn_mcp] = Axn::MCP.deprecator`) and govern its behavior
+    # (silence in test, raise in CI, etc.) the same way it already does for its own deprecations.
+    def self.deprecator
+      @deprecator ||= ActiveSupport::Deprecation.new("1.0", "axn-mcp")
+    end
+
+    # The live MCP server context for the current wrapped-tool call -- an `MCP::ServerContext` over a
+    # real `MCP::Server`, or whatever raw value was passed as `server_context:` to a direct call --
+    # or `nil` outside a wrapped `#call`. This is the MCP-specific handle for transport *capabilities*
+    # (`Axn::MCP.server_context.report_progress(...)`, `.cancelled?`), which are not ambient data and
+    # don't survive `ambient_context`'s declared-key filtering. Ambient *data* still belongs in
+    # `ambient_context` (`expects :user_id, on: :ambient_context`), which `wrap` spreads from the same
+    # server_context and which stays adapter-agnostic. A tool reaching for this is knowingly
+    # MCP-coupled -- appropriate, since these operations are MCP-transport-only.
+    def self.server_context
+      ActiveSupport::IsolatedExecutionState[:__axn_mcp_server_context]
+    end
+
+    # Sets Axn::MCP.server_context for the duration of the block. Uses ActiveSupport's
+    # IsolatedExecutionState (thread- or fiber-scoped per the configured isolation_level), matching
+    # how axn core scopes its own per-execution state and CurrentAttributes -- so this stays correct
+    # under a Fiber scheduler rather than silently leaking across fibers a raw Thread-local would.
+    # Restores the previous value on the way out so nested wrapped calls compose.
+    def self.with_server_context(value)
+      previous = ActiveSupport::IsolatedExecutionState[:__axn_mcp_server_context]
+      ActiveSupport::IsolatedExecutionState[:__axn_mcp_server_context] = value
+      yield
+    ensure
+      ActiveSupport::IsolatedExecutionState[:__axn_mcp_server_context] = previous
     end
+
+    # Register :mcp with axn core's process-global tool registry, passing this module as the config
+    # source (PRO-2943/PRO-2944) so the registry reads `Axn::MCP.config.tool_roots` for
+    # directory-based membership. A consumer builds its server tool list from `Axn::MCP.tools`
+    # (`Axn::Tools.for(:mcp)`) -- resolving directory-root grants, an explicit `tool`/`tool :mcp`
+    # declaration, and implicit `configure(:mcp)` membership -- instead of a hand-maintained array.
+    Axn::Tools.register_adapter(:mcp, self)
   end
 end
+
+# Required after the module above extends Axn::Configurable, since Tool calls
+# Axn::MCP.overrides at class-definition time. (Setting declaration order is
+# free, but the extend must happen first.)
+require_relative "mcp/annotations"
+require_relative "mcp/serializer"
+require_relative "mcp/invocation"
+require_relative "mcp/tool"
+require_relative "mcp/wrap"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: axn-mcp
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.2
 platform: ruby
 authors:
 - Kali Donovan
@@ -15,7 +15,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.0.pre.alpha.4.3
+        version: 0.1.0.pre.alpha.6
     - - "<"
       - !ruby/object:Gem::Version
         version: 0.2.0
@@ -25,7 +25,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.0.pre.alpha.4.3
+        version: 0.1.0.pre.alpha.6
     - - "<"
       - !ruby/object:Gem::Version
         version: 0.2.0
@@ -35,20 +35,20 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: 0.5.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: 0.5.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '2.0'
 description: Build MCP tools using Axn's expects/exposes contract with auto-generated
   JSON schemas and responses.
 email:
@@ -60,15 +60,14 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
-- Rakefile
 - lib/axn-mcp.rb
 - lib/axn/mcp.rb
-- lib/axn/mcp/config.rb
-- lib/axn/mcp/field_declarations.rb
-- lib/axn/mcp/schema_builder.rb
+- lib/axn/mcp/annotations.rb
+- lib/axn/mcp/invocation.rb
 - lib/axn/mcp/serializer.rb
 - lib/axn/mcp/tool.rb
 - lib/axn/mcp/version.rb
+- lib/axn/mcp/wrap.rb
 homepage: https://github.com/teamshares/axn-mcp
 licenses:
 - MIT

data/Rakefile

@@ -1,13 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-require "rubocop/rake_task"
-
-RSpec::Core::RakeTask.new(:spec)
-
-RuboCop::RakeTask.new
-
-task default: %i[spec rubocop]
-
-Rake::Task["build"].enhance([:default])

data/lib/axn/mcp/config.rb

@@ -1,27 +0,0 @@
-# frozen_string_literal: true
-
-module Axn
-  module MCP
-    class Config
-      VALID_MCP_TEXT_CONTENT = %i[structured message].freeze
-
-      attr_reader :mcp_text_content
-
-      def initialize
-        @mcp_text_content = :structured
-      end
-
-      def mcp_text_content=(value)
-        self.class.validate_mcp_text_content!(value)
-        @mcp_text_content = value
-      end
-
-      def self.validate_mcp_text_content!(value)
-        return if VALID_MCP_TEXT_CONTENT.include?(value)
-
-        raise ArgumentError,
-              "mcp_text_content must be one of #{VALID_MCP_TEXT_CONTENT.map(&:inspect).join(", ")}; got #{value.inspect}"
-      end
-    end
-  end
-end

data/lib/axn/mcp/field_declarations.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-module Axn
-  module MCP
-    module FieldDeclarations
-      module_function
-
-      def hydrate(declarations)
-        return declarations if declarations.is_a?(Hash)
-
-        Array(declarations).each_with_object({}) do |item, acc|
-          if item.is_a?(Hash)
-            item.each { |k, v| acc[k] = v }
-          else
-            acc[item] = {}
-          end
-        end
-      end
-    end
-  end
-end

data/lib/axn/mcp/schema_builder.rb

@@ -1,224 +0,0 @@
-# frozen_string_literal: true
-
-require "date"
-
-module Axn
-  module MCP
-    module SchemaBuilder
-      TYPE_MAP = {
-        String => "string",
-        Integer => "integer",
-        Float => "number",
-        Numeric => "number",
-        Hash => "object",
-        Array => "array",
-        TrueClass => "boolean",
-        FalseClass => "boolean",
-        Date => "string",
-        DateTime => "string",
-        Time => "string",
-      }.freeze
-
-      FORMAT_MAP = {
-        Date => "date",
-        DateTime => "date-time",
-        Time => "date-time",
-      }.freeze
-
-      EXCLUDED_FROM_SCHEMA = %i[server_context].freeze
-
-      module_function
-
-      def build_input(field_configs, subfield_configs = [])
-        properties = {}
-        required = []
-
-        subfields_by_parent = subfield_configs.group_by(&:on)
-
-        field_configs.each do |config|
-          next if EXCLUDED_FROM_SCHEMA.include?(config.field)
-
-          if config.validations[:model]
-            build_model_property(config, properties, required)
-          else
-            prop = build_property(config)
-            nested_subfields = subfields_by_parent[config.field]
-            if nested_subfields&.any? && prop[:type] == "object"
-              prop[:properties] ||= {}
-              prop[:required] ||= []
-              nested_subfields.each do |subconfig|
-                subprop = build_property(subconfig)
-                prop[:properties][subconfig.field] = subprop
-                prop[:required] << subconfig.field.to_s unless optional?(subconfig)
-              end
-              prop[:required] = nil if prop[:required].empty?
-            end
-
-            properties[config.field] = prop.compact
-            required << config.field.to_s unless optional?(config)
-          end
-        end
-
-        schema = { type: "object", properties: }
-        schema[:required] = required unless required.empty?
-        schema
-      end
-
-      def build_output(field_configs)
-        properties = {}
-        required = []
-
-        field_configs.each do |config|
-          prop = build_property(config, for_output: true)
-          properties[config.field] = prop.compact
-          required << config.field.to_s unless optional?(config)
-        end
-
-        schema = { type: "object", properties: }
-        schema[:required] = required unless required.empty?
-        schema
-      end
-
-      def build_property(config, for_output: false)
-        prop = {}
-        prop[:description] = config.description if config.description
-
-        type_info = json_type_for(config.validations, for_output:)
-        prop[:type] = type_info[:type] if type_info[:type]
-        prop[:format] = type_info[:format] if type_info[:format]
-
-        prop[:default] = config.default if config.respond_to?(:default) && !config.default.nil?
-
-        if (inclusion = config.validations[:inclusion])
-          enum_values = inclusion[:in] || inclusion[:within] if inclusion.is_a?(Hash)
-          prop[:enum] = enum_values if enum_values
-        end
-
-        apply_structured_schema!(prop, config, for_output:)
-
-        prop
-      end
-
-      # Combine of: (bare element baseline) and shape: (typed member contracts) into
-      # items:/properties: schema. Precedence: shape: enriches/overrides of: baseline.
-      def apply_structured_schema!(prop, config, for_output:)
-        of    = config.validations[:of]
-        shape = config.validations[:shape]
-        return unless of || shape
-
-        if prop[:type] == "array"
-          items = of ? items_schema_for(of, for_output:) : {}
-          if shape
-            member_props, required = member_properties(shape[:members], for_output:)
-            base_props = items[:properties] || {}
-            items = items.merge(type: "object", properties: base_props.merge(member_props))
-            items[:required] = required unless required.empty?
-          end
-          prop[:items] = items unless items.empty?
-        elsif shape
-          # Hash / class field — shape: members are the object's own properties.
-          # If the field type is a Data.define subclass, use its members as the bare
-          # baseline so unannotated members still appear (same enrich logic as of:).
-          member_props, required = member_properties(shape[:members], for_output:)
-          type_klass = config.validations.dig(:type, :klass)
-          base_props = type_klass.is_a?(Class) && type_klass < Data ? type_klass.members.to_h { |m| [m, {}] } : {}
-          prop[:properties] = base_props.merge(member_props)
-          prop[:required] = required unless required.empty?
-        end
-      end
-
-      # Build a JSON Schema items: value from the of: validation hash.
-      def items_schema_for(of_validations, for_output: false)
-        klasses = Array(of_validations[:klass])
-        if klasses.size == 1
-          single_items_schema(klasses.first, for_output:)
-        else
-          { anyOf: klasses.map { |k| single_items_schema(k, for_output:) } }
-        end
-      end
-
-      def single_items_schema(klass, for_output: false)
-        if klass.is_a?(Class) && klass < Data
-          # Data.define subclass → object with named (but untyped) properties as baseline
-          { type: "object", properties: klass.members.to_h { |m| [m, {}] } }
-        else
-          json_type_for({ type: klass }, for_output:)
-        end
-      end
-
-      # Build properties/required from a shape: block's members. Recurses for nested shape/of.
-      def member_properties(members, for_output:)
-        props = {}
-        required = []
-        members.each do |m|
-          props[m.field] = build_property(m, for_output:).compact
-          required << m.field.to_s unless optional?(m)
-        end
-        [props, required]
-      end
-
-      def build_model_property(config, properties, required)
-        model_opts = config.validations[:model]
-        klass = model_opts[:klass]
-        klass_name = klass.is_a?(Class) ? klass.name : klass.to_s
-
-        id_field = :"#{config.field}_id"
-        prop = {
-          type: "integer",
-          description: config.description || "ID of the #{klass_name} record",
-        }
-
-        properties[id_field] = prop.compact
-        required << id_field.to_s unless optional?(config)
-      end
-
-      def json_type_for(validations, for_output: false)
-        if validations[:type]
-          type_opt = validations[:type]
-          klass = type_opt.is_a?(Hash) ? type_opt[:klass] : type_opt
-          klasses = Array(klass)
-
-          klass = klasses.first
-          return { type: "boolean" } if klass == :boolean
-          return { type: "string", format: "uuid" } if klass == :uuid
-
-          if TYPE_MAP.key?(klass)
-            result = { type: TYPE_MAP[klass] }
-            result[:format] = FORMAT_MAP[klass] if FORMAT_MAP.key?(klass)
-            return result
-          end
-
-          return { type: "object" } if for_output
-
-          return { type: "string" }
-        end
-
-        if validations[:inclusion]
-          inclusion = validations[:inclusion]
-          enum_values = inclusion[:in] || inclusion[:within] if inclusion.is_a?(Hash)
-          if enum_values&.any?
-            sample = enum_values.first
-            return { type: "string" } if sample.is_a?(String)
-            return { type: "integer" } if sample.is_a?(Integer)
-            return { type: "number" } if sample.is_a?(Float)
-          end
-        end
-
-        if validations[:numericality]
-          numericality = validations[:numericality]
-          return { type: "integer" } if numericality.is_a?(Hash) && numericality[:only_integer]
-
-          return { type: "number" }
-        end
-
-        return { type: "string" } if validations[:presence] || validations[:length]
-
-        {}
-      end
-
-      def optional?(config)
-        Axn::Internal::FieldConfig.optional?(config)
-      end
-    end
-  end
-end