activeadmin_mcp 0.0.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5eb6b95afa3bf6d96a2ae33ced52621014f535f11542dcbee38b88638580e6a9
-  data.tar.gz: c87121826ee5e29805cfa9f3fd8faf1f5042698ec94d46c5fbd7bbc90f08b3f3
+  metadata.gz: 3c5af58e285dcddc7105564342dc34b55531810db4ed351b10d45a1e018ab9f4
+  data.tar.gz: 5b03712e5ea784179d552b670875183324135a9835d4bceead9301433f82e8a5
 SHA512:
-  metadata.gz: 6b7a903b975a980a23246e944b2e321fab7019ac218c06a51f6645a5e0d7577951cb4bdce9c4319e7184d9b5f031b96320ee874666b8d28c1814850cb59533b9
-  data.tar.gz: 3a069d2f4d7a69038f3f96153e67911472f43fabb64aa4fc7a3ccdb421684cd6cabd126d208fbe9671dc1fa7c7ecc7f2789d68638f4e84cfdcb78e45d90ddb7b
+  metadata.gz: cc3367de9915d2c12ac449a410328a553941341f76bfd2cf8b331c8f22a1cfb0a070f56a6990772ded10893ee1259af4d36f28defe6fc73cb52013a582f0c42e
+  data.tar.gz: 78b2f980db593f334e4349ede90bab1d264ab03796ebcbebc4673b79f30670eb9902e748c24b687f0d04250b64d36fbd2455644e7bce9dfddaaf33e9ad6d87b6

data/README.md

