axn-mcp 0.1.0 → 0.2.2

data/README.md

@@ -2,6 +2,10 @@
 
 Build [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) tools using [Axn](https://github.com/teamshares/axn)'s declarative `expects`/`exposes` contract. This gem wraps the official [MCP Ruby SDK](https://github.com/modelcontextprotocol/ruby-sdk) and auto-generates JSON schemas from your Axn field declarations.
 
+**Author once, expose anywhere.** You write a plain Axn — a normal action, usable by any caller — and this gem exposes it as an `::MCP::Tool` with `Axn::MCP.wrap` (one tool) or `Axn::MCP.tools` (every registered tool at once). The Axn stays a plain Axn: called directly it returns an `Axn::Result`, with no MCP awareness. The same action can be exposed to other adapters (e.g. an `axn-ruby_llm`) the same way, from the same class.
+
+This gem is scoped to MCP **Tools** only. `MCP::Server` also supports `resources`, `resource_templates`, and `prompts` as first-class concepts — `Axn::MCP.wrap` doesn't adapt an Axn into any of those, and there's no `Axn::MCP.wrap_as_resource` or equivalent. If you need those, register them with `MCP::Server` directly per the [MCP Ruby SDK documentation](https://github.com/modelcontextprotocol/ruby-sdk).
+
 ## Installation
 
 Add to your Gemfile:
@@ -18,10 +22,12 @@ bundle install
 
 ## Quick Start
 
-Define an MCP tool by inheriting from `Axn::MCP::Tool`:
+Write a plain Axn, then expose it with `Axn::MCP.wrap`:
 
 ```ruby
-class GreetUser < Axn::MCP::Tool
+class GreetUser
+  include Axn
+
   description "Greet a user by name"
 
   expects :name, type: String, description: "The user's name"
@@ -31,36 +37,253 @@ class GreetUser < Axn::MCP::Tool
     expose greeting: "Hello, #{name}!"
   end
 end
+
+GreetUserTool = Axn::MCP.wrap(GreetUser) # => an ::MCP::Tool subclass, ready to register
 ```
 
-That's it. The gem automatically:
+`Axn::MCP.wrap` returns a genuine `::MCP::Tool` subclass. The gem automatically:
 
 - Generates `inputSchema` from your `expects` declarations
 - Generates `outputSchema` from your `exposes` declarations
 - Converts `Axn::Result` to `MCP::Tool::Response`
 - Serializes exposed data to JSON-safe `structured_content`
 
-## Usage
+`GreetUser` itself is untouched — `GreetUser.call(name: "Alice")` still returns a plain `Axn::Result`.
+
+`inputSchema`/`outputSchema` are generated by `axn` core from your `expects`/`exposes` declarations,
+and exposed values are serialized through its `Axn::Extensions::Serialization` facade. See
+[Field declarations & schema](#field-declarations--schema) for the type mappings and how the schema
+handles values whose wire form isn't knowable from the declaration.
+
+## Exposing tools
+
+An Axn is just an action; the gem turns it into an `::MCP::Tool` at the edge. There are three ways
+in, all producing the same kind of `::MCP::Tool` subclass.
+
+### One tool: `Axn::MCP.wrap`
 
-### Basic Tool Definition
+```ruby
+GreetUserTool = Axn::MCP.wrap(GreetUser)
+```
+
+`wrap(axn_class, description: nil, name: nil, title: nil, icons: nil, meta: nil, annotations: nil, present_as: nil)`:
+
+- **`description:`** defaults to the Axn's own `.description`. Pass it to override.
+- **`name:`** defaults to `axn_class.tool_name` — axn core's canonical, provider-safe name, which
+  honors a `tool name: "..."` override on the Axn and any configured `tool_name_stripped_prefixes`
+  (e.g. `GreetUser` → `"greet_user"`). Pass `name:` to override. This matters if you register the
+  tool inline (`tools: [Axn::MCP.wrap(GreetUser)]`) rather than assigning it to a constant. If the
+  wrapped Axn is *truly* anonymous (no class name, no `axn_name`), `wrap` raises `ArgumentError`
+  rather than ship an unusable, unnamed tool — pass `name:` in that case.
+- **`annotations:`** / **`present_as:`** / **`title:`** / **`icons:`** / **`meta:`** — all
+  optional; see the sections below. Omitted values fall through to the Axn's own declarations
+  (`semantic_hints`, `configure(:mcp)`) or `::MCP::Tool`'s defaults.
+
+The original class is never modified — the transport concerns (schema, `server_context` routing,
+response mapping) live entirely on the generated subclass:
 
 ```ruby
-class CreateNote < Axn::MCP::Tool
-  description "Create a new note"
+GreetUserTool.input_schema_value.to_h[:properties].keys        # => [:name]
+GreetUserTool.call(name: "Bob", server_context: { user_id: 42 }) # => MCP::Tool::Response
+GreetUser.call(name: "Alice")                                    # => Axn::Result (untouched)
+```
 
-  expects :title, type: String, description: "Note title"
-  expects :content, type: String, description: "Note body"
-  expects :tags, type: Array, optional: true, description: "Optional tags"
+The generated subclass's `.call` **always** returns `MCP::Tool::Response`, and it has no `.call!` —
+if you want raise-on-failure semantics, call the original Axn's `.call!` directly (unwrapped).
 
-  exposes :note_id, type: Integer, description: "ID of the created note"
+#### Never-raises contract
 
-  def call
-    note = Note.create!(title:, content:, tags: tags || [])
-    expose note_id: note.id
-  end
+`.call` extends axn's non-bang "never raises" contract to the transport boundary. A tool's own
+failures come back as an error `MCP::Tool::Response` (axn already catches exceptions *inside* the
+action into a failed `Axn::Result` — see [Error Handling](#error-handling)). And if the transport
+layer *around* the action raises — exposed-value serialization hitting a value with no honest JSON
+form, a structure past JSON's `max_nesting`, or a bug — the wrapper catches that too: it reports the
+exception through axn's global `on_exception` hook (so it's never silent) and returns a generic
+error response, rather than letting an exception escape `.call` on a direct or custom transport.
+The one exception is axn's dev mode (`Axn.config.best_effort_raises_in_dev` in `development`): there
+it re-raises instead, so a real bug surfaces loudly rather than being masked.
+
+### Every registered tool: `Axn::MCP.tools`
+
+Mark an Axn as an MCP tool with `tool :mcp` (axn core's tool-registry DSL), and `Axn::MCP.tools`
+returns them all, already wrapped — no hand-maintained array:
+
+```ruby
+class ListCompanies
+  include Axn
+  tool :mcp
+  description "List companies"
+  # ...
 end
+
+MCP::Server.new(name: "my-server", version: "1.0.0", tools: Axn::MCP.tools)
 ```
 
+`Axn::MCP.tools` is `Axn::Tools.for(:mcp).map { |axn| Axn::MCP.wrap(axn) }` — zero-arg by design.
+Per-tool customization comes from each class's own declarations (`tool name:`, `description`,
+`semantic_hints`, `configure(:mcp)`), all honored inside `wrap`. It's symmetric with the same
+pattern in sibling adapter gems (e.g. `Axn::RubyLLM.tools`).
+
+**Versioning.** When two Axns share a `tool_name` but declare different `tool_version`s (axn core's
+DSL — identity is `(tool_name, tool_version)`), `Axn::Tools.for(:mcp)` returns only the latest, so
+`Axn::MCP.tools` exposes a single tool for that name, resolving to the highest version. For a
+versioned tool (`tool_version > 1`), `wrap` also surfaces the resolved revision as `tool_version` in
+the tool's `_meta` — visible to an operator/model without touching the tool's `name` (its
+cross-adapter identity). Unversioned tools (the default `tool_version` of 1) get no such `_meta`.
+
+### Membership: directory roots + the `tool` DSL
+
+A class's `:mcp` membership is **`(directory-root grant ∪ tool declaration) − except`**:
+
+- **Directory roots** — every Axn whose file lives under one of this adapter's `tool_roots` is granted, no `tool` declaration needed. `Axn::MCP` ships a default root of **`agent_tools`** (i.e. `app/agent_tools/` in a Rails app), a dir shared with `axn-ruby_llm` — so a tool dropped there is exposed over both surfaces at once. Configure the roots with `Axn::MCP.config.tool_roots = ["agent_tools", "actions/mcp_tools"]` (relative to `Rails.root/app`, or absolute). Roots are validated: a broad entry (`app`, `.`, `actions`, a `..` traversal) is rejected, so you can't bulk-expose every business action.
+- **`tool :mcp`** — explicitly **adds** `:mcp` (on top of any directory grant), for a tool that lives *outside* the roots. Bare **`tool`** grants every registered adapter.
+- **`configure(:mcp) { … }`** — declaring MCP config implies `:mcp` membership.
+- **`tool except: :mcp`** — narrows: keeps the directory grant but removes `:mcp`. **`tool false`** opts out of every adapter.
+
+> **Union, not replacement:** `tool :mcp` **adds** to the directory grant rather than replacing it — a tool under a root *and* declaring `tool :ruby_llm` belongs to both. Declare all adapters/`except:`/per-adapter options in a single `tool` call (a second `tool` on the same class raises).
+
+```ruby
+# In app/agent_tools/ — no `tool` needed; granted to every adapter whose roots include agent_tools:
+class ListCompanies
+  include Axn
+  description "List companies"
+  # ...
+end
+
+# Anywhere else — opt in explicitly:
+class Ping
+  include Axn
+  tool :mcp
+  description "Ping"
+  # ...
+end
+
+MCP::Server.new(name: "my-server", version: "1.0.0", tools: Axn::MCP.tools)
+```
+
+**The class must be loaded for `Axn::MCP.tools` to see it** — the registry only enumerates
+currently-defined classes. `tool_roots` directories are eager-loaded on demand (and by Rails
+eager-loading); a `tool :mcp` class that lives *outside* a root and isn't otherwise required won't
+appear until its file is loaded. Enumerate from `config.after_initialize` / a `to_prepare` block
+(not a `config/initializers` file) for reliable results under Rails.
+
+For a curated subset instead of all of them, filter the registry yourself:
+`Axn::Tools.for(:mcp).select { ... }.map { |a| Axn::MCP.wrap(a) }`.
+
+### One-off inline tools
+
+For a throwaway tool, build a plain Axn inline with `Axn::Factory.build` (block-as-`#call`, no named
+class needed) and wrap it:
+
+```ruby
+# The block is the Axn's #call body — pass it to Axn::Factory.build.
+search = Axn::Factory.build(
+  expects: { query: { type: String, description: "Search query" } },
+  exposes: { results: { type: Array } },
+) do
+  expose results: Item.search(query)
+end
+
+SearchTool = Axn::MCP.wrap(search, name: "search", description: "Search for items", annotations: { read_only_hint: true })
+```
+
+`Axn::Factory.build` carries the action's behavior — the `#call` block plus
+`expects`/`exposes`/`success`/`error`/hooks/… — while the MCP-facing bits
+(`name:`/`description:`/`annotations:`/`present_as:`) go to `wrap`. For a multi-adapter one-off,
+build the Axn once and hand it to each adapter's `wrap`.
+
+### Mixing with native `::MCP::Tool` tools
+
+Because `wrap` returns a real `::MCP::Tool` subclass, wrapped Axns and hand-written MCP tools
+compose in one array — splat `Axn::MCP.tools` alongside anything else:
+
+```ruby
+MCP::Server.new(
+  name: "my-server", version: "1.0.0",
+  server_context: { user_id: current_user.id },
+  tools: [
+    *Axn::MCP.tools,                                   # every registered :mcp Axn, wrapped
+    NativeSearchTool,                                  # a plain MCP::Tool subclass
+    MCP::Tool.define(name: "ping", description: "…") { |server_context:, **_args| MCP::Tool::Response.new([...]) },
+  ],
+)
+```
+
+`server_context` flows identically to both: native tools read it in `call(args, server_context:)`;
+wrapped Axns get it spread into `ambient_context` (see [Server Context](#server-context)).
+
+## Tool call contract
+
+A wrapped Axn's `.call` doesn't dispatch to the plain `axn_class.call` a direct in-process caller
+gets — it runs through axn core's [`Axn::Tools::Invoker`](https://teamshares.github.io/axn/reference/tool-invoker),
+the sanctioned path for treating model-supplied arguments as untrusted wire data. This applies to
+every wrapped tool call, with no opt-out:
+
+- **Input types are always coerced.** An `expects` field with a coercible `type:` (`Date`,
+  `DateTime`, `Time`, `Symbol`, `Integer`, `Float`, `:boolean`) accepts a wire-typed String and
+  converts it before validation runs — `expects :limit, type: Integer` already accepts `"25"`, with
+  no separate `coerce:` needed. `coerce:`/`type: { coerce: true }` still exist (see below), and a
+  field can explicitly opt **out** with `type: { klass: Integer, coerce: false }` if you need this
+  particular field to reject a wire string rather than convert it.
+- **A bad or missing argument surfaces as a specific, correctable client error** — not axn's generic
+  `"Something went wrong"` — and is **not** reported through `on_exception` (a model sending a
+  malformed argument isn't a bug in your code):
+
+  ```ruby
+  expects :limit, type: Integer
+  # missing entirely  -> result.error == "Limit is not a Integer"
+  # limit: "abc"       -> result.error == "Limit could not be coerced to a Integer"
+  ```
+
+- **An argument the tool never declared with `expects` is rejected**, rather than silently dropped:
+  `extra: "value"` on a tool with no such field -> `result.error == "unknown input: extra"`.
+
+None of this touches `exposes`/output serialization, `ambient_context` resolution (still
+adapter-injected and guarded against a model-supplied override — see
+[Server Context](#server-context)), or a direct, unwrapped `TheAxn.call(...)` — a direct call keeps
+whatever `coerce_input_types`/undeclared-key behavior it already had. `wrap`'s never-raises contract
+(above) still governs the transport step *after* this — `result.error` still flows through
+`Serializer`/`guard_tool_response` exactly as any other failure does.
+
+Every wrapped call is also stamped with the `invoked_via: "mcp"` dimension for its whole call tree
+(visible in axn's own call-completion log line, and to any tracing/dashboard code keyed off it), so
+MCP-driven traffic is distinguishable from a direct `.call` with no extra work on your part.
+
+## Field declarations & schema
+
+The schema mappings below are axn core reflection surfaced through `wrap` — declare fields on a
+plain Axn (`include Axn`), and the shapes appear on `Axn::MCP.wrap(TheAxn).input_schema_value` /
+`.output_schema`.
+
+### How reflection derives schemas
+
+**Reflection is best-effort and deliberately biased stricter-than-runtime.** Schemas are built
+*statically* from your `expects`/`exposes` declarations — reflection is side-effect-free and never
+runs your validators. Where a value's wire form isn't *provable* from the declared type, the schema
+reflects the conservative answer (untyped, required, or non-null) rather than guess. The net
+contract: **a client that follows the schema will not be rejected by schema validation; the schema
+may occasionally be more restrictive than what the tool would actually accept at runtime.**
+Concretely, you may see: `type` omitted entirely (an untyped `{}`) when the wire form isn't knowable
+(e.g. a `Numeric`/`Complex` field, or a reader-only/custom-serialized object); `not: { type: "null"
+}` on a required `model:`-generated `_id` (a primary key has no fixed JSON type); `enum:
+[true]`/`[false]` for a `TrueClass`/`FalseClass` field; and `anyOf` for union types.
+
+This isn't an absolute "schema-valid implies success" guarantee, though: a schema-following call can
+still fail axn's own runtime validation in the narrow case where a field's contract is
+self-contradictory — e.g. `expects :name, type: String, default: 123` reflects `name` as *optional*
+(a default is present), but omitting it applies the invalid default and then fails runtime
+validation. Reflection derives requiredness from the declared *signals* (a present default,
+`optional:`/`allow_nil:`/`allow_blank:`) without evaluating whether the default itself is valid —
+catching that would only cover literal defaults, not custom validators, callable defaults, or model
+lookups, so the caveat exists either way. This is the one documented spot where the input schema is
+*looser* than runtime rather than stricter (a known, deliberate gap, not a bug).
+
+**Required fields also carry a presence constraint.** axn requires non-blank values by default, so a
+required `String` reflects `minLength: 1` and a required `Array` reflects `minItems: 1` (an *optional*
+field is nullable instead — e.g. `["string", "null"]` — and carries no minimum). The per-feature
+examples below omit these for focus, but real `inputSchema`/`outputSchema` output includes them on
+every required string/array field.
+
 ### Field Descriptions
 
 Use `description:` directly as a kwarg on `expects` and `exposes`:
@@ -76,7 +299,6 @@ exposes :results,    type: Array,                description: "Matching records"
 
 Axn types map to JSON Schema types:
 
-
 | Ruby Type          | JSON Schema                    |
 | ------------------ | ------------------------------ |
 | `String`           | `string`                       |
@@ -89,6 +311,16 @@ Axn types map to JSON Schema types:
 | `Date`             | `string` (format: `date`)      |
 | `DateTime`, `Time` | `string` (format: `date-time`) |
 
+### Coercing loosely-typed inbound values with `coerce:`
+
+An LLM (or a client that stringifies its JSON) doesn't always send a value in the exact Ruby type your `expects` field declares — a `Date`/`Integer`/`Float`/`Symbol`/`Time`/`DateTime` field can arrive as a `String`. **Through a wrapped tool call this already happens automatically** — see [Tool call contract](#tool-call-contract) above; `expects :count, type: Integer` alone accepts `"42"`. `coerce:`/`type: { coerce: true }` below matters for a *direct*, unwrapped `TheAxn.call(...)` (which doesn't get the Invoker's coercion), or to force coercion **on** a field even outside a tool call. Add the `coerce: <Type>` shorthand (or `type: { klass: <Type>, coerce: true }` when you also need other type options alongside it — `coerce:` can't be combined with a sibling top-level `type:`) to have `axn` core convert a well-formed string to the declared type *before* validation runs:
+
+```ruby
+expects :starts_on, coerce: Date                          # "2026-01-15" -> a Date
+expects :count,     type: { klass: Integer, coerce: true } # "42" -> 42
+```
+
+Coercion applies to inbound `expects` fields — top-level **and** subfields declared with `on:` (including ambient ones, e.g. a value spread from the MCP server context). It is **not** available on `exposes` (outbound values are serialized, not coerced) or on `shape:` block members (a shape member only constrains its parent's structure and has no reader of its own for a coerced value to resolve onto — coercion is a read-path transform) — both *raise at class-definition* if given `coerce:`. Only a non-blank `String` is converted. An unparseable string doesn't silently fall through to a generic type-mismatch: coercion raises `Axn::InboundValidationError` carrying a specific `"<field> could not be coerced to a <Type>"` message. **Through a wrapped tool call**, that specific message *is* `result.error` (e.g. `"Limit could not be coerced to a Integer"`, combined with the tool's own base `error "…"` if it has one), and it is **not** reported to `on_exception` — see [Tool call contract](#tool-call-contract). On a *direct*, unwrapped call, it stays dev-facing as any inbound violation always has: the detail rides on the exception (logs / `on_exception`), and the caller sees axn's generic `result.error` (`"Something went wrong"` by default, or the tool's own base `error "…"`). `inputSchema`/`outputSchema` output is identical with or without `coerce:` — only accepted inbound values change, not the field's advertised JSON type.
 
 ### Typed member contracts with `shape:`
 
@@ -109,18 +341,20 @@ end
   "required": ["region"],
   "properties": {
     "region":  { "type": "string" },
-    "timeout": { "type": "integer" }
+    "timeout": { "type": ["integer", "null"] }
   }
 }
 ```
 
+Requiredness and nullability are two orthogonal JSON Schema signals, not a redundancy: a member's *requiredness* is tracked solely by the `required` array (`region` is listed, so it's required); an *optional* member is omitted from `required` **and** additionally reflects a nullable `type` array (`["integer", "null"]`) — because an omittable field may resolve to null. So a required member shows up in `required` with a bare type, while an optional one is absent from `required` with a nullable type; that's why the `of:`/`shape:` examples below show `status` (required) in `required` but `active` (optional) as `["boolean", "null"]`.
+
 **`Data.define` struct:**
 
 ```ruby
 IntegrationRecord = Data.define(:source, :provider_name, :active, :status)
 
 exposes :integration, type: IntegrationRecord do
-  field :status, type: String, inclusion: { in: %w[connected error needs_reconnect] }
+  field :status, type: String, inclusion: %w[connected error needs_reconnect]
   field :active, type: :boolean, optional: true
 end
 ```
@@ -131,7 +365,7 @@ end
   "required": ["status"],
   "properties": {
     "status":        { "type": "string", "enum": ["connected", "error", "needs_reconnect"] },
-    "active":        { "type": "boolean" },
+    "active":        { "type": ["boolean", "null"] },
     "source":        {},
     "provider_name": {}
   }
@@ -170,9 +404,11 @@ exposes :values, type: Array, of: [String, Numeric]
 ```
 
 ```json
-{ "type": "array", "items": { "anyOf": [{ "type": "string" }, { "type": "number" }] } }
+{ "type": "array", "items": { "anyOf": [{ "type": "string" }, {}] } }
 ```
 
+(The `Numeric` member is left untyped: it admits `Complex`, whose serialized wire form isn't knowable from the declaration alone.)
+
 **`Data.define` struct — bare member names as baseline:**
 
 ```ruby
@@ -193,7 +429,7 @@ exposes :integrations, type: Array, of: IntegrationRecord
 
 ```ruby
 exposes :integrations, type: Array, of: IntegrationRecord do
-  field :status, type: String, inclusion: { in: %w[connected error needs_reconnect] }
+  field :status, type: String, inclusion: %w[connected error needs_reconnect]
   field :active, type: :boolean, optional: true
 end
 ```
@@ -206,7 +442,7 @@ end
     "required": ["status"],
     "properties": {
       "status":        { "type": "string", "enum": ["connected", "error", "needs_reconnect"] },
-      "active":        { "type": "boolean" },
+      "active":        { "type": ["boolean", "null"] },
       "source":        {},
       "provider_name": {}
     }
@@ -221,7 +457,9 @@ Annotated members are fully typed; unannotated `Data.define` members (`source`,
 When using `model: true`, the schema automatically generates an `_id` field with an appropriate description:
 
 ```ruby
-class UpdateUser < Axn::MCP::Tool
+class UpdateUser
+  include Axn
+
   description "Update a user's profile"
 
   expects :user, model: true
@@ -239,17 +477,22 @@ Generates schema:
 {
   "properties": {
     "user_id": {
-      "type": "integer",
-      "description": "ID of the User record"
+      "description": "ID of the User record",
+      "not": { "type": "null" }
     }
   }
 }
 ```
 
+The generated id field's JSON type is intentionally left unconstrained — a model's primary key isn't
+knowable from the declaration (it could be an integer, UUID, string, etc.), and inferring it would
+require a database lookup. A required model field's id still forbids `null` (a null token can never
+resolve to a record).
+
 ### Enums via Inclusion
 
 ```ruby
-expects :status, inclusion: { in: %w[active inactive pending] }
+expects :status, inclusion: %w[active inactive pending]
 ```
 
 Generates:
@@ -263,110 +506,110 @@ Generates:
 }
 ```
 
-### Annotations
+## Annotations
 
-Use convenience methods or the `annotations` DSL:
+Declare `axn` core's generic `semantic_hints` DSL (`semantic_hints :read_only, :idempotent, ...`) on your Axn, and `Axn::MCP.wrap` maps them to MCP annotations automatically. This gem registers `:open_world`/`:closed_world` as additional semantic hints (via `Axn::Extensions.config.register_semantic_hint` — no core change needed for MCP-only vocabulary):
+
+| Declared `semantic_hints` | Default 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` |
 
 ```ruby
-class ReadOnlyTool < Axn::MCP::Tool
+class FetchData
+  include Axn
   description "Fetch data without side effects"
-  read_only!
-
-  # ...
-end
-
-class DangerousTool < Axn::MCP::Tool
-  description "Delete all the things"
-  destructive!
-  idempotent!
-
+  semantic_hints :read_only, :closed_world
+  # Axn::MCP.wrap(FetchData) => annotations include read_only_hint: true, destructive_hint: false, open_world_hint: false
   # ...
 end
+```
 
-class CustomAnnotations < Axn::MCP::Tool
-  annotations(
-    read_only_hint: true,
-    idempotent_hint: true,
-    title: "My Custom Tool",
-  )
+For anything `semantic_hints` doesn't cover (a custom annotation `title`, or an annotation with no corresponding hint), set `annotations` directly — either as a `wrap` kwarg or via `configure(:mcp)` (the latter survives `Axn::MCP.tools`). Precedence: `wrap` kwarg → `configure(:mcp)` → the `semantic_hints`-derived default.
 
-  # ...
+```ruby
+# At wrap time:
+Axn::MCP.wrap(MyAxn, annotations: { read_only_hint: true, idempotent_hint: true, title: "My Custom Tool" })
+
+# Or declaratively (picked up by Axn::MCP.tools):
+class MyAxn
+  include Axn
+  tool :mcp
+  configure(:mcp) { |c| c.annotations = { read_only_hint: true, idempotent_hint: true, title: "My Custom Tool" } }
+  # …
 end
 ```
 
-Available shortcuts:
+## Title, Icons, and Metadata
 
-
-| Method          | Effect                                            |
-| --------------- | ------------------------------------------------- |
-| `read_only!`    | `read_only_hint: true`, `destructive_hint: false` |
-| `destructive!`  | `destructive_hint: true`, `read_only_hint: false` |
-| `idempotent!`   | `idempotent_hint: true`                           |
-| `open_world!`   | `open_world_hint: true`                           |
-| `closed_world!` | `open_world_hint: false`                          |
-
-
-### Factory-Style Definition
-
-For quick one-off tools:
+`::MCP::Tool` supports `title`/`icons`/`meta` alongside `description`/`annotations`. Set them either as `wrap` kwargs, or declaratively on the Axn via `configure(:mcp)` — the latter survives the zero-arg `Axn::MCP.tools` path (which calls `wrap` with no kwargs), so it's how you attach this metadata to a registry-enumerated tool. An explicit `wrap` kwarg wins over the `configure(:mcp)` value; both are omitted (left at `::MCP::Tool`'s own defaults) unless set.
 
 ```ruby
-SearchTool = Axn::MCP::Tool.define(
+# At wrap time:
+Axn::MCP.wrap(
+  SearchAxn,
   description: "Search for items",
-  expects: { query: { type: String, description: "Search query" } },
-  exposes: { results: { type: Array } },
-  annotations: { read_only_hint: true },
-) do
-  expose results: Item.search(query)
+  title: "Item Search",
+  icons: [{ src: "https://example.com/icon.png", mimeType: "image/png" }],
+  meta: { version: "1.0" },
+)
+
+# Or declaratively (picked up by Axn::MCP.tools):
+class SearchAxn
+  include Axn
+  tool :mcp
+  configure(:mcp) do |c|
+    c.title = "Item Search"
+    c.icons = [{ src: "https://example.com/icon.png", mimeType: "image/png" }]
+    c.meta = { version: "1.0" }
+  end
+  # …
 end
 ```
 
-### Server Context
+## Server Context
+
+Server-injected **data** and server-side **capabilities** are two different things, reached two different ways.
+
+### Data — declare it on `ambient_context`
 
-`server_context` is automatically available in all tools (no declaration needed):
+A tool declares each value it needs directly on `ambient_context`, and reads it like any other input:
 
 ```ruby
-class AuthenticatedTool < Axn::MCP::Tool
+class AuthenticatedAction
+  include Axn
+
   description "Do something with the current user"
 
+  expects :user_id, on: :ambient_context, type: Object, optional: true
+
   def call
-    current_user = server_context&.dig(:user)
+    current_user = User.find(user_id) if user_id
     # ...
   end
 end
 ```
 
-Note the safe navigation (`&.dig`): `server_context` may be `nil` if the tool is invoked directly as a standard Axn action rather than through the MCP server.
+`Axn::MCP.wrap` passes the `server_context:` given to `.call` **as** the Axn's `ambient_context` (spread, not nested under a `server_context` key), and axn extracts each declared field from it via `#[]`/`#dig` — working whether the value is a plain `Hash` (direct/test calls) or an `MCP::ServerContext` object (a real-server round-trip). This is deliberately generic: the *same* Axn resolves `user_id` from the MCP server context here, from `ActiveSupport::CurrentAttributes` on a direct call, and from whatever `Axn::RubyLLM.wrap` provides — no MCP-specific `server_context` intermediate to declare, so the class stays reusable across adapters (the whole point of `ambient_context`).
 
-The `server_context` field is excluded from the generated `inputSchema` since it's injected by the MCP server, not provided by the LLM.
+`on: :ambient_context` fields are excluded from `inputSchema` automatically (not via a hand-rolled list), and the explicit ambient context `wrap` passes **replaces** any process-wide `Current`-derived default for that call — so no server-side state leaks into an MCP invocation, and the field is `nil` when the Axn is called directly with none provided.
 
-### Dual-Use: MCP Server vs Direct Invocation
+### Capabilities — `Axn::MCP.server_context`
 
-Tools automatically adapt their return type based on how they're called:
+Over a real `MCP::Server`, the context also offers session-scoped operations that talk back to the client — `report_progress`, `cancelled?`, etc. Those are transport **capabilities**, not data: they live on the `MCP::ServerContext` object itself and don't survive `ambient_context`'s declared-key filtering. Reach the live object with **`Axn::MCP.server_context`** (an MCP-specific handle; `nil` outside a wrapped tool call):
 
 ```ruby
-# Called FROM MCP server (server_context injected) → returns MCP::Tool::Response
-# This happens automatically when registered with MCP::Server
-
-# Called DIRECTLY without server_context → returns Axn::Result
-result = MyTool.call(name: "Alice")
-if result.ok?
-  puts result.greeting
-else
-  puts "Error: #{result.message}"
+def call
+  Axn::MCP.server_context&.report_progress(50, total: 100, message: "Halfway done")
+  fail!("cancelled") if Axn::MCP.server_context&.cancelled?
+  # ...
 end
-
-# Or use call! to raise on failure
-result = MyTool.call!(name: "Bob")
-puts result.greeting
 ```
 
-The branching is based on presence of `server_context`:
-
-- **With `server_context`**: Returns `MCP::Tool::Response` (for MCP server compatibility)
-- **Without `server_context`**: Returns `Axn::Result` (standard Axn semantics)
-
-This allows you to test tools or call them from non-MCP contexts using standard Axn patterns.
+A tool using this is knowingly MCP-coupled — appropriate, since these operations are MCP-transport-only (there's no equivalent on a direct call, where `Axn::MCP.server_context` returns the raw value passed as `server_context:`, or `nil`). The exact method set is the `mcp` gem's own surface and evolves with it (check `MCP::ServerContext`'s source for your installed version — some methods there are themselves SDK-deprecated); consult it directly rather than treating any list here as authoritative.
 
 ## Error Handling
 
@@ -381,13 +624,71 @@ def call
 end
 ```
 
+The MCP error response carries the Axn's own `result.error` — the gem imposes no headline of its own:
+
+| Failure                                  | Text shown to the LLM   |
+| ----------------------------------------- | ----------------------- |
+| `fail! "User not found"`                  | `"User not found"`      |
+| An `expects` (inbound argument) violation — missing, wrong-type, undeclared | The specific violation, e.g. `"Limit is not a Integer"`, `"unknown input: extra"` — see [Tool call contract](#tool-call-contract). Not reported to `on_exception`. |
+| Bare `fail!`, an `ambient_context`/`exposes` (outbound) violation, or an unhandled exception | `"Something went wrong"` (axn's generic default). Reported to `on_exception`. |
+
+Want a friendlier generic message than `"Something went wrong"`? Declare your own base `error "..."`
+on the Axn (standard axn practice) — it's per-tool, so each tool can say something specific:
+
+```ruby
+class ChargeCard
+  include Axn
+  error "Could not charge the card"
+  # a bare fail! / validation error / exception now surfaces "Could not charge the card"
+end
+```
+
+With a base `error` declared, an explicit `fail!("reason")` **combines** rather than replaces — by default the base prefixes the reason: `fail!("card declined")` → `"Could not charge the card: card declined"`. (A bare `fail!`, validation error, or exception still surfaces the base alone.) To emit a specific reason *without* the prefix, opt out per-call with `fail!("card declined", standalone: true)` → `"card declined"`. So the table above (reason shown verbatim) reflects a tool with **no** base `error`; add one and reasons are prefixed unless `standalone:`.
+
 Unhandled exceptions are also caught automatically. When an exception occurs:
 
 1. The error is recorded on the result
 2. Any configured `on_exception` handlers are triggered (see [Axn configuration](https://github.com/teamshares/axn))
 3. An `MCP::Tool::Response` is returned with `error: true`
 
-Both `fail!` calls and unhandled exceptions result in error responses to the LLM.
+## Success response text: config and per-tool
+
+By default, successful responses contain a text block with the JSON-serialized `structured_content` (a SHOULD per [MCP spec](https://modelcontextprotocol.io/specification/draft/server/tools#structured-content)). To use the Axn success message instead, set **gem-wide config** once (`Axn::MCP.config.present_as = :message`), override **per tool** via `configure(:mcp)`, or pass it to `wrap`. Valid values are `:structured` (default) and `:message`. Precedence (most local wins): `wrap`'s `present_as:` kwarg → the Axn's own `configure(:mcp)` override → the gem-wide config.
+
+```ruby
+# per-tool, on the Axn:
+class MyAction
+  include Axn
+  configure(:mcp) { |c| c.present_as = :message }
+end
+
+# or at wrap time:
+Axn::MCP.wrap(MyAction, present_as: :message)
+```
+
+`configure(:mcp)` uses axn core's namespaced config DSL. The same base Axn can be composed with another adapter (e.g. an `axn-ruby_llm` gem) via its own `config_namespace` — each adapter's settings live in their own namespace, so `configure(:mcp)` and `configure(:other_adapter)` on the same class never collide.
+
+## Rejecting opaque exposed values (`reject_opaque_exposed_values`)
+
+When a successful result's `exposes` values are serialized into the response, most values have an obvious JSON form (a `String`, a `Hash`, a `Data.define`, …). But an exposed value can be **opaque** — it has no JSON rendering *its author declared*, so it falls back to a generic one that leaks Ruby internals: a bare object serializes to the string `"#<User:0x000055…>"`, and in a Rails app ActiveSupport's generic `as_json` instead dumps the object's instance variables. Concretely, a value is opaque when its only `to_s` is the one inherited from `Object` and it defines no `to_h`/`to_hash`/custom `as_json` — i.e. it never told the serializer how it wants to look as JSON.
+
+`reject_opaque_exposed_values` decides what happens when that occurs:
+
+- **`false` (default)** — the opaque rendering ships. For an LLM tool result an ugly-but-honest string is usually better than a failed call, so this is the default.
+- **`true`** — the value is rejected: instead of shipping the blob, the call returns an error response and reports the failure via axn's `on_exception` (with the exact path, e.g. `records[3].owner`, for your logs/error tracker). Use it when a leaked `#<…>` string in a result is worse than a failed call. (See [Never-raises contract](#never-raises-contract) for how the raise becomes an error response.)
+
+Set it **gem-wide** (`Axn::MCP.config.reject_opaque_exposed_values = true`) or **per tool** via `configure(:mcp)`; the per-class value wins over the gem-wide one.
+
+```ruby
+class ListOwners
+  include Axn
+  tool :mcp
+  configure(:mcp) { |c| c.reject_opaque_exposed_values = true }
+  # ...
+end
+```
+
+**Scope — this is an output-side check only.** It governs `exposes` serialization, *not* inbound argument handling (that's [`coerce:`](#coercing-loosely-typed-inbound-values-with-coerce)). And it is *narrow*: it toggles only the extra "was this rendering author-declared?" test. Values with no **honest** JSON form at all — a reference cycle, a non-finite `Float` (`Infinity`/`NaN`), bytes with no UTF-8 rendering, or two `Hash` keys that collapse to one property — always fail the call regardless of this setting (surfaced the same way: an error response + an `on_exception` report), because shipping them would produce a wrong or malformed body. `reject_opaque_exposed_values` only additionally rejects the *honest-but-undeclared* rendering above.
 
 ## Integration with MCP Server
 
@@ -400,7 +701,7 @@ require "axn-mcp"
 server = MCP::Server.new(
   name: "my-server",
   version: "1.0.0",
-  tools: [GreetUser, CreateNote, SearchTool],
+  tools: Axn::MCP.tools,              # or an explicit list: [GreetUserTool, SearchTool, ...]
 )
 
 # Use with stdio transport
@@ -410,15 +711,30 @@ transport.open
 
 For complete server setup, transport options, and advanced configuration, see the [MCP Ruby SDK documentation](https://github.com/modelcontextprotocol/ruby-sdk).
 
-### Success response text: config and per-tool
-
-By default, successful responses contain a text block with the JSON-serialized `structured_content` (a SHOULD per [MCP spec](https://modelcontextprotocol.io/specification/draft/server/tools#structured-content)). To use the Axn success message instead, set **central config** once (`Axn::MCP.config.mcp_text_content = :message`) or override **per tool** with `mcp_text_content :message`. Valid values are `:structured` (default) and `:message`; per-tool overrides config.
+## Divergences from the raw MCP SDK
+
+`Axn::MCP.wrap` covers the **full `MCP::Tool` configuration surface** — `tool_name`, `title`,
+`description`, `icons`, `inputSchema`, `outputSchema`, tool-level `_meta`, and every annotation hint
+(`read_only_hint`/`destructive_hint`/`idempotent_hint`/`open_world_hint` + annotation `title`) — plus
+`server_context` routing and `MCP::ServerContext`'s session capabilities (`report_progress`,
+`cancelled?`, …). Two `MCP::Tool::Response` **output** affordances are intentionally *not* mapped,
+because an Axn's model is typed structured I/O:
+
+- **Non-text content.** A wrapped tool's response is always a single text block plus
+  `structuredContent` (the JSON of your `exposes`). Image / audio / embedded-resource content
+  (`MCP::Content::Image` / `Audio` / `EmbeddedResource`) and multi-block content are not produced —
+  an Axn has no convention for declaring "this exposed value is binary/media." For a tool that must
+  return media content, register a hand-written `MCP::Tool` directly and splat it alongside
+  `Axn::MCP.tools` (see [Mixing with native tools](#mixing-with-native-mcptool-tools)).
+- **Response-level `_meta`.** The per-response `_meta` channel isn't populated — there's no Axn
+  convention for per-call response metadata; your `exposes` become `structuredContent`. (Tool-*definition*
+  `_meta`, in the tools/list entry, *is* supported — via `wrap`'s `meta:` kwarg.)
 
 ## Requirements
 
 - Ruby >= 3.2.1
-- [axn](https://github.com/teamshares/axn) >= 0.1.0-alpha.4.3
-- [mcp](https://github.com/modelcontextprotocol/ruby-sdk) >= 0.4
+- [axn](https://github.com/teamshares/axn) >= 0.1.0-alpha.6, < 0.2.0
+- [mcp](https://github.com/modelcontextprotocol/ruby-sdk) >= 0.5.0, < 2.0 — the floor is `0.5.0`, the first SDK version with the `icons` setter (and full JSON-Schema tool-schema handling, so conditional `allOf` constraints survive). Across that range the SDK varies in `server_context` shape (see [Server Context](#server-context)) and in how it surfaces a mid-serialization raise (a top-level JSON-RPC error vs. an `isError` tool result); this gem is written to be correct across all of it, not just the version you happen to have installed locally. The upper bound tracks the SDK's own semver: `1.0` declared its public API stable (breaking changes only in a future major), so `1.x` is in range.
 
 ## Development
 
@@ -428,6 +744,9 @@ bundle exec rspec
 bundle exec rubocop
 ```
 
+Working on this gem with a coding agent? Read [`AGENTS.md`](AGENTS.md) first (`CLAUDE.md` is a
+symlink to it).
+
 ## License
 
 MIT License. See [LICENSE](LICENSE) for details.
@@ -439,3 +758,43 @@ Bug reports and pull requests are welcome on GitHub at [https://github.com/teams
 ## Acknowledgments
 
 This gem wraps the excellent [MCP Ruby SDK](https://github.com/modelcontextprotocol/ruby-sdk) from the Model Context Protocol team.
+
+<!-- TEMPORARY: transitional upgrade guide — remove this section at 1.0 (tracked in DEPRECATIONS.md). -->
+## Upgrading from 0.1.x
+
+`0.2.0` re-architects the gem around author-once (a plain Axn exposed via `Axn::MCP.wrap` / `Axn::MCP.tools`) and retires the `Axn::MCP::Tool` subclass base. The migration is mechanical — mostly one-liners:
+
+| 0.1.x | 0.2.0 |
+| --- | --- |
+| `class T < Axn::MCP::Tool` … `end` | a plain Axn (`class T; include Axn; … end`), then `Axn::MCP.wrap(T)` |
+| `Axn::MCP::Tool.define(description:, expects:, exposes:, …) { … }` | `Axn::MCP.wrap(Axn::Factory.build(expects:, exposes:) { … }, name: "…", description: "…")` |
+| `mcp_text_content :message` / `Axn::MCP.config.mcp_text_content` | `present_as` (same `:structured`/`:message` values) — on `configure(:mcp)`, `Axn::MCP.config`, or `wrap(present_as:)` |
+| `Axn::MCP.config.error_headline = "…"` | declare a per-tool base `error "…"` on the Axn (MCP errors now surface `result.error`) |
+| `read_only!` / `destructive!` / `idempotent!` / `open_world` / `closed_world` | `semantic_hints :read_only, :open_world, …` on the plain Axn |
+| a hand-maintained `tools: [T1, T2, …]` array | `tool :mcp` on each Axn + `MCP::Server.new(tools: Axn::MCP.tools)` |
+
+The most common case, before and after:
+
+```ruby
+# 0.1.x
+class GreetUser < Axn::MCP::Tool
+  description "Greet a user"
+  expects :name, type: String
+  exposes :greeting, type: String
+  def call = expose(greeting: "Hello, #{name}!")
+end
+# registered as: tools: [GreetUser]
+
+# 0.2.0
+class GreetUser
+  include Axn
+  tool :mcp                       # opt into Axn::MCP.tools discovery
+  description "Greet a user"
+  expects :name, type: String
+  exposes :greeting, type: String
+  def call = expose(greeting: "Hello, #{name}!")
+end
+# registered as: tools: Axn::MCP.tools   # or explicitly: [Axn::MCP.wrap(GreetUser)]
+```
+
+The retired `Axn::MCP::Tool` / `.define` and the renamed `wrap(mcp_text_content:)` kwarg **raise** with migration messages rather than failing silently, so anything you miss surfaces loudly. See [`DEPRECATIONS.md`](DEPRECATIONS.md) for what's slated for removal at 1.0.