axn-mcp 0.1.0 → 0.2.2

data/lib/axn/mcp/annotations.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Axn
+  module MCP
+    # Maps axn core's `semantic_hints` vocabulary (plus the MCP-only extensions this adapter
+    # registers below) to MCP tool annotation kwargs. Registering :open_world/:closed_world via
+    # Axn::Extensions.config.register_semantic_hint is the poster-child use of PRO-2842's registry:
+    # no core change was needed to add MCP-spec-only vocabulary.
+    module Annotations
+      # read_only also asserts destructive_hint: false: MCP::Tool::Annotations defaults
+      # destructive_hint to true, so without this a read_only tool would be advertised as BOTH
+      # read-only and destructive -- the same contradiction the legacy read_only! bang method
+      # already avoided by setting both explicitly. A later :destructive in the same hints list
+      # still wins (annotations_for merges in order), for a tool that means both.
+      HINT_TO_ANNOTATION = {
+        read_only: { read_only_hint: true, destructive_hint: false },
+        idempotent: { idempotent_hint: true },
+        destructive: { destructive_hint: true },
+        open_world: { open_world_hint: true },
+        closed_world: { open_world_hint: false },
+      }.freeze
+
+      module_function
+
+      def annotations_for(hints)
+        hints.each_with_object({}) { |hint, acc| acc.merge!(HINT_TO_ANNOTATION.fetch(hint, {})) }
+      end
+    end
+  end
+end

