activeadmin_mcp 0.0.3 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d97e042cb6e4af51f5939d4edd39a96f7193ece948a05a70dd8e18851f1bc85
-  data.tar.gz: 6b91b93d2d0511f3bea310f62044589eb35b90358547e942d379be214582d5e7
+  metadata.gz: aac4aa9e2af5d377f711090b2e8adad79915844e26842733f5c8af6b02f37d7b
+  data.tar.gz: c418625d7b5bff3c9e555d0d248e098c08a8ac1a224644e900fa14fa3a95dfa7
 SHA512:
-  metadata.gz: 6714a33bbef7072a22f067f422837e6ccf88ebd6a835157c8ffa8fff5487791ee2494fbcd1316ac4ca65c9767e53ac6e48a7c672e84846615fb77af29b507080
-  data.tar.gz: fb49f14f716cd9c5a5e0b9ca80c546adaaa7fcab15b8867965c7d823084f456580982270185c65861477c11840c219cbdf41fd676a597c2b39c4835ec7d0f5f4
+  metadata.gz: aea999468c061e6d532b0edb1e3241393a78dc34c1f94c0b07c2108431ab4370b4c89d45940a6691dce0ce5bfbc6903f92bc087457fc4d557fd70a97dacc9278
+  data.tar.gz: 588af72e3801e3c2c728d0407e217c7ebf54277d07a8dbdbd518fdbfe7e9cb335601cc3afe90cbcbbe76af40ef55b6bddde982ce11632107aca957875e34e464

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,230 @@ 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.
+- **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. `has_many` blocks are
+reported under `nested` rather than flattened in with the record's own fields.
+
+`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.
+
+### 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.
 
 ## Connecting a client
 
@@ -203,10 +406,95 @@ end
 }
 ```
 
+## Claude Desktop (MCPB bundle)
+
+Claude Code talks to the server over HTTP directly, but **Claude Desktop** cannot:
+its remote connector UI has no way to send an API token header. The `mcpb/`
+directory solves this with an
+[MCP bundle](https://claude.com/docs/connectors/building/mcpb) — a `.mcpb` file
+your colleagues install with a double-click.
+
+Inside the bundle is a small Node script that speaks stdio to Claude Desktop and
+forwards every message, unchanged, to your server over HTTPS with the token
+attached. It has no dependencies and adds no capabilities of its own, so the
+tools it exposes are exactly the ones your server exposes.
+
+```
+Claude Desktop  ──stdio──▶  mcpb proxy  ──HTTPS + token──▶  your Rails app
+```
+
+### Building the bundle
+
+Requires Node 18 or newer. From the repository root:
+
+```bash
+cd mcpb
+npm test                                   # no dependencies to install
+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. 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).
+
+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 — 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
+
+1. **Generate a token.** Sign in to your admin panel, go to **MCP Tokens**, name
+   the token after the machine you are installing on (e.g. "Claude Desktop —
+   work laptop") and copy it. It is shown only once.
+2. **Install the bundle.** Double-click the `.mcpb` file, or drag it onto the
+   Claude Desktop window, or use **Settings → Extensions → Advanced settings →
+   Install Extension…**.
+3. **Fill in the three settings** Claude Desktop prompts for:
+
+   | Setting | Value |
+   |---------|-------|
+   | Server URL | The full MCP endpoint, e.g. `https://admin.example.com/admin/mcp` |
+   | API token | The token from step 1 (stored in the OS keychain, never shown again) |
+   | Authentication header | `Authorization`, unless your app sets a custom [`auth_header_name`](#custom-auth-header) |
+
+4. **Check it works.** Start a new chat and ask Claude to list the admin
+   resources it can see. You should get back the resources your account can read.
+
+Installation is per-person: each colleague installs the bundle and generates
+their own token, so every MCP call is attributed to them and constrained by
+their own admin permissions.
+
+### Revoking access
+
+A token is a long-lived credential granting everything that user can do in
+admin. Revoke one from the same **MCP Tokens** page — the `Last used` column
+shows which tokens are still live. Revoking takes effect immediately; the
+installed bundle simply starts reporting an authentication failure.
+
+### Troubleshooting
+
+| Symptom | Cause |
+|---------|-------|
+| "The server rejected the API token (HTTP 401)" | The token is wrong, revoked, or being sent in the wrong header. Check the **Authentication header** setting matches your `auth_header_name`. |
+| "Could not reach …" | The URL is wrong or unreachable from this machine — check VPN, and that the URL includes the full mount path. |
+| The extension shows no tools | Claude Desktop only refreshes tools on connect. Toggle the extension off and on in Settings → Extensions. |
+| Anything else | Claude Desktop's extension logs carry the proxy's stderr output, each line prefixed `[activeadmin_mcp]`. |
+
 ## 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|
@@ -266,6 +554,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,64 @@
+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
+      def all
+        ResourceRegistry.resources.flat_map { |entry| definitions_for(entry[:config]) }
+      end
+
+      def find(tool_name)
+        all.find { |definition| definition.tool_name == tool_name }
+      end
+
+      private
+
+      def definitions_for(config)
+        candidates(config).filter_map do |action, kind|
+          definition = ActionDefinition.build(config: config, action: action, kind: kind)
+          next unless definition
+
+          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
+
+      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