activeadmin_mcp 0.0.2 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e336c562299eb5de7192243106f42dc18602589811fff5eb0282f12b605ea9b8
-  data.tar.gz: 006f6aac09bceb97605517a9b1b7346a4aef6fc2ddc4c59ab48b36b658825078
+  metadata.gz: 5eb6b95afa3bf6d96a2ae33ced52621014f535f11542dcbee38b88638580e6a9
+  data.tar.gz: c87121826ee5e29805cfa9f3fd8faf1f5042698ec94d46c5fbd7bbc90f08b3f3
 SHA512:
-  metadata.gz: 602940dbd9eb2a0337220672258f343aff84d0851eaec4b0199b38cb99f843adca48ee085ab201ed896ec29f260fe5e8ae6a8844b567990611e4c866d3abd05f
-  data.tar.gz: 54e2309b725add92b02af4ebbaefdafd5cfa8c349890211c22f0bb391f00863764e89cf50f7e5f6ace5f293962f473ad75f5197f7813702b939cfc2dc95d5b9d
+  metadata.gz: 6b7a903b975a980a23246e944b2e321fab7019ac218c06a51f6645a5e0d7577951cb4bdce9c4319e7184d9b5f031b96320ee874666b8d28c1814850cb59533b9
+  data.tar.gz: 3a069d2f4d7a69038f3f96153e67911472f43fabb64aa4fc7a3ccdb421684cd6cabd126d208fbe9671dc1fa7c7ecc7f2789d68638f4e84cfdcb78e45d90ddb7b

data/README.md