data/lib/axn/mcp/invocation.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Axn
+  module MCP
+    # Shared "server_context: -> ambient_context: -> Invoker#call -> MCP::Tool::Response" path used by
+    # Axn::MCP.wrap-generated classes (PRO-2844). The injected server_context is passed *as* the
+    # Axn's ambient_context (spread, not nested under a `server_context` key), so a wrapped Axn
+    # declares the data it needs generically -- `expects :user_id, on: :ambient_context` -- and stays
+    # adapter-agnostic (the same class works under axn-ruby_llm, or a direct call resolving from
+    # Current). Passing an explicit ambient_context: (even the empty {} when server_context is nil)
+    # is what replaces axn core's default Current-attributes-derived ambient_context, stopping
+    # server-side Current state from leaking into an MCP call.
+    #
+    # The raw server_context object -- carrying MCP transport *capabilities* (#report_progress,
+    # #cancelled?), which are not ambient data and don't survive ambient_context's declared-key
+    # filtering -- is exposed separately via Axn::MCP.server_context for the duration of the call.
+    module Invocation
+      module_function
+
+      def perform(axn_class, kwargs, text_content:, tool_name: nil)
+        # Prefer the Symbol key WHENEVER PRESENT (key?, not `||`/truthiness): an explicit
+        # server_context: nil must win over a String-keyed value, or a caller could forge
+        # server_context by appending an extra "server_context" argument alongside a real, explicit
+        # nil. Only fall back to the String key when the Symbol key is absent entirely -- a
+        # forwarding layer that splats a parsed Hash without symbolizing first would otherwise
+        # silently lose the real value (it gets stripped below as `rest`, with no reader here to
+        # have captured it first).
+        server_context = kwargs.key?(:server_context) ? kwargs[:server_context] : kwargs["server_context"]
+        # Strip :ambient_context too, not just :server_context, and strip BOTH keys under either
+        # a Symbol or a String form: **rest is expanded after the trusted `ambient_context:`
+        # literal below, so a caller-supplied `ambient_context:`/`"ambient_context"` kwarg (e.g.
+        # smuggled in as an extra tool argument from a transport that splats parsed JSON without
+        # symbolizing keys first) would otherwise silently win -- Ruby keeps a String key distinct
+        # from the Symbol literal at the splat site, and Axn::Core::Context only symbolizes afterwards
+        # (last-write-wins on the collision), so `.except` with Symbol keys alone doesn't catch it.
+        rest = kwargs.reject { |k, _| %w[server_context ambient_context].include?(k.to_s) }
+
+        # The sanctioned tool call path (axn core's Axn::Tools::Invoker, PRO-2943/PRO-3332), not a
+        # bare `axn_class.call` -- args here are untrusted, model-supplied wire data, and the Invoker
+        # applies the tool contract a trusted in-process `.call` deliberately doesn't: always-on
+        # coercion of those wire args (a JSON-string "5" for an `expects :n, type: Integer` becomes
+        # the Integer), a user-facing "Invalid tool arguments" failure instead of an on_exception page
+        # for an inbound contract violation, and rejection of a top-level key the tool never declared
+        # (previously silently dropped by plain `**kwargs`). `adapter: :mcp` stamps every call this
+        # Invoker makes with the `invoked_via` dimension for its whole call tree (Datadog can then
+        # separate tool-driven traffic from ordinary direct calls) -- matches axn-ruby_llm's and
+        # axn-openapi's own `Invoker.new(user_facing_input_errors: true, reject_undeclared_inputs:
+        # true)` profile, the established contract for an LLM/model-facing tool adapter.
+        #
+        # `rest`/`server_context` here are unchanged from before this migration: the Invoker ALSO
+        # strips a model-supplied `ambient_context` key and merges in the trusted `ambient_context:`
+        # kwarg after that guard, so this file's own stripping above is now redundant with the
+        # Invoker's -- kept as-is rather than removed, since a caller-supplied `ambient_context` was
+        # already stripped from `rest` before it ever reaches here.
+        invoker = Axn::Tools::Invoker.new(adapter: :mcp, user_facing_input_errors: true, reject_undeclared_inputs: true)
+        result = Axn::MCP.with_server_context(server_context) do
+          invoker.call(axn_class, rest, ambient_context: server_context || {})
+        end
+
+        # Uphold axn's non-bang "never raises" contract at the adapter boundary. The wrapped Axn's own
+        # `.call` never raises -- core catches action exceptions into a failed Result and pages
+        # on_exception itself -- but the TRANSPORT layer that runs AFTER it (exposed-value
+        # serialization, response building) can raise outside core's executor: a value with no honest
+        # JSON form (dup keys, non-finite float, non-UTF-8 bytes, an opaque value under
+        # reject_opaque_exposed_values), a structure past JSON's max_nesting, or a gem bug.
+        #
+        # `guard_tool_response` (core's Axn::Tools::AdapterSerialization, PRO-2996) owns that guard for
+        # every tool adapter: it reports through axn's global on_exception hook -- inside its own
+        # best_effort, so a broken reporter can't break the guard -- honors core's
+        # `best_effort_raises_in_dev` by re-raising in development, and otherwise calls `on_error` so
+        # the adapter builds its own transport-native response. Only the MCP-shaped parts are ours: the
+        # diagnostic log line and the `MCP::Tool::Response`. Scoped to the mapping step ONLY (never
+        # axn_class.call above, which already reports its own exceptions -- wrapping both would
+        # double-report one failure).
+        Axn::MCP.guard_tool_response(axn_class, on_error: lambda { |e|
+          # The user-facing response stays generic (ADAPTER_FAILURE_MESSAGE) -- this line is an
+          # operator's only pointer to WHY. Mirrors axn-openapi's dispatcher hint: the config pointer
+          # lives HERE rather than in core's exception message, since core raises the same error for
+          # adapters with no such setting. Named as BOTH config levels, never just the gem-wide setter
+          # -- the value is resolved per-tool, so a `configure(:mcp)` override beats `config`, and core
+          # exposes no way to ask which level supplied a resolved value. Non-committal ("if this is")
+          # because reject_opaque_exposed_values being on doesn't mean THIS failure is an opaque
+          # rejection -- it could equally be a colliding key, a non-finite Float, or a gem bug.
+          #
+          # Resolved right here rather than threaded in as a kwarg: `Axn::MCP.serialize_exposed` now
+          # resolves the same override internally (off the result's own action class), so `perform` no
+          # longer receives it. A second read is fine -- this one only builds a diagnostic string, it
+          # gates no behavior.
+          #
+          # Named by the MCP-facing tool_name (from wrap's `resolved_name`), not the wrapped Axn's own
+          # class name: `Axn::MCP.wrap` lets the same Axn mount under a different name per call site
+          # (an explicit `name:`, or a per-adapter `tool mcp: { name: }` override), and an operator
+          # correlating this line with a failed MCP request has the REQUEST's tool name, not the class's.
+          # Falls back to `resolved_axn_name` (axn core) for a caller of `perform` outside `wrap` (the
+          # specs) -- never raw `#{axn_class}`: Class#to_s does NOT dispatch through an overridden
+          # `.name` (it renders the object-id form regardless), so a class with no assigned constant --
+          # e.g. one built via Axn::Factory.build -- would otherwise show as `#<Class:0x...>` instead of
+          # naming the action.
+          #
+          # Kept inside its own best_effort, rather than leaning on guard_tool_response's rescue around
+          # `on_error`: that rescue reports and then RE-RAISES, so a broken configured logger (or a
+          # hostile tool_name override) would escape as an exception on the very path whose whole job
+          # is to return an error response. Swallowing it here keeps the response guaranteed; the log
+          # line is the diagnostic, not the contract.
+          Axn::Extensions.best_effort("Axn::MCP transport-failure diagnostic log", action: axn_class) do
+            hint = if Axn::MCP.resolve_override_for(axn_class, :reject_opaque_exposed_values)
+                     display_name = tool_name || axn_class.resolved_axn_name
+                     " (if this is an opaque-value rejection: reject_opaque_exposed_values resolved true for " \
+                       "#{display_name} — unset it on the action via `configure(:mcp)`, or " \
+                       "gem-wide via `Axn::MCP.config.reject_opaque_exposed_values = false`, whichever is set)"
+                   else
+                     ""
+                   end
+            Axn.config.logger.error { "[axn-mcp] failed to serialize successful result: #{e.class}: #{e.message}#{hint}" }
+          end
+
+          Serializer.error_response(Serializer::ADAPTER_FAILURE_MESSAGE)
+        }) do
+          Serializer.result_to_mcp_response(result, text_content:)
+        end
+      end
+    end
+  end
+end

data/lib/axn/mcp/serializer.rb

@@ -8,48 +8,34 @@ module Axn
     module Serializer
       module_function
 
-      def serialize_exposed(result, field_configs)
-        field_configs.each_with_object({}) do |config, hash|
-          value = result.public_send(config.field)
-          hash[config.field.to_s] = serialize_value(value)
-        end
-      end
-
-      def serialize_value(value)
-        case value
-        when nil, String, Integer, Float, TrueClass, FalseClass
-          value
-        when Hash
-          value.transform_keys(&:to_s).transform_values { |v| serialize_value(v) }
-        when Array
-          value.map { |v| serialize_value(v) }
-        else
-          if value.respond_to?(:as_json)
-            value.as_json
-          elsif value.respond_to?(:to_h)
-            serialize_value(value.to_h)
-          else
-            value.to_s
-          end
-        end
-      end
+      # Client-facing text when the transport layer raises while turning a *successful* result into a
+      # response (serialization, response-building — see Invocation.perform's guard). Deliberately
+      # generic: the actionable detail is a gem/tool bug, so it rides on the reported exception (logs
+      # / on_exception), not the tool's response — mirroring how axn keeps a failure's detail off the
+      # user-facing message.
+      ADAPTER_FAILURE_MESSAGE = "The tool could not produce a valid response"
 