@@ -20,7 +20,11 @@ The server is a Rails engine mounted inside your application (by default at
   are the ones you have already configured.
 - **Queries use Ransack.** The `query` tool passes its arguments straight to
   [Ransack](https://activerecord-hackery.github.io/ransack/), the same search
-  library ActiveAdmin uses for filtering.
+  library ActiveAdmin uses for filtering. The tool calls `ransack` on the
+  model directly rather than going through an ActiveAdmin filter form, so on
+  Ransack 4 the model must allowlist the attributes it wants queryable via
+  `ransackable_attributes`; without that allowlist, `query` against that
+  resource will raise instead of returning an empty result.
 - **Reads go through ActiveAdmin too.** `list_resources` and `query` run through
   the same authorization adapter (CanCanCan, Pundit, etc.) as the authenticated
   MCP user: resources the user cannot read are hidden from the listing and
@@ -28,18 +32,21 @@ The server is a Rails engine mounted inside your application (by default at
   `scope_collection`, so the MCP user only ever sees the records they could see
   in the admin UI. With ActiveAdmin's default adapter every check passes, so
   applications without an authorization adapter are unaffected.
-- **Writes go through ActiveAdmin.** The `update` tool only writes fields
-  allowed by the resource's `permit_params`, refuses resources that don't
-  register the `update` action, and runs every change through your
-  authorization adapter as the authenticated MCP user.
+- **Writes go through ActiveAdmin.** The `create` and `update` tools dispatch
+  the resource's real ActiveAdmin controller action, so `permit_params`, your
+  `before_save`/`after_update` callbacks, the controller's `before_action`
+  chain and your authorization adapter all apply exactly as they do when
+  someone clicks Save in the admin UI. Resources that don't register the
+  action are refused, and `describe_form` will tell a client what a given
+  resource's form accepts before it tries.
 - **Authentication is optional but built in.** Enable Bearer-token auth and the
   installer adds an "MCP Tokens" management page to your ActiveAdmin panel.
 
 ## Requirements
 
-- Ruby >= 3.0
-- Rails >= 6.1
-- ActiveAdmin >= 2.0
+- Ruby >= 4.0
+- Rails >= 7.2
+- ActiveAdmin ~> 3.5
 
 ## Installation
 
@@ -65,34 +72,323 @@ read/query setup without authentication.
 |------|-------------|
 | `list_resources` | List the ActiveAdmin resources the current user may read, along with their attributes. |
 | `query` | Query a resource the current user may read, using Ransack syntax, scoped to the records they may access (`limit` defaults to 25, capped at 100). |
-| `update` | Update an existing record, honouring ActiveAdmin's permitted params and authorization. |
+| `create` | Create a new record through the resource's ActiveAdmin create action, honouring its permitted params, callbacks and authorization. |
+| `update` | Update an existing record through the resource's ActiveAdmin update action, honouring its permitted params, callbacks and authorization. |
+| `describe_form` | Describe the fields of a resource's form — input types, labels, hints, allowed values, column types and which are required — so a `create` or `update` call need not guess them. |
+| *(per action)* | Any ActiveAdmin member, collection or batch action the application has opted in with an `mcp:` option, exposed as its own tool. |
+
+The examples below are drawn from the application the end-to-end suite builds
+and drives over HTTP, which is checked in under
+[`spec/e2e/fixture_app/`](spec/e2e/fixture_app/): `Post` permits `title` and
+`body` but not `slug`, `Author` is registered `actions :index, :show`, `Review`
+declares its own form block, and `Tag` declares no `permit_params` at all. Most
+of what this README claims is asserted against that running application in
+[`spec/e2e/`](spec/e2e/), so a claim here can be read next to the example that
+exercises it.
 
 ### Query examples
 
 ```
-Query users whose email contains "example.com"
-→ query(resource: "User", q: { email_cont: "example.com" })
+Find the post whose title mentions Earthsea
+→ query(resource: "Post", q: { title_cont: "Earthsea" })
 
-Find active posts created since the start of the month
-→ query(resource: "Post", q: { status_eq: "active", created_at_gt: "2026-08-01" })
+Find draft posts created since the start of the month
+→ query(resource: "Post", q: { status_eq: "draft", created_at_gt: "2026-08-01" })
+
+Look an author up by email
+→ query(resource: "Author", q: { email_eq: "ursula@example.com" })
 ```
 
-### Updating records
+### Creating and updating records
 
 ```
-Update a user's name
-→ update(resource: "User", id: 42, attributes: { name: "New name" })
+Create a post
+→ create(resource: "Post", attributes: { title: "Mort", body: "The fourth." })
+
+Retitle a post
+→ update(resource: "Post", id: 42, attributes: { title: "Pyramids" })
 ```
 
-The `update` tool applies the same rules as the ActiveAdmin UI:
+Both tools dispatch the resource's own ActiveAdmin `create` or `update`
+action, so a write from MCP is the same write the admin UI makes:
 
-- **Editable resources only** — resources registered without the `update`
-  action (e.g. `actions :index, :show`) are refused.
-- **Authorization** — the change runs through the resource namespace's
-  authorization adapter for the authenticated MCP user, so it can only update
-  what that user is allowed to update in admin.
+- **Registered actions only** — resources registered without the action
+  (e.g. `Author`, registered `actions :index, :show`) are refused.
+- **Authorization** — the write runs through the resource namespace's
+  authorization adapter for the authenticated MCP user, both before dispatch
+  and again inside the controller, so it can only write what that user is
+  allowed to write in admin.
 - **Permitted fields only** — attributes are filtered through the resource's
-  `permit_params`; fields the admin form doesn't accept are silently dropped.
+  `permit_params`; fields the admin form doesn't accept are silently dropped,
+  so a `slug` sent to a `Post` permitting only `title` and `body` never
+  reaches the record. A resource that declares no `permit_params` at all (like
+  `Tag`) is refused outright, with a message saying so — ActiveAdmin cannot
+  write such a resource through its own forms either. A block-form
+  `permit_params` is evaluated in controller context as the authenticated MCP
+  user, so a block varying the writable set by user gets the same answer it
+  would give that user in admin.
+- **Your callbacks run** — ActiveAdmin's `before_build`, `before_create`,
+  `before_save`, `after_update` and friends all fire, because the controller
+  action is what fires them. A `before_create` that fills in a `slug` the form
+  never accepted still fills it in.
+
+A write rejected by the model comes back as a `Validation failed` error with
+the model's own messages in `details`, and nothing is written.
+
+### Describing a form
+
+```
+What can I set when writing a review?
+→ describe_form(resource: "Review")          # source: "form"
+
+What can I set when creating a post?
+→ describe_form(resource: "Post")            # source: "permit_params"
+→ describe_form(resource: "Post", action: "edit")
+```
+
+`describe_form` reads the resource's own `form do ... end` block when it
+declares one, reporting each input's `as:`, `label:`, `hint:` and — when the
+`collection:` is a literal array — its allowed values. `Review` declares one,
+so its `status` comes back as a `select` labelled "Moderation status" with
+`["pending", "approved"]` as its allowed values. Resources that declare
+no form block get a description derived from their `permit_params` instead:
+ActiveAdmin renders a bare `f.inputs` for those, which Formtastic only expands
+at render time, so there is nothing to read. The response's `source` says which
+of the two you are looking at.
+
+Either way every field is annotated from the model with the column type it is
+stored in and whether the model validates its presence. An associated record's
+fields — declared with `has_many`, or with `inputs for: :author` — are reported
+under `nested` rather than flattened in with the record's own, because a write
+against the parent would drop them.
+
+A form block that declares no inputs of its own is described from
+`permit_params` too. A bare `f.inputs` is legal, and Formtastic only expands it
+against the model at render time, so there is nothing in the block to read.
+
+`action:` selects the gate, not the shape — ActiveAdmin uses one form block for
+both. `"new"` (the default) requires the resource to register `create` and pass
+`create` authorization; `"edit"` requires `update`. Describing a form you could
+never submit tells you nothing you can act on, so it is refused with the same
+messages `create` and `update` use: `Author` is not creatable, and `Tag`
+declares no permitted params.
+
+Two limits worth knowing:
+
+- A `collection:` that is an `ActiveRecord::Relation` or a proc is omitted
+  rather than evaluated. Describing a form should not fire a query, and a
+  relation can be arbitrarily large. Use an action's
+  [`suggestions:`](#running-member-collection-and-batch-actions) when you want
+  dynamic values.
+- A field a form block declares but `permit_params` omits is described and then
+  silently dropped on write. This cannot arise on the `permit_params` fallback
+  path.
+- On the `permit_params` fallback path, only fields backed by a database column
+  are reported. ActiveAdmin keeps no list of the params it permits — only a
+  method that filters against them — so the names are recovered by offering it
+  every column the model has and seeing which survive. Permitted params that
+  are not columns, such as `tag_ids` or a nested `*_attributes` key, are
+  therefore missing from the description even though `create` and `update`
+  will accept them.
+
+### Running member, collection and batch actions
+
+ActiveAdmin actions are **not** exposed by default. An action becomes an MCP
+tool only when you add an `mcp:` option to it:
+
+```ruby
+ActiveAdmin.register Post do
+  member_action :publish, method: :post, mcp: {
+    description: "Publish a post with the given visibility",
+    params: {
+      visibility: { type: :string, required: true,
+                    enum: %w[public unlisted],
+                    hint: "Who can see the post once published" }
+    }
+  } do
+    # your existing action body, unchanged by opting in
+    resource.update!(status: params[:visibility])
+    redirect_to resource_path(resource), notice: "Published"
+  end
+
+  # No mcp: key, so this one is not a tool — not listed, and refused by name.
+  member_action :archive, method: :post do
+    resource.update!(status: "archived")
+    redirect_to resource_path(resource), notice: "Archived"
+  end
+end
+```
+
+That registers a `post_publish` tool, and no `post_archive` tool. Batch actions
+opt in the same way, and inherit their param types from the `form:` hash you
+already declare:
+
+```ruby
+batch_action :set_status, form: { status: :text },
+                          mcp: { description: "Set the status on the selected posts" } do |ids, inputs|
+  Post.where(id: ids).update_all(status: inputs["status"])
+end
+```
+
+That registers a `post_set_status` tool taking an `ids` array alongside the
+`status` string it took from `form:`.
+
+**Declaring params**
+
+- `type:` — one of `:string`, `:integer`, `:number`, `:boolean`, `:array`, `:object`.
+- `required:` — refuses the call when the value is missing.
+- `hint:` — static guidance shown to the agent. Always a plain string.
+- `enum:` — **binding**. A value outside the list is refused before dispatch.
+- `suggestions:` — a proc evaluated when tools are listed, e.g.
+  `suggestions: -> { Post.distinct.pluck(:status) }`. **Advisory only**, never
+  enforced, so use it for live values from the database. If it raises, the tool
+  is still listed without suggestions.
+
+On a batch action, every declared param must also appear in the action's `form:`
+hash. ActiveAdmin slices submitted inputs down to the declared `form:` keys
+before calling the block, so a param declared only under `mcp:` would be
+advertised to the client and then dropped; the declaration is refused instead.
+
+**Authorization**
+
+`permission:` is an *additional* gate, never a replacement. Every call first
+passes your ActiveAdmin authorization adapter exactly as `query` and `update`
+do; the proc can only narrow access further, never widen it. It is evaluated in
+controller context, so `current_admin_user`, `can?` and the usual admin helpers
+are available. Return `false` to refuse, or a `String` to refuse with a reason
+the agent can act on.
+
+```ruby
+# Takes the record, so it can only be resolved when the call arrives.
+member_action :feature, method: :post, mcp: {
+  description: "Feature a published post on the front page",
+  permission: ->(post) { post.status == "draft" ? "Only a published post can be featured" : true }
+} do
+  resource.update!(status: "featured")
+end
+
+# Takes no arguments, so it is resolved when tools are listed.
+collection_action :purge_drafts, method: :post, mcp: {
+  description: "Purge every draft post",
+  permission: -> { current_admin_user&.editor? }
+} do
+  redirect_to collection_path, notice: "Purged"
+end
+```
+
+Tools are also listed per user: an action whose resource the adapter refuses is
+left out of `tools/list` entirely, and a `permission:` proc that takes no
+arguments is evaluated at listing time (in the same controller context) so the
+tool is hidden rather than offered and then refused. A proc that takes the
+record cannot be resolved without one, so `post_feature` stays advertised and
+refuses at call time with the string the proc returned.
+
+For **batch actions** the adapter check is necessarily resource-level — there is
+no single record to authorize — so it is `authorized?(:<action>, YourModel)`
+rather than a per-record policy evaluation. To stop that being a hole, the ids
+the client submits are run back through the adapter's `scope_collection`, and
+the whole call is refused if any of them falls outside the scope. Nothing is
+narrowed silently: the call either acts on every id you asked for or on none.
+
+One caveat on authentication. Dispatch neutralises the namespace's
+`authentication_method` callback, because the MCP request has already
+authenticated by bearer token and that callback would otherwise redirect to a
+login page. If your `authentication_method` is a *combined* authentication-and-
+authorization method — one that also, say, rejects non-superusers — then
+neutralising it disables that authorization half too. Resource-level
+authorization still runs through the adapter, but the "we only skip
+authentication" framing is not universal; keep authorization in the adapter,
+not in the authentication callback.
+
+**What you get back**
+
+Actions are executed through your real ActiveAdmin controller, so the action's
+`before_action` chain, authorization and callbacks all run. The tool returns the
+response status, the redirect target and any flash messages — not the rendered
+HTML. An action whose body raises comes back as a generic `Post#publish failed`
+naming the resource and action, with the exception's own message — which can
+carry SQL, table names and file paths — kept away from the client.
+
+Redirect-style (submit-side) actions are the supported case; a `GET` action that
+renders a full admin view is best-effort and may fail for want of a view
+context.
+
+### Actions declared somewhere you can't add `mcp:`
+
+An action declared by a shared concern, or by another gem, has no declaration
+you can hang an `mcp:` key on — and if it did, every resource including it
+would get the same description, params and `permission:` proc. Annotate it by
+name from the registration instead, with `mcp_action`:
+
+```ruby
+module Flaggable
+  def self.included(dsl)
+    dsl.send(:member_action, :flag, method: [:post, :delete]) { ... }
+    dsl.send(:batch_action, :flag, form: proc { { reason: :text } }) { |ids, inputs| ... }
+  end
+end
+
+ActiveAdmin.register Volunteer do
+  include Flaggable
+
+  mcp_action :flag, kind: :batch, tool_name: "volunteer_bulk_flag",
+    description: "Flag the selected volunteers",
+    params: { reason: { type: :string, required: true } }
+
+  mcp_action :flag, kind: :member, tool_name: "volunteer_flag",
+    description: "Flag a volunteer",
+    params: { reason: { type: :string, required: true } }
+
+  mcp_action :flag, kind: :member, http_verb: :delete, tool_name: "volunteer_unflag",
+    description: "Remove a volunteer's flag"
+end
+```
+
+`mcp_action` takes everything `mcp:` takes, plus:
+
+| Option | Meaning |
+|--------|---------|
+| `kind:` | `:member`, `:collection` or `:batch`. Optional; needed only when one name belongs to more than one action, which is refused rather than guessed. |
+| `tool_name:` | The MCP tool name, in place of the derived `<resource>_<action>`. |
+| `http_verb:` | Which verb to dispatch, for an action declared with several (`method: [:post, :delete]`). A verb the action does not answer to is a declaration error. |
+
+It **annotates**; it never declares. Naming an action the resource does not
+have warns and skips. It is resolved when the tool list is built, not when it
+is called, so it may appear above or below the `include`.
+
+An annotation **replaces** an inline `mcp:` declaration rather than merging
+into it, so a shared generic declaration and a per-resource one cannot
+half-combine into something neither author wrote.
+
+An action may carry more than one annotation, each producing its own tool —
+which is how an action answering to two verbs, one undoing the other, becomes
+two tools.
+
+**Opting in is still per resource.** Two resources including the same concern
+share the actions, not the exposure: whichever does not annotate exposes
+nothing.
+
+**Names must not collide.** A tool name carries no kind, so a `member_action`
+and a `batch_action` of the same name derive the same one. Rather than let one
+silently shadow the other, both are hidden until a `tool_name:` tells them
+apart.
+
+**Batch actions declared with a String title** — the ones applications generate
+in loops from data — may be annotated by that title, rather than by the symbol
+ActiveAdmin derives from it by titleizing and underscoring, which can carry
+punctuation. The derived tool name has that punctuation squeezed out.
+
+**ActiveAdmin's `:if` proc is honoured.** A batch action the admin UI hides
+because its `:if` refuses is neither listed nor runnable over MCP. ActiveAdmin
+itself consults `:if` only when rendering, so this is stricter than ActiveAdmin
+is — deliberately: MCP should not be the way round a gate the admin enforces by
+not offering the button. A proc that raises, typically because it reads request
+state a tool listing cannot supply, hides the tool and says so in the log.
+
+**A proc `form:` is evaluated** in controller context, the way ActiveAdmin
+evaluates it, so a batch action whose form varies by resource still contributes
+its param types. Like `suggestions:`, this runs application code, and is never
+evaluated for a user the resource's authorization adapter refuses.
 
 ## Connecting a client
 
@@ -231,16 +527,20 @@ npx @anthropic-ai/mcpb pack . ../activeadmin-mcp.mcpb
 ```
 
 That writes `activeadmin-mcp.mcpb` (a zip of `manifest.json`, `package.json` and
-`server/index.js`) to the repository root, ready to distribute. Bump `version`
-in **both** `mcpb/manifest.json` and `mcpb/package.json` before packing a
-release — Claude Desktop uses the manifest version to detect upgrades.
+`server/index.js`) to the repository root. You do not bump the bundle's
+`version` by hand: publishing a GitHub Release writes the release tag into
+`mcpb/manifest.json` and `mcpb/package.json`, packs the bundle from that, and
+attaches `activeadmin-mcp-<version>.mcpb` to the release — so the bundle
+version Claude Desktop uses to detect upgrades always matches the gem version.
+See [RELEASING.md](RELEASING.md).
 
-CI packs the bundle on every push and attaches it as a build artifact, so you
-can also download a build from the Actions tab rather than packing it yourself.
+So the bundle for any released version is on that release's page, and CI packs
+the bundle on every push and attaches it as a build artifact if you want an
+unreleased build from the Actions tab.
 
-Distribute the file however suits you: an internal file share, a GitHub release
-asset, or an S3 bucket. Anyone with the file can install it, but it is inert
-without a token.
+Distribute the file however suits you — pointing colleagues at the release
+asset, an internal file share, or an S3 bucket. Anyone with the file can
+install it, but it is inert without a token.
 
 ### Installing
 
@@ -284,7 +584,10 @@ installed bundle simply starts reporting an authentication failure.
 ## Configuration
 
 The generator writes an initializer to
-`config/initializers/activeadmin_mcp.rb`:
+`config/initializers/activeadmin_mcp.rb` carrying every option below,
+commented out. Running it with `--auth devise_token` uncomments the
+authentication method for you, so the first edit is usually just naming your
+Devise model:
 
 ```ruby
 ActiveadminMcp.configure do |config|
@@ -344,6 +647,44 @@ bundle install
 bundle exec rspec
 ```
 
+### Running the tests
+
+`bundle exec rspec` (or `rake spec`, the default rake task) runs the unit
+suite only — it's fast, and it's what CI's `rspec` job runs. It never touches
+`spec/e2e`; that directory is excluded via `.rspec`.
+
+The end-to-end suite lives in `spec/e2e` and runs separately:
+
+```bash
+bundle exec rake e2e
+```
+
+This generates a real Rails 7.2 + ActiveAdmin + Devise application under
+`tmp/e2e_app`, installs the gem into it with `path:`, boots it under Puma,
+and drives it over real HTTP with a minimal JSON-RPC client — the same way
+Claude Code or any other MCP client would. It's how the gem is tested
+against ActiveAdmin's and Ransack's actual behaviour rather than mocks.
+
+The registrations, models, migrations and seeds that application uses are
+checked in under [`spec/e2e/fixture_app/`](spec/e2e/fixture_app/) rather than
+written from heredocs, and they are the `Post`, `Author`, `Review` and `Tag`
+this README's examples are written against — so a claim above can be read next
+to both the registration it describes and the example that exercises it.
+[`spec/e2e/fixture_app/README.md`](spec/e2e/fixture_app/README.md) says which
+claim each fixture exists to support.
+
+The generated application is expensive to build (a full `bundle install`
+against rubygems.org, and a `gem install rails` if Rails 7.2.2.2 isn't
+already on your system) so it's cached in `tmp/e2e_app` between runs, keyed
+on the contents of `spec/e2e/support/app_builder.rb`. The first run costs a
+few minutes and needs network access; edit that file and the next run
+rebuilds from scratch, otherwise reruns are quick. Force a rebuild without
+editing anything by setting `E2E_REBUILD=1`:
+
+```bash
+E2E_REBUILD=1 bundle exec rake e2e
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub.

data/app/controllers/activeadmin_mcp/mcp_controller.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module ActiveadminMcp
   class McpController < ActionController::API
     before_action :authenticate_mcp_token!

data/app/models/activeadmin_mcp/api_token.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 require "digest"
 require "securerandom"
 

data/config/routes.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 ActiveadminMcp::Engine.routes.draw do
   post "/", to: "mcp#call"
 end

data/lib/activeadmin_mcp/action_catalog.rb

@@ -0,0 +1,165 @@
+module ActiveadminMcp
+  # Finds every ActiveAdmin action an application has opted in to MCP.
+  #
+  # Nothing is cached: ActiveAdmin reloads resources in development, and a
+  # stale catalog would advertise tools that no longer exist.
+  module ActionCatalog
+    # Tool names the engine reserves for itself, including names Phase 2 and 3
+    # will take, so an application cannot silently shadow one later.
+    RESERVED = %w[list_resources query update create describe_form].freeze
+
+    class << self
+      # The authenticated user is carried through so a batch action's `form:`
+      # proc can be evaluated in controller context, the way ActiveAdmin
+      # evaluates it. Nothing here evaluates it — see ActionDefinition#params,
+      # which does, lazily, once the caller has authorized the action.
+      def all(current_user: nil)
+        without_colliding_names(
+          ResourceRegistry.resources.flat_map do |entry|
+            definitions_for(entry[:config], current_user)
+          end
+        )
+      end
+
+      def find(tool_name, current_user: nil)
+        all(current_user: current_user).find { |definition| definition.tool_name == tool_name }
+      end
+
+      private
+
+      # A tool name carries no kind, so a member and a batch action of the same
+      # name derive the same one — which ActiveAdmin allows, and a shared
+      # concern declaring both is how it happens in practice. Advertising a
+      # duplicate would leave whichever the catalog found second permanently
+      # unreachable, since find returns the first match. Refuse both instead,
+      # and say which name, so the declaration can choose a tool_name.
+      def without_colliding_names(definitions)
+        definitions.group_by(&:tool_name).flat_map do |tool_name, sharing|
+          next sharing if sharing.one?
+
+          warn_and_skip("#{sharing.length} actions would both be called #{tool_name}; " \
+                        "give all but one an explicit tool_name:")
+          []
+        end
+      end
+
+      def definitions_for(config, current_user = nil)
+        annotated, inline = partition_declarations(config)
+
+        (annotated + inline).filter_map do |action, kind, options|
+          definition = ActionDefinition.new(
+            config: config, action: action, kind: kind, options: options, current_user: current_user
+          )
+
+          next warn_and_skip(definition.errors.join("; ")) unless definition.valid?
+          next warn_and_skip("#{definition.tool_name} collides with a built-in tool") if reserved?(definition)
+
+          definition
+        end
+      end
+
+      # Resolves each mcp_action annotation to the action it names, and leaves
+      # every unannotated action to its own inline mcp: declaration. An
+      # annotation replaces an inline declaration wholesale rather than merging
+      # into it: one declaration wins, and it is visible which.
+      def partition_declarations(config)
+        actions = candidates(config)
+        annotated = []
+        claimed = []
+
+        safe_annotations(config).each do |annotation|
+          matches = matching_actions(actions, annotation)
+
+          next warn_and_skip(annotation_missing(config, annotation)) if matches.empty?
+          next warn_and_skip(annotation_ambiguous(config, annotation)) unless matches.one?
+
+          action, kind = matches.first
+          claimed << action
+          annotated << [action, kind, annotation[:options]]
+        end
+
+        inline = actions.filter_map do |action, kind|
+          # By identity, not equality: ActiveAdmin::ControllerAction is
+          # Comparable through a `priority` its instances do not all have, so
+          # asking an Array whether it includes one can raise.
+          next if claimed.any? { |claimed_action| claimed_action.equal?(action) }
+
+          options = action.mcp_options
+          [action, kind, options] if options.is_a?(Hash)
+        end
+
+        [annotated, inline]
+      end
+
+      def matching_actions(actions, annotation)
+        wanted = annotation[:action_name].to_s
+
+        actions.select do |action, kind|
+          names_of(action, kind).include?(wanted) &&
+            (annotation[:kind].nil? || annotation[:kind] == kind)
+        end
+      end
+
+      # A batch action may be declared with a String title, from which
+      # ActiveAdmin derives the symbol by titleizing, stripping spaces and
+      # underscoring — which can leave punctuation in it. Applications generate
+      # those in loops from data, so an annotation may name either the title it
+      # wrote or the symbol ActiveAdmin made of it.
+      def names_of(action, kind)
+        names = [declared_name(action, kind).to_s]
+        names << action.title.to_s if kind == :batch && action.respond_to?(:title)
+        names
+      end
+
+      def declared_name(action, kind)
+        (kind == :batch ? action.sym : action.name).to_sym
+      end
+
+      def annotation_missing(config, annotation)
+        "#{resource_name(config)} annotates #{annotation[:action_name]}, which it does not declare"
+      end
+
+      def annotation_ambiguous(config, annotation)
+        "#{resource_name(config)} annotates #{annotation[:action_name]}, which names more than one " \
+          "action; say which with kind:"
+      end
+
+      def resource_name(config)
+        config.resource_class.name
+      end
+
+      def safe_annotations(config)
+        config.respond_to?(:mcp_annotations) ? Array(config.mcp_annotations) : []
+      end
+
+      def candidates(config)
+        pairs = []
+        pairs.concat(safe_actions(config, :member_actions).map { |a| [a, :member] })
+        pairs.concat(safe_actions(config, :collection_actions).map { |a| [a, :collection] })
+        pairs.concat(safe_actions(config, :batch_actions).map { |a| [a, :batch] }) if batch_enabled?(config)
+        pairs.select { |action, _kind| action.respond_to?(:mcp_options) }
+      end
+
+      def safe_actions(config, reader)
+        config.respond_to?(reader) ? Array(config.public_send(reader)) : []
+      end
+
+      # ActiveAdmin keeps registered batch actions even when the namespace has
+      # batch actions switched off, and hides them in the UI. Match that.
+      def batch_enabled?(config)
+        return false unless config.respond_to?(:batch_actions_enabled?)
+
+        config.batch_actions_enabled?
+      end
+
+      def reserved?(definition)
+        RESERVED.include?(definition.tool_name)
+      end
+
+      def warn_and_skip(message)
+        warn("[activeadmin_mcp] ignoring action: #{message}")
+        nil
+      end
+    end
+  end
+end