@@ -21,11 +21,17 @@ The server is a Rails engine mounted inside your application (by default at
 - **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.
+- **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
+  refused by `query`, and every query is scoped with the adapter's
+  `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 (CanCanCan, Pundit, etc.) as the authenticated MCP
-  user.
+  authorization adapter as the authenticated MCP user.
 - **Authentication is optional but built in.** Enable Bearer-token auth and the
   installer adds an "MCP Tokens" management page to your ActiveAdmin panel.
 
@@ -57,8 +63,8 @@ read/query setup without authentication.
 
 | Tool | Description |
 |------|-------------|
-| `list_resources` | List every ActiveAdmin resource along with its attributes. |
-| `query` | Query a resource using Ransack syntax (`limit` defaults to 25, capped at 100). |
+| `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. |
 
 ### Query examples
@@ -197,6 +203,84 @@ 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, 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.
+
+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.
+
+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.
+
+### 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

data/lib/activeadmin_mcp/authorization.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ActiveadminMcp
+  # Applies a resource's ActiveAdmin authorization adapter to MCP tool calls, so
+  # reads, listings and writes obey the same rules as the admin UI.
+  #
+  # ActiveAdmin's default adapter authorizes every action and returns collections
+  # unchanged, so applications without an authorization adapter are unaffected.
+  # Applications that configure one (CanCanCan via `cancan_ability_class`, Pundit,
+  # a custom adapter, ...) get their policy enforced on every path.
+  class Authorization
+    READ = :read
+
+    def self.for(config, current_user)
+      adapter_class = config.namespace.authorization_adapter
+      adapter_class = adapter_class.constantize if adapter_class.is_a?(String)
+      new(adapter_class.new(config, current_user))
+    end
+
+    def initialize(adapter)
+      @adapter = adapter
+    end
+
+    def authorized?(action, subject)
+      @adapter.authorized?(action, subject)
+    end
+
+    def scope_collection(collection, action = READ)
+      @adapter.scope_collection(collection, action)
+    end
+  end
+end

data/lib/activeadmin_mcp/record_updater.rb

@@ -53,9 +53,7 @@ module ActiveadminMcp
     end
 
     def authorized?(config, record)
-      adapter_class = config.namespace.authorization_adapter
-      adapter_class = adapter_class.constantize if adapter_class.is_a?(String)
-      adapter_class.new(config, @current_user).authorized?(UPDATE, record)
+      Authorization.for(config, @current_user).authorized?(UPDATE, record)
     end
 
     # Resolves the fields we may write, accepting exactly what the admin form

data/lib/activeadmin_mcp/request_handler.rb

@@ -44,12 +44,15 @@ module ActiveadminMcp
         tools: [
           {
             name: "list_resources",
-            description: "List all ActiveAdmin resources with their attributes",
+            description: "List the ActiveAdmin resources the authenticated user is authorized " \
+                         "to read, with their attributes",
             inputSchema: { type: "object", properties: {} },
           },
           {
             name: "query",
-            description: "Query an ActiveAdmin resource using Ransack syntax",
+            description: "Query an ActiveAdmin resource using Ransack syntax. Respects ActiveAdmin " \
+                         "authorization: the resource must be readable by the authenticated user, " \
+                         "and results are scoped to the records they may access.",
             inputSchema: {
               type: "object",
               properties: {
@@ -93,18 +96,21 @@ module ActiveadminMcp
     end
 
     def tool_list_resources
-      { resources: ResourceRegistry.all }
+      entries = ResourceRegistry.resources.select { |entry| authorized_to_read?(entry) }
+      { resources: entries.map { |entry| ResourceRegistry.resource_info(entry) } }
     end
 
     def tool_query(args)
       resource = ResourceRegistry.find(args["resource"])
       return { error: "Resource not found: #{args['resource']}" } unless resource
+      return { error: "Not authorized to query #{resource[:name]}" } unless authorized_to_read?(resource)
 
       limit = [args["limit"] || 25, 100].min
       q = args["q"] || {}
 
-      records = resource[:model].ransack(q).result.limit(limit)
-      { resource: resource[:name], count: records.size, records: records.as_json }
+      relation = resource[:model].ransack(q).result
+      records = authorization(resource).scope_collection(relation, Authorization::READ).limit(limit)
+      { resource: resource[:name], count: records.size, records: filter_sensitive(records.as_json) }
     end
 
     def tool_update(args)
@@ -119,6 +125,21 @@ module ActiveadminMcp
                    .call(id: args["id"], attributes: attributes)
     end
 
+    def authorized_to_read?(resource)
+      authorization(resource).authorized?(Authorization::READ, resource[:model])
+    end
+
+    def authorization(resource)
+      Authorization.for(resource[:config], @current_user)
+    end
+
+    def filter_sensitive(records)
+      sensitive = ResourceRegistry.sensitive_attributes
+      Array(records).map do |record|
+        record.is_a?(Hash) ? record.except(*sensitive) : record
+      end
+    end
+
     def success(id, result)
       { jsonrpc: "2.0", id: id, result: result }
     end

data/lib/activeadmin_mcp/resource_registry.rb

@@ -4,14 +4,28 @@ module ActiveadminMcp
   module ResourceRegistry
     class << self
       def all
-        discover.map { |r| resource_info(r) }
+        resources.map { |entry| resource_info(entry) }
+      end
+
+      def resources
+        discover.map { |r| entry(r) }
       end
 
       def find(name)
-        resource = discover.find { |r| r.resource_class.name == name }
-        return unless resource
+        resources.find { |entry| entry[:name] == name }
+      end
 
-        { name: resource.resource_class.name, model: resource.resource_class, config: resource }
+      def resource_info(entry)
+        klass = entry[:model]
+        {
+          name: klass.name,
+          table: klass.table_name,
+          attributes: klass.column_names - sensitive_attributes,
+        }
+      end
+
+      def sensitive_attributes
+        %w[encrypted_password password_digest reset_password_token api_key secret]
       end
 
       private
@@ -26,17 +40,8 @@ module ActiveadminMcp
         end || []
       end
 
-      def resource_info(resource)
-        klass = resource.resource_class
-        {
-          name: klass.name,
-          table: klass.table_name,
-          attributes: klass.column_names - sensitive_attributes,
-        }
-      end
-
-      def sensitive_attributes
-        %w[encrypted_password password_digest reset_password_token api_key secret]
+      def entry(resource)
+        { name: resource.resource_class.name, model: resource.resource_class, config: resource }
       end
     end
   end

data/lib/activeadmin_mcp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveadminMcp
-  VERSION = "0.0.2"
+  VERSION = "0.0.4"
 end

data/lib/activeadmin_mcp.rb

@@ -2,6 +2,7 @@
 
 require_relative "activeadmin_mcp/version"
 require_relative "activeadmin_mcp/configuration"
+require_relative "activeadmin_mcp/authorization"
 require_relative "activeadmin_mcp/resource_registry"
 require_relative "activeadmin_mcp/form_field_collector"
 require_relative "activeadmin_mcp/record_updater"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activeadmin_mcp
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.4
 platform: ruby
 authors:
 - harunkumars
@@ -95,6 +95,7 @@ files:
 - app/models/activeadmin_mcp/api_token.rb
 - config/routes.rb
 - lib/activeadmin_mcp.rb
+- lib/activeadmin_mcp/authorization.rb
 - lib/activeadmin_mcp/configuration.rb
 - lib/activeadmin_mcp/engine.rb
 - lib/activeadmin_mcp/form_field_collector.rb