-      def result_to_mcp_response(result, field_configs, text_content: :structured)
+      # No `reject_opaque_exposed_values:` kwarg: `Axn::MCP.serialize_exposed` (from core's
+      # Axn::Tools::AdapterSerialization) resolves it per-tool off `result.__action__`'s own class, so
+      # there is nothing left for a caller to pass -- or to pass wrong. Resolving one class's override
+      # while rendering a different class's result is now structurally impossible.
+      def result_to_mcp_response(result, text_content: :structured)
         if result.ok?
-          exposed = serialize_exposed(result, field_configs)
+          exposed = Axn::MCP.serialize_exposed(result)
           success_text = success_response_text(result, exposed, text_content)
           ::MCP::Tool::Response.new(
             [{ type: "text", text: success_text }],
             structured_content: exposed.presence,
           )
         else
-          ::MCP::Tool::Response.new(
-            [{ type: "text", text: result.error }],
-            error: true,
-          )
+          error_response(result.error)
         end
       end
 
+      def error_response(text)
+        ::MCP::Tool::Response.new([{ type: "text", text: }], error: true)
+      end
+
       def success_response_text(result, exposed, text_content)
         use_message = text_content == :message
         success_message = result.respond_to?(:success) ? result.success : result.message

data/lib/axn/mcp/tool.rb

@@ -2,149 +2,62 @@
 
 module Axn
   module MCP
