Expose opted-in ActiveAdmin member, collection and batch actions as MCP tools

[lloydwatkin]

Closes #8.

Lets an application expose individual ActiveAdmin actions — member_action, collection_action and batch_action — to MCP clients as tools, executed through the real ActiveAdmin controller so authorization and callbacks apply exactly as they do in the admin UI.

This is phase 1 of the design in #8. Phases 2 (a create tool, and moving update onto controller dispatch) and 3 (richer form description) are deliberately not included — see "Not in this PR" below.

How an application opts in

Nothing is exposed unless an action says so, via an mcp: key on the options hash it already passes:

ActiveAdmin.register Volunteer do
  member_action :create_warning, method: :post, mcp: {
    description: "Record a warning against a volunteer",
    permission: ->(volunteer) { volunteer.active? && can?(:warn, volunteer) },
    params: {
      reason:   { type: :string, required: true,
                  hint: "Short free-text summary shown to the volunteer" },
      severity: { type: :string, enum: %w[low medium high] },
      category: { type: :string, suggestions: -> { WarningCategory.pluck(:name) } }
    }
  } do
    # existing action body, untouched
  end
end

That registers a volunteer_create_warning tool. Batch actions opt in the same way and inherit their param types from the form: hash they already declare.

ActiveAdmin carries unknown option keys through untouched — ResourceDSL#action strips only :title, and the router reads just name and http_verb — so the engine's entire footprint here is an mcp_options reader mixed into ControllerAction and BatchAction, kept in one file with a guard spec that fails loudly if a future ActiveAdmin stops tolerating extra keys.

Design notes

enum: binds, suggestions: advises. A static enum: is validated before dispatch. A suggestions: proc is evaluated at listing time, surfaced as JSON Schema examples, and never enforced — so it can pull live values from the database. A raising suggestions proc costs its suggestions, never the tool listing.

permission: can only narrow. Every call first passes the resource's ActiveAdmin authorization adapter, exactly as query and update do today; the proc is an additional gate on top, evaluated in controller context so current_admin_user and can? are in scope. Returning a String refuses with that string as the reason, which gives an agent something actionable.

Execution synthesizes a request rather than routing one. Routing would mean issuing a second HTTP request that authenticates by forging an admin session — a back door this gem should not have. Instead the request is built directly and the MCP-authenticated user injected onto the controller instance, so the namespace's authentication callback can be neutralised while authorization keeps running in full. A spec with a denying authorization adapter proves the write is blocked.

Batch calls are scoped. Requested ids are checked against the authorization adapter's scope_collection and the whole call refused if any fall outside — deliberately stricter than ActiveAdmin's own batch_action, which passes collection_selection through unscoped.

Results return status, redirect target and flash — never the rendered HTML body. Redirect-style (submit-side) actions are the supported case; a GET rendering a full admin view is best-effort.

Not in this PR

Phase 2 (create, and update moved onto dispatch so ActiveAdmin's callbacks fire — a behaviour change to an existing tool) and phase 3 (describe_form). Phase 2's central question — whether RecordUpdater's from_form permit-params fallback still earns its place once writes dispatch — is answered by having this PR's dispatcher in hand, which is why it was not planned up front.

Testing

Rebased onto main and brought in line with its conventions: Ruby 4.0.7, no
frozen_string_literal magic comments.

157 unit examples and 27 end-to-end examples, all green in CI.

Per CLAUDE.md, every MCP action is covered end to end, not only by unit
specs. spec/e2e/mcp_actions_spec.rb drives a real generated Rails +
ActiveAdmin + Devise application over HTTP with a real API token, and the
fixture application gained four actions under spec/e2e/fixture_app/ for it
to bite on: an opted-in member_action with a binding enum:, one with no
mcp: key at all, an opted-in batch_action, and a collection_action whose
zero-argument permission: proc calls current_admin_user.

The e2e suite found a real bug the unit specs could not. Rails' forgery
protection refused the synthesized request, so every method: :post member
action and every batch action — batch always dispatches non-GET — failed
against a real application. The unit specs mock around real dispatch, so they
were green throughout. ControllerDispatcher now marks the synthesized
request as verified, alongside the existing authentication no-op: the MCP
request has already authenticated by bearer token and carries no session, so
CSRF has nothing to protect here. Authorization is untouched and still runs in
full.

Each e2e example was verified able to fail by breaking the thing it covers and
watching it go red. Breaking the opt-in guarantee is the instructive one: it
exposes post_destroy, author_destroy and admin_user_destroy, ActiveAdmin's
default destroy batch actions, which is precisely what opt-in holds back.

Unit specs stay double-based in the existing style; the dispatcher and runner
specs boot a real minimal ActiveAdmin, since neither controller dispatch nor
the ActiveAdmin coupling can be honestly covered by doubles.

The design spec and implementation plan that drove this work are kept out of the repository (docs/ is gitignored); the spec's content is reproduced in #8.

🤖 Generated with Claude Code