-    class Tool < ::MCP::Tool
-      include Axn
-
-      expects :server_context, optional: true, description: "MCP server context (injected automatically)"
-
-      class << self
-        NOT_SET = Object.new.freeze
-
-        def mcp_text_content(value = NOT_SET)
-          if value == NOT_SET
-            resolved_mcp_text_content
-          else
-            Config.validate_mcp_text_content!(value)
-            @mcp_text_content = value
-          end
-        end
-
-        def resolved_mcp_text_content
-          if instance_variable_defined?(:@mcp_text_content) && !@mcp_text_content.nil?
-            @mcp_text_content
-          else
-            Axn::MCP.config.mcp_text_content
-          end
-        end
-
-        def input_schema(value = NOT_SET)
-          if value != NOT_SET
-            super
-          elsif @input_schema_value
-            @input_schema_value
-          else
-            @input_schema_value = ::MCP::Tool::InputSchema.new(
-              SchemaBuilder.build_input(internal_field_configs, subfield_configs),
-            )
-          end
-        end
-
-        def input_schema_value
-          @input_schema_value || input_schema
-        end
-
-        def output_schema(value = NOT_SET)
-          if value != NOT_SET
-            super
-          elsif @output_schema_value
-            @output_schema_value
-          elsif external_field_configs.empty?
-            nil
-          else
-            @output_schema_value = ::MCP::Tool::OutputSchema.new(
-              SchemaBuilder.build_output(external_field_configs),
+    # RETIRED (PRO-2923): the `Axn::MCP::Tool` subclass base has been removed.
+    #
+    # It previously wrapped `include Axn` + `::MCP::Tool` into a dual-mode base whose `.call`
+    # returned either an `Axn::Result` (called directly) or an `MCP::Tool::Response` (called with
+    # `server_context:`). That dual mode also overrode `input_schema` to a non-Hash
+    # `MCP::Tool::InputSchema`, which broke `Axn::RubyLLM.wrap` on the same class. The author-once
+    # model replaces it: write a plain Axn and expose it with `Axn::MCP.wrap` (per tool) or
+    # `Axn::MCP.tools` (every registered `:mcp` tool at once).
+    #
+    # Kept only as a raising tombstone so leftover `class MyTool < Axn::MCP::Tool` / `.define` code
+    # fails with a migration message instead of a bare `NameError`/`NoMethodError`. See
+    # DEPRECATIONS.md — this constant is slated for deletion at 1.0.
+    class Tool
+      MIGRATION_MESSAGE = <<~MSG
+        Axn::MCP::Tool (subclass base) and Axn::MCP::Tool.define were retired in PRO-2923.
+
+        Instead of subclassing:
+
+            class MyTool < Axn::MCP::Tool
+              expects :query, type: String
+              exposes :results, type: Array
+              def call = expose(results: Item.search(query))
+            end
+
+        author a plain Axn and expose it with Axn::MCP.wrap:
+
+            class MyTool
+              include Axn
+              tool :mcp                       # optional: discoverable via Axn::MCP.tools
+              expects :query, type: String
+              exposes :results, type: Array
+              def call = expose(results: Item.search(query))
+            end
+
+            Axn::MCP.wrap(MyTool)             # -> a ready-to-register ::MCP::Tool subclass
+            # ...or register every :mcp tool at once:
+            MCP::Server.new(name: "...", version: "...", tools: Axn::MCP.tools)
+
+        For a one-off inline tool (the old .define use case), wrap an Axn::Factory.build:
+
+            Axn::MCP.wrap(
+              Axn::Factory.build(expects: { query: { type: String } },
+                                 exposes: { results: { type: Array } }) { expose results: Item.search(query) },
+              name: "search", description: "Search for items",
             )
-          end
-        end
-
-        def output_schema_value
-          return @output_schema_value if @output_schema_value
-          return nil if external_field_configs.empty?
-
-          output_schema
-        end
-
-        def to_h
-          input_schema
-          output_schema unless external_field_configs.empty?
-          super
-        end
-
-        def call(**kwargs)
-          result = new(**kwargs).tap(&:_run).result
-
-          # Branch on presence of server_context:
-          # - Present: called from MCP server, return MCP::Tool::Response
-          # - Absent: called directly as Axn, return Axn::Result
-          return result unless kwargs.key?(:server_context)
-
-          Serializer.result_to_mcp_response(result, external_field_configs, text_content: resolved_mcp_text_content)
-        end
 
-        def call!(**)
-          result = call(**)
+        See DEPRECATIONS.md.
+      MSG
 
-          # For MCP calls (with server_context), just return the response
-          return result if result.is_a?(::MCP::Tool::Response)
-
-          # For direct Axn calls, raise on failure
-          return result if result.ok?
-
-          raise result.exception
-        end
-
-        # Convenience DSL for annotations
-        # See: https://github.com/modelcontextprotocol/ruby-sdk#tool-annotations
-        #
-        # Available annotations:
-        #   destructive_hint: true/false - Indicates if tool performs destructive operations (default: true)
-        #   idempotent_hint: true/false - Indicates if tool's operations are idempotent (default: false)
-        #   open_world_hint: true/false - Indicates if tool operates in open world context (default: true)
-        #   read_only_hint: true/false - Indicates if tool only reads data (default: false)
-        #   title: "string" - Human-readable title for the tool
-
-        def read_only!
-          annotations(read_only_hint: true, destructive_hint: false)
-        end
-
-        def destructive!
-          annotations(destructive_hint: true, read_only_hint: false)
-        end
-
-        def idempotent!
-          annotations(idempotent_hint: true)
-        end
-
-        def open_world!
-          annotations(open_world_hint: true)
-        end
-
-        def closed_world!
-          annotations(open_world_hint: false)
-        end
-
-        # Factory-style tool definition for quick one-off tools
-        def define(description:, expects: [], exposes: [], annotations: nil, mcp_text_content: NOT_SET, **_opts, &block)
-          tool_class = Class.new(self) do
-            include Axn unless self < Axn
-          end
-
-          FieldDeclarations.hydrate(expects).each do |field, field_opts|
-            tool_class.expects(field, **field_opts)
-          end
-
-          FieldDeclarations.hydrate(exposes).each do |field, field_opts|
-            tool_class.exposes(field, **field_opts)
-          end
-
-          tool_class.description(description)
-          tool_class.annotations(annotations) if annotations
-          tool_class.mcp_text_content(mcp_text_content) if mcp_text_content != NOT_SET
-
-          tool_class.define_method(:call, &block) if block
+      def self.inherited(subclass)
+        super
+        raise NotImplementedError, MIGRATION_MESSAGE
+      end
 
-          tool_class
-        end
+      def self.define(*, **, &)
+        raise NotImplementedError, MIGRATION_MESSAGE
       end
     end
   end

data/lib/axn/mcp/version.rb

@@ -2,6 +2,6 @@
 
 module Axn
   module MCP
-    VERSION = "0.1.0"
+    VERSION = "0.2.2"
   end
 end

data/lib/axn/mcp/wrap.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/object/blank"
+
+module Axn
+  module MCP
+    class << self
+      # Exposes any Axn (whether or not it subclasses Axn::MCP::Tool) as an ::MCP::Tool subclass.
+      # The wrapped class's own .call/.call! are untouched -- direct callers keep getting a plain
+      # Axn::Result. All MCP transport concerns (schema, server_context routing, response mapping)
+      # live entirely on the generated subclass, via the same Axn::MCP::Invocation path
+      # Axn::MCP::Tool#call uses -- proves the "author once" story from PRO-2844/PRO-2842.
+      #
+      # The generated subclass is MCP-transport-only, unlike Axn::MCP::Tool: its .call always
+      # returns MCP::Tool::Response (never a raw Axn::Result), and it deliberately has no .call! --
+      # MCP::Server itself only ever calls .call, and a consumer wanting real bang/raise-on-failure
+      # semantics can call the original wrapped class's own .call! directly (unwrapped).
+      VALID_PRESENT_AS = %i[structured message].freeze
+
+      # `server_context` is the input name the wrapper reserves for the injected MCP context
+      # (Invocation strips it before calling the Axn), so a wrapped Axn must not declare it as a
+      # top-level `expects`. (`ambient_context`, the other stripped key, needs no entry here: axn core
+      # already reserves it and rejects `expects :ambient_context` at declaration.)
+      RESERVED_INPUT_FIELDS = %i[server_context].freeze
+      private_constant :RESERVED_INPUT_FIELDS
+
+      # Sentinel for the retired `mcp_text_content:` kwarg (renamed to `present_as:`, PRO-2923), so a
+      # caller still passing it gets a pointed migration error instead of silently having it ignored.
+      RENAMED_MCP_TEXT_CONTENT = Object.new.freeze
+      private_constant :RENAMED_MCP_TEXT_CONTENT
+
+      # The gem-level convenience for building a ready-to-register MCP tool list (PRO-2923),
+      # symmetric with `Axn::RubyLLM.tools`: enumerate every Axn that belongs to the :mcp adapter
+      # (via axn core's process-global registry) and wrap each one. Zero-arg by design -- per-tool
+      # customization comes from each class's own `configure(:mcp) { ... }` (honored inside `wrap`)
+      # and its `tool name:`/`description`, not per-call kwargs -- so a consumer registers tools with
+      # just `MCP::Server.new(tools: Axn::MCP.tools, ...)` instead of a hand-maintained array.
+      def tools
+        Axn::Tools.for(:mcp).map { |axn_class| wrap(axn_class) }
+      end
+
+      def wrap(axn_class, description: nil, name: nil, title: nil, icons: nil, meta: nil, annotations: nil,
+               present_as: nil, mcp_text_content: RENAMED_MCP_TEXT_CONTENT)
+        reject_renamed_mcp_text_content!(mcp_text_content)
+        validate_present_as!(present_as)
+        reject_reserved_input_fields!(axn_class)
+        resolved_name = resolve_wrap_tool_name(axn_class, name)
+        resolved_description = description || axn_class.description
+
+        # Each metadata kwarg falls back to the wrapped Axn's own `configure(:mcp)` value (via axn
+        # core's shadow-proof resolver), so it's carried through the zero-arg `Axn::MCP.tools` path
+        # too; an explicit `wrap` kwarg still wins. `annotations` also falls back further, to the
+        # `semantic_hints`-derived defaults -- precedence: kwarg > configure(:mcp) > semantic_hints.
+        resolved_title = title || Axn::MCP.resolve_override_for(axn_class, :title)
+        resolved_icons = icons || Axn::MCP.resolve_override_for(axn_class, :icons)
+        resolved_meta  = meta  || Axn::MCP.resolve_override_for(axn_class, :meta)
+        configured_annotations = annotations || Axn::MCP.resolve_override_for(axn_class, :annotations)
+
+        # Surface the resolved revision in `_meta` (never the name -- name is the cross-adapter
+        # identity), so an operator/model can see which version `Axn::MCP.tools` collapsed to. Only
+        # for actually-versioned tools; an unversioned tool (default `tool_version` 1) stays
+        # meta-free. Keyed `tool_version` to mirror the DSL and avoid clobbering a consumer's own
+        # `version` meta key.
+        resolved_meta = { **(resolved_meta || {}), tool_version: axn_class.tool_version } if axn_class.tool_version > 1
+
+        Class.new(::MCP::Tool) do
+          tool_name(resolved_name)
+          description(resolved_description)
+          title(resolved_title) if resolved_title
+          icons(resolved_icons) if resolved_icons
+          meta(resolved_meta) if resolved_meta
+
+          # axn_class.input_schema/.output_schema are axn core's own public reflection entry points --
+          # wiring to those directly, rather than reaching past them for the lower-level builder the
+          # wrapped Axn's own methods already call, keeps this on the documented surface.
+          input_schema(axn_class.input_schema)
+          output_schema(axn_class.output_schema) unless axn_class.external_field_configs.empty?
+
+          hint_annotations = Axn::MCP::Annotations.annotations_for(axn_class._semantic_hints)
+          resolved_annotations = configured_annotations || (hint_annotations if hint_annotations.any?)
+          # Skip the setter for an EMPTY hash, not just nil: `annotations: {}` (or a `configure(:mcp)`
+          # empty override) is how a caller suppresses the semantic-hint-derived annotations, and
+          # `MCP::Tool.annotations()` with no kwargs would instead advertise the SDK's own defaults
+          # (destructiveHint: true, openWorldHint: true, ...) -- the opposite of what they asked for.
+          self.annotations(**resolved_annotations) if resolved_annotations.present?
+
+          define_singleton_method(:call) do |**kwargs|
+            # Resolved fresh on every call, not captured once at wrap-time, so a gem-wide config
+            # change takes effect immediately, even for tools already wrapped before the change.
+            #
+            # Reads the wrapped Axn's own per-action override (e.g. `axn_class.configure(:mcp) { |c|
+            # c.present_as = :message }`) via Axn::MCP.resolve_override_for rather than
+            # axn_class.present_as -- axn_class is a plain Axn that may never have included
+            # Axn::MCP.overrides, so it may have no such method at all; resolve_override_for reads
+            # the override store directly and falls back to the gem-wide config on its own, with no
+            # dependency on axn_class having that accessor.
+            #
+            # `present_as` is the only setting resolved here now: `reject_opaque_exposed_values` is
+            # resolved inside `Axn::MCP.serialize_exposed` (core's Axn::Tools::AdapterSerialization),
+            # keyed off the result's own action class, so there is no longer a value to thread through
+            # the invocation -- and no way for a caller to thread the wrong one.
+            Axn::MCP::Invocation.perform(
+              axn_class, kwargs,
+              text_content: present_as || Axn::MCP.resolve_override_for(axn_class, :present_as),
+              tool_name: resolved_name
+            )
+          end
+        end
+      end
+
+      private
+
+      # `mcp_text_content:` was renamed to `present_as:` (PRO-2923). It's kept as a raising alias --
+      # rather than silently dropped -- so a caller still passing it gets a pointed migration error.
+      # Detected via a sentinel (not `nil?`), so an explicit `mcp_text_content: nil` is still caught.
+      def reject_renamed_mcp_text_content!(value)
+        return if value.equal?(RENAMED_MCP_TEXT_CONTENT)
+
+        raise ArgumentError,
+              "Axn::MCP.wrap's `mcp_text_content:` was renamed to `present_as:` (PRO-2923). " \
+              "Replace `mcp_text_content: #{value.inspect}` with `present_as: #{value.inspect}`."
+      end
+
+      # Fail fast on any explicitly-provided invalid value (a typo like :mesage, or `false`)
+      # rather than silently falling through to :structured -- matches the validation the
+      # `present_as` setting already enforces. `nil` alone means "not provided" (use the resolved
+      # per-class/gem-wide value at call time) -- checked via `nil?`, not truthiness, so
+      # `present_as: false` can't skip this guard the way a truthy-only check would.
+      def validate_present_as!(present_as)
+        return if present_as.nil? || VALID_PRESENT_AS.include?(present_as)
+
+        raise ArgumentError, "present_as must be one of #{VALID_PRESENT_AS.map(&:inspect).join(", ")}; got #{present_as.inspect}"
+      end
+
+      # `server_context` is reserved: Invocation injects the MCP server context under that key and
+      # strips it before calling the Axn (see Invocation.perform). A wrapped Axn declaring it as a
+      # normal TOP-LEVEL `expects` (so it surfaces in `input_schema`, unlike an `on: :ambient_context`
+      # field, which is excluded) would advertise it as a client argument yet never receive it -- a
+      # schema-valid call would then fail the Axn's own validation. Reject at wrap time rather than ship
+      # that contradiction; the data an Axn needs from the context goes on `ambient_context`
+      # (`expects :user_id, on: :ambient_context`).
+      def reject_reserved_input_fields!(axn_class)
+        reserved = RESERVED_INPUT_FIELDS & (axn_class.input_schema[:properties] || {}).keys.map(&:to_sym)
+        return if reserved.empty?
+
+        raise ArgumentError,
+              "Axn::MCP.wrap can't expose #{axn_class}: #{reserved.map(&:inspect).join(", ")} " \
+              "#{reserved.one? ? "is a reserved top-level input name" : "are reserved top-level input names"} " \
+              "(the wrapper injects the MCP server context there). Declare the data the Axn needs on " \
+              "`ambient_context` instead, e.g. `expects :user_id, on: :ambient_context`."
+      end
+
+      # Resolve the provider-facing tool name. An explicit `name:` kwarg (most local to the call
+      # site) wins; otherwise consume axn core's canonical `tool_name(:mcp)` -- passing the adapter so
+      # a per-adapter `tool mcp: { name: "..." }` override wins (PRO-2942), then a shared `tool name:`,
+      # then `tool_name_stripped_prefixes` + snake_cased class name. Passing `:mcp` also matches the
+      # name `Axn::Tools.for(:mcp)` sorts / collapses to the latest per `tool_name`, so `.tools` and a
+      # direct `wrap` agree.
+      #
+      # Core's `tool_name` never returns blank: a truly anonymous, never-named class (no class name,
+      # no `axn_name`) falls back to the generic "tool". That's a footgun for wrap's common inline
+      # `tools: [Axn::MCP.wrap(...)]` usage -- every such nameless tool would collide on "tool" and
+      # be unregisterable in practice -- so keep wrap's original fail-fast for that case rather than
+      # silently shipping a tool named "tool"; require an explicit `name:` instead.
+      def resolve_wrap_tool_name(axn_class, name)
+        return name if name
+        return axn_class.tool_name(:mcp) if axn_class.name.present? || axn_class.axn_name.present?
+
+        raise ArgumentError, "Axn::MCP.wrap requires name: when the wrapped Axn has no derivable class name (#{axn_class}.name is nil)"
+      end
+    end
+  end
+end