activeadmin_mcp 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 99312ac0bef360e80a8d058b79adf5f0af182d3bedc19fdfbf4caa69964f7e44
+  data.tar.gz: bba982b59472e271c18214bc4674e60a3ae96729b78172163d54eed756b3997c
+SHA512:
+  metadata.gz: 861ea8e3d8eeff901f12f4fa99385db60fd0854a0eae22462cf314cce67820632033b8e55ebc13252bcaa3389f0b6aceda4cc712d5bceb4ba0c342ac10a5815d
+  data.tar.gz: 035b92456d5b3ca111c5e4715c8f495f52531ab053eb7974f1c1dda12de73d87f08ba34b40f226723d8a207bc98a89c929c4d6bb8ecdc9ee0873fdc6fbefb275

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 harunkumars
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,276 @@
+# ActiveadminMcp
+
+> **Status: Experimental / work in progress**
+
+`activeadmin_mcp` turns the resources you have already registered with
+[ActiveAdmin](https://activeadmin.info/) into a
+[Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server, so AI
+assistants such as Claude Code can list, query, and update your admin data —
+while respecting the exact same forms, permitted parameters, and authorization
+rules as your ActiveAdmin UI.
+
+The server is a Rails engine mounted inside your application (by default at
+`/mcp`) and speaks MCP over HTTP (JSON-RPC 2.0, protocol revision
+`2025-06-18`).
+
+## How it works
+
+- **Nothing new to describe.** The engine reads your existing ActiveAdmin
+  registrations, so the resources, attributes, and permitted fields it exposes
+  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.
+- **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.
+- **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
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+gem "activeadmin_mcp"
+```
+
+Install it and run the generator:
+
+```bash
+bundle install
+rails generate activeadmin_mcp:install
+```
+
+The MCP server is mounted at `/mcp` automatically. That's all you need for a
+read/query setup without authentication.
+
+## Available tools
+
+| 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). |
+| `update` | Update an existing record, honouring ActiveAdmin's permitted params and authorization. |
+
+### Query examples
+
+```
+Query users whose email contains "example.com"
+→ query(resource: "User", q: { email_cont: "example.com" })
+
+Find active posts created since the start of the month
+→ query(resource: "Post", q: { status_eq: "active", created_at_gt: "2026-08-01" })
+```
+
+### Updating records
+
+```
+Update a user's name
+→ update(resource: "User", id: 42, attributes: { name: "New name" })
+```
+
+The `update` tool applies the same rules as the ActiveAdmin UI:
+
+- **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.
+- **Permitted fields only** — attributes are filtered through the resource's
+  `permit_params`; fields the admin form doesn't accept are silently dropped.
+
+## Connecting a client
+
+`activeadmin_mcp` has been tested with **Claude Code** (Anthropic) over the
+HTTP transport.
+
+```bash
+claude mcp add --transport http my-app http://localhost:3000/mcp/
+```
+
+Or add it to your `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "my-app": {
+      "type": "http",
+      "url": "http://localhost:3000/mcp/"
+    }
+  }
+}
+```
+
+## Authentication
+
+To protect the MCP endpoint with API-token authentication, run the installer
+with the `devise_token` strategy and migrate:
+
+```bash
+rails generate activeadmin_mcp:install --auth devise_token
+rails db:migrate
+```
+
+This will:
+
+- Create the `mcp_api_tokens` table.
+- Add an "MCP Tokens" page to your ActiveAdmin panel (`app/admin/` by default).
+- Enable token authentication in the initializer.
+
+### Generator options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--auth` | none | Authentication method to use (e.g. `devise_token`). |
+| `--admin-path` | `app/admin` | Directory for the ActiveAdmin page file. |
+
+Example with a custom admin path:
+
+```bash
+rails generate activeadmin_mcp:install --auth devise_token --admin-path app/admin/mcp
+```
+
+### Managing tokens
+
+1. Log in to your ActiveAdmin panel (`/admin`).
+2. Navigate to **MCP Tokens** (or **Settings > MCP Tokens** if you set a
+   `menu_parent`).
+3. Create a token and copy it — it is only shown once.
+
+### Connecting with a token
+
+```bash
+claude mcp add --transport http \
+  --header 'Authorization: Bearer YOUR_TOKEN' \
+  my-app http://localhost:3000/mcp/
+```
+
+Or in `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "my-app": {
+      "type": "http",
+      "url": "http://localhost:3000/mcp/",
+      "headers": {
+        "Authorization": "Bearer YOUR_TOKEN"
+      }
+    }
+  }
+}
+```
+
+### Custom auth header
+
+If your application sits behind a reverse proxy that strips the standard
+`Authorization` header (e.g. AWS Verified Access), configure a custom header
+name and pass the token through it instead:
+
+```ruby
+ActiveadminMcp.configure do |config|
+  config.authentication_method = :devise_token
+  config.auth_header_name = "X-MCP-Authorization"
+end
+```
+
+```json
+{
+  "mcpServers": {
+    "my-app": {
+      "type": "http",
+      "url": "https://admin.example.com/admin/mcp/",
+      "headers": {
+        "X-MCP-Authorization": "Bearer YOUR_TOKEN"
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+The generator writes an initializer to
+`config/initializers/activeadmin_mcp.rb`:
+
+```ruby
+ActiveadminMcp.configure do |config|
+  config.authentication_method = :devise_token
+  config.user_class = "User" # your Devise model class
+end
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `authentication_method` | `nil` | Set to `:devise_token` to enable Bearer-token auth. |
+| `user_class` | `"User"` | The Devise model class name. |
+| `current_user_method` | `:current_admin_user` | Controller method returning the current user. |
+| `menu_parent` | `nil` | Parent menu for the MCP Tokens page (e.g. `"Settings"`). |
+| `mount_path` | `"/mcp"` | Path where the MCP server is mounted. |
+| `mount_strategy` | `:prepend` | Route mounting strategy: `:prepend`, `:append`, or `:none`. |
+| `auth_header_name` | `"Authorization"` | HTTP header to read the Bearer token from. |
+
+### Route mounting
+
+By default the engine prepends its route to the top of your application's route
+table. This suits most setups, but can cause problems when your admin routes
+use constraints (e.g. hostname-based routing), because a prepended mount sits
+outside any constraint blocks.
+
+| Strategy | Behaviour |
+|----------|-----------|
+| `:prepend` | **(default)** Mounts at the top of the route table via `routes.prepend`. |
+| `:append` | Mounts at the bottom of the route table via `routes.append`. |
+| `:none` | Skips automatic mounting — you mount the engine yourself. |
+
+To mount inside a constraint block, set `mount_strategy` to `:none` and mount
+the engine manually:
+
+```ruby
+# config/initializers/activeadmin_mcp.rb
+ActiveadminMcp.configure do |config|
+  config.mount_path = "/admin/mcp"
+  config.mount_strategy = :none
+end
+```
+
+```ruby
+# config/routes.rb (or a drawn route file)
+constraints AdminConstraint.new do
+  ActiveAdmin.routes(self)
+  mount ActiveadminMcp::Engine => ActiveadminMcp.config.mount_path
+end
+```
+
+## Development
+
+After checking out the repo, install dependencies and run the test suite:
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.
+
+## Credits
+
+This project was forked from
+[betacraft/active_admin_mcp](https://github.com/betacraft/active_admin_mcp),
+originally created by [harunkumars](https://github.com/harunkumars), and has
+been extended from there.
+
+## License
+
+Released under the [MIT License](LICENSE.txt).

data/app/controllers/activeadmin_mcp/mcp_controller.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module ActiveadminMcp
+  class McpController < ActionController::API
+    before_action :authenticate_mcp_token!
+
+    attr_reader :current_mcp_user
+
+    def call
+      request_body = JSON.parse(request.body.read)
+      response = RequestHandler.new(current_user: current_mcp_user).handle(request_body)
+
+      response ? render(json: response) : head(:no_content)
+    rescue JSON::ParserError => e
+      render json: { jsonrpc: "2.0", error: { code: -32_700, message: e.message } }, status: :bad_request
+    end
+
+    private
+
+    def authenticate_mcp_token!
+      return unless ActiveadminMcp.config.authentication_enabled?
+
+      token = extract_bearer_token
+      unless token
+        render json: jsonrpc_error(-32_000, "Unauthorized"), status: :unauthorized
+        return
+      end
+
+      api_token = ApiToken.find_by_raw_token(token)
+      unless api_token
+        render json: jsonrpc_error(-32_000, "Unauthorized"), status: :unauthorized
+        return
+      end
+
+      @current_mcp_user = api_token.user
+      api_token.touch_last_used!
+    rescue ActiveRecord::StatementInvalid
+      render json: jsonrpc_error(-32_000, "Authentication not configured — run migrations"),
+             status: :internal_server_error
+    end
+
+    def extract_bearer_token
+      header = request.headers[ActiveadminMcp.config.auth_header_name]
+      return nil unless header&.start_with?("Bearer ")
+
+      header.delete_prefix("Bearer ")
+    end
+
+    def jsonrpc_error(code, message)
+      { jsonrpc: "2.0", id: nil, error: { code: code, message: message } }
+    end
+  end
+end

data/app/models/activeadmin_mcp/api_token.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "digest"
+require "securerandom"
+
+module ActiveadminMcp
+  class ApiToken < ActiveRecord::Base
+    self.table_name = "mcp_api_tokens"
+
+    belongs_to :user, class_name: ActiveadminMcp.config.user_class
+
+    attr_accessor :raw_token
+
+    validates :token_digest, presence: true, uniqueness: true
+    validates :user_id, presence: true
+
+    before_validation :generate_token, on: :create
+
+    LAST_USED_THROTTLE = 5.minutes
+
+    def self.find_by_raw_token(raw_token)
+      return nil if raw_token.blank?
+
+      find_by(token_digest: digest(raw_token))
+    end
+
+    def self.digest(raw_token)
+      Digest::SHA256.hexdigest(raw_token)
+    end
+
+    def touch_last_used!
+      return if last_used_at.present? && last_used_at > LAST_USED_THROTTLE.ago
+
+      update_column(:last_used_at, Time.current)
+    end
+
+    private
+
+    def generate_token
+      self.raw_token = "aamcp_#{SecureRandom.hex(32)}"
+      self.token_digest = self.class.digest(raw_token)
+    end
+  end
+end

data/config/routes.rb

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

data/lib/activeadmin_mcp/configuration.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module ActiveadminMcp
+  class Configuration
+    MOUNT_STRATEGIES = %i[prepend append none].freeze
+
+    attr_accessor :authentication_method, :user_class, :current_user_method, :menu_parent, :mount_path,
+                  :auth_header_name
+
+    attr_reader :mount_strategy
+
+    def initialize
+      @authentication_method = nil
+      @user_class = "User"
+      @current_user_method = :current_admin_user
+      @menu_parent = nil
+      @mount_path = "/mcp"
+      @mount_strategy = :prepend
+      @auth_header_name = "Authorization"
+    end
+
+    def mount_strategy=(strategy)
+      unless MOUNT_STRATEGIES.include?(strategy)
+        raise ArgumentError, "Invalid mount strategy: #{strategy}. Must be one of: #{MOUNT_STRATEGIES.join(', ')}"
+      end
+
+      @mount_strategy = strategy
+    end
+
+    def authentication_enabled?
+      authentication_method == :devise_token
+    end
+  end
+end

data/lib/activeadmin_mcp/engine.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ActiveadminMcp
+  class Engine < ::Rails::Engine
+    isolate_namespace ActiveadminMcp
+
+    initializer "activeadmin_mcp.mount" do |app|
+      case ActiveadminMcp.config.mount_strategy
+      when :prepend
+        app.routes.prepend do
+          mount ActiveadminMcp::Engine => ActiveadminMcp.config.mount_path
+        end
+      when :append
+        app.routes.append do
+          mount ActiveadminMcp::Engine => ActiveadminMcp.config.mount_path
+        end
+      end
+    end
+  end
+end

data/lib/activeadmin_mcp/record_updater.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module ActiveadminMcp
+  # Updates a single ActiveAdmin-managed record, enforcing the same three gates
+  # the admin UI would: the resource must expose the update action, the current
+  # user must be authorized, and only fields the admin form permits are written.
+  class RecordUpdater
+    UPDATE = :update
+
+    # Raised internally when the resource's permitted params cannot be resolved.
+    class PermitError < StandardError; end
+
+    def initialize(resource:, current_user:)
+      @resource = resource
+      @current_user = current_user
+    end
+
+    def call(id:, attributes:)
+      config = @resource[:config]
+
+      return error("Resource is not editable: #{@resource[:name]}") unless editable?(config)
+
+      record = @resource[:model].find_by(id: id)
+      return error("Record not found: #{@resource[:name]}##{id}") unless record
+
+      unless authorized?(config, record)
+        return error("Not authorized to update #{@resource[:name]}##{id}")
+      end
+
+      begin
+        permitted = permitted_attributes(config, attributes)
+      rescue PermitError => e
+        return error(e.message)
+      end
+      return error("No permitted attributes to update") if permitted.empty?
+
+      if record.update(permitted)
+        {
+          resource: @resource[:name],
+          id: record.id,
+          updated: permitted.keys,
+          record: record.as_json,
+        }
+      else
+        error("Validation failed", details: record.errors.full_messages)
+      end
+    end
+
+    private
+
+    def editable?(config)
+      config.defined_actions.include?(UPDATE)
+    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)
+    end
+
+    # Runs the incoming attributes through the resource controller's own
+    # permitted_params (compiled from `permit_params`), so we accept exactly what
+    # the admin form accepts. Fails closed if that cannot be resolved.
+    def permitted_attributes(config, attributes)
+      param_key = config.param_key.to_sym
+      controller = config.controller.new
+
+      unless controller.respond_to?(:permitted_params, true)
+        raise PermitError, "Resource does not declare permit_params: #{@resource[:name]}"
+      end
+
+      controller.params = ActionController::Parameters.new(param_key => attributes)
+      permitted = controller.send(:permitted_params)[param_key]
+      permitted ? permitted.to_h.symbolize_keys : {}
+    rescue PermitError
+      raise
+    rescue StandardError => e
+      raise PermitError, "Could not determine permitted attributes: #{e.message}"
+    end
+
+    def error(message, details: nil)
+      result = { error: message }
+      result[:details] = details if details
+      result
+    end
+  end
+end

data/lib/activeadmin_mcp/request_handler.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module ActiveadminMcp
+  class RequestHandler
+    PROTOCOL_VERSION = "2025-06-18"
+
+    def initialize(current_user: nil)
+      @current_user = current_user
+    end
+
+    def handle(request)
+      id = request["id"]
+      method = request["method"]
+      params = request["params"] || {}
+
+      case method
+      when "initialize"
+        success(id, initialize_result)
+      when "notifications/initialized"
+        nil
+      when "tools/list"
+        success(id, tools_list)
+      when "tools/call"
+        success(id, call_tool(params))
+      when "ping"
+        success(id, {})
+      else
+        error(id, -32_601, "Method not found: #{method}")
+      end
+    end
+
+    private
+
+    def initialize_result
+      {
+        protocolVersion: PROTOCOL_VERSION,
+        serverInfo: { name: "activeadmin-mcp", version: ActiveadminMcp::VERSION },
+        capabilities: { tools: {} },
+      }
+    end
+
+    def tools_list
+      {
+        tools: [
+          {
+            name: "list_resources",
+            description: "List all ActiveAdmin resources with their attributes",
+            inputSchema: { type: "object", properties: {} },
+          },
+          {
+            name: "query",
+            description: "Query an ActiveAdmin resource using Ransack syntax",
+            inputSchema: {
+              type: "object",
+              properties: {
+                resource: { type: "string", description: "Resource name (e.g., 'User', 'Post')" },
+                q: { type: "object", description: "Ransack query (e.g., {name_cont: 'john'})" },
+                limit: { type: "integer", description: "Max records (default: 25)" },
+              },
+              required: ["resource"],
+            },
+          },
+          {
+            name: "update",
+            description: "Update an existing record. Only fields the resource's ActiveAdmin " \
+                         "form permits are written, and the update respects ActiveAdmin authorization.",
+            inputSchema: {
+              type: "object",
+              properties: {
+                resource: { type: "string", description: "Resource name (e.g., 'User', 'Post')" },
+                id: { type: ["integer", "string"], description: "Primary key of the record to update" },
+                attributes: { type: "object", description: "Attributes to update (e.g., {name: 'New name'})" },
+              },
+              required: %w[resource id attributes],
+            },
+          },
+        ],
+      }
+    end
+
+    def call_tool(params)
+      name = params["name"]
+      args = params["arguments"] || {}
+
+      result = case name
+               when "list_resources" then tool_list_resources
+               when "query" then tool_query(args)
+               when "update" then tool_update(args)
+               else { error: "Unknown tool: #{name}" }
+               end
+
+      { content: [{ type: "text", text: JSON.pretty_generate(result) }] }
+    end
+
+    def tool_list_resources
+      { resources: ResourceRegistry.all }
+    end
+
+    def tool_query(args)
+      resource = ResourceRegistry.find(args["resource"])
+      return { error: "Resource not found: #{args['resource']}" } unless 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 }
+    end
+
+    def tool_update(args)
+      resource = ResourceRegistry.find(args["resource"])
+      return { error: "Resource not found: #{args['resource']}" } unless resource
+      return { error: "id is required" } if args["id"].nil?
+
+      attributes = args["attributes"] || {}
+      return { error: "attributes are required" } if attributes.empty?
+
+      RecordUpdater.new(resource: resource, current_user: @current_user)
+                   .call(id: args["id"], attributes: attributes)
+    end
+
+    def success(id, result)
+      { jsonrpc: "2.0", id: id, result: result }
+    end
+
+    def error(id, code, message)
+      { jsonrpc: "2.0", id: id, error: { code: code, message: message } }
+    end
+  end
+end

data/lib/activeadmin_mcp/resource_registry.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module ActiveadminMcp
+  module ResourceRegistry
+    class << self
+      def all
+        discover.map { |r| resource_info(r) }
+      end
+
+      def find(name)
+        resource = discover.find { |r| r.resource_class.name == name }
+        return unless resource
+
+        { name: resource.resource_class.name, model: resource.resource_class, config: resource }
+      end
+
+      private
+
+      def discover
+        return [] unless defined?(ActiveAdmin)
+
+        ActiveAdmin.application.namespaces[:admin]&.resources&.select do |r|
+          r.respond_to?(:resource_class) &&
+            r.resource_class.respond_to?(:ransack) &&
+            r.resource_class.table_exists?
+        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]
+      end
+    end
+  end
+end

data/lib/activeadmin_mcp/version.rb

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

data/lib/activeadmin_mcp.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "activeadmin_mcp/version"
+require_relative "activeadmin_mcp/configuration"
+require_relative "activeadmin_mcp/resource_registry"
+require_relative "activeadmin_mcp/record_updater"
+require_relative "activeadmin_mcp/request_handler"
+require_relative "activeadmin_mcp/engine"
+
+module ActiveadminMcp
+  class Error < StandardError; end
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+  end
+end

data/lib/generators/activeadmin_mcp/install/install_generator.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module ActiveadminMcp
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :auth, type: :string, default: nil,
+                          desc: "Authentication method (e.g., devise_token)"
+      class_option :admin_path, type: :string, default: "app/admin",
+                                desc: "Path for ActiveAdmin page file"
+
+      def copy_initializer
+        template "initializer.rb", "config/initializers/activeadmin_mcp.rb"
+      end
+
+      def copy_migration
+        return unless auth_method
+
+        migration_template "migration.rb.erb", "db/migrate/create_mcp_api_tokens.rb"
+      end
+
+      def copy_admin_page
+        return unless auth_method
+
+        copy_file "mcp_api_tokens.rb", File.join(options[:admin_path], "mcp_api_tokens.rb")
+      end
+
+      def set_auth_config
+        return unless auth_method
+
+        gsub_file "config/initializers/activeadmin_mcp.rb",
+                  "# config.authentication_method = :devise_token",
+                  "config.authentication_method = :#{auth_method}"
+      end
+
+      def show_instructions
+        say ""
+        say "=" * 60, :green
+        say " ActiveadminMcp installed!", :green
+        say "=" * 60, :green
+        say ""
+        say "Your MCP server is available at: /mcp"
+        say ""
+
+        if auth_method
+          say "Authentication (#{auth_method}) enabled! Next steps:", :yellow
+          say ""
+          say "  1. Run migrations:"
+          say "     rails db:migrate"
+          say ""
+          say "  2. Create tokens via ActiveAdmin:"
+          say "     Log in to /admin and visit 'MCP Tokens' under Settings"
+          say ""
+          say "  3. Connect Claude Code with your token:"
+          say "     claude mcp add --transport http \\", :cyan
+          say "       --header 'Authorization: Bearer YOUR_TOKEN' \\", :cyan
+          say "       #{app_name} http://localhost:3000/mcp/", :cyan
+        else
+          say "Connect Claude Code:"
+          say ""
+          say "  claude mcp add --transport http #{app_name} http://localhost:3000/mcp/"
+          say ""
+          say "To add authentication later:"
+          say "  rails generate activeadmin_mcp:install --auth devise_token"
+        end
+
+        say ""
+      end
+
+      private
+
+      def auth_method
+        options[:auth]
+      end
+
+      def app_name
+        Rails.application.class.module_parent_name.underscore.dasherize
+      rescue StandardError
+        "my-app"
+      end
+    end
+  end
+end

data/lib/generators/activeadmin_mcp/install/templates/initializer.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+ActiveadminMcp.configure do |config|
+  # Uncomment to enable API token authentication.
+  # Requires running the auth migration first:
+  #   rails generate activeadmin_mcp:install --auth
+  #
+  # config.authentication_method = :devise_token
+
+  # The Devise model class used for authentication.
+  # config.user_class = "User"
+
+  # The controller method that returns the current user.
+  # config.current_user_method = :current_admin_user
+
+  # Parent menu for the MCP Tokens page in ActiveAdmin.
+  # config.menu_parent = "Settings"
+
+  # Path where the MCP server is mounted.
+  # config.mount_path = "/mcp"
+
+  # HTTP header used to read the Bearer token from.
+  # Useful when a reverse proxy (e.g. AWS Verified Access) strips the
+  # standard Authorization header.
+  # config.auth_header_name = "Authorization"
+end

data/lib/generators/activeadmin_mcp/install/templates/mcp_api_tokens.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+ActiveAdmin.register_page "MCP API Tokens" do
+  menu label: "MCP Tokens", parent: ActiveadminMcp.config.menu_parent, priority: 100
+
+  content do
+    @tokens = ActiveadminMcp::ApiToken.where(user: send(ActiveadminMcp.config.current_user_method)).order(created_at: :desc)
+
+    if flash[:mcp_raw_token]
+      panel "New Token Created", class: "mcp-token-created" do
+        para "Copy this token now — it will not be shown again:"
+        pre flash[:mcp_raw_token], class: "mcp-raw-token"
+      end
+    end
+
+    panel "Your MCP API Tokens" do
+      table_for @tokens do
+        column :name
+        column(:created_at) { |t| l(t.created_at, format: :long) }
+        column(:last_used_at) { |t| t.last_used_at ? l(t.last_used_at, format: :long) : "Never" }
+        column "Actions" do |token|
+          link_to "Revoke", admin_mcp_api_tokens_destroy_path(token_id: token.id),
+                  method: :delete,
+                  data: { confirm: "Revoke token '#{token.name}'?" },
+                  class: "button small"
+        end
+      end
+
+      if @tokens.empty?
+        para "No tokens yet. Create one to authenticate MCP clients."
+      end
+    end
+
+    panel "Create New Token" do
+      form action: admin_mcp_api_tokens_create_path, method: :post do
+        input type: :hidden, name: :authenticity_token, value: form_authenticity_token
+        label "Token Name", for: :mcp_token_name
+        input type: :text, name: "mcp_token[name]", id: :mcp_token_name, placeholder: "e.g., Claude Code laptop"
+        input type: :submit, value: "Generate Token"
+      end
+    end
+  end
+
+  page_action :create, method: :post do
+    token = ActiveadminMcp::ApiToken.create!(
+      user: send(ActiveadminMcp.config.current_user_method),
+      name: params[:mcp_token][:name].presence || "Unnamed token"
+    )
+    flash[:mcp_raw_token] = token.raw_token
+    redirect_to admin_mcp_api_tokens_path()
+  end
+
+  page_action :destroy, method: :delete do
+    token = ActiveadminMcp::ApiToken.where(user: send(ActiveadminMcp.config.current_user_method)).find(params[:token_id])
+    token.destroy!
+    flash[:notice] = "Token revoked."
+    redirect_to admin_mcp_api_tokens_path()
+  end
+end

data/lib/generators/activeadmin_mcp/install/templates/migration.rb.erb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class CreateMcpApiTokens < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    return if table_exists?(:mcp_api_tokens)
+
+    create_table :mcp_api_tokens do |t|
+      t.references :user, null: false
+      t.string :token_digest, null: false
+      t.string :name
+      t.datetime :last_used_at
+
+      t.timestamps
+    end
+
+    add_index :mcp_api_tokens, :token_digest, unique: true
+  end
+end

metadata

@@ -0,0 +1,133 @@
+--- !ruby/object:Gem::Specification
+name: activeadmin_mcp
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- harunkumars
+- OLIOEX
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: activeadmin
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.4'
+description: Expose your ActiveAdmin resources to AI assistants via the Model Context
+  Protocol (MCP).
+email:
+- harun@betacraft.io
+- lloyd@olioex.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- app/controllers/activeadmin_mcp/mcp_controller.rb
+- app/models/activeadmin_mcp/api_token.rb
+- config/routes.rb
+- lib/activeadmin_mcp.rb
+- lib/activeadmin_mcp/configuration.rb
+- lib/activeadmin_mcp/engine.rb
+- lib/activeadmin_mcp/record_updater.rb
+- lib/activeadmin_mcp/request_handler.rb
+- lib/activeadmin_mcp/resource_registry.rb
+- lib/activeadmin_mcp/version.rb
+- lib/generators/activeadmin_mcp/install/install_generator.rb
+- lib/generators/activeadmin_mcp/install/templates/initializer.rb
+- lib/generators/activeadmin_mcp/install/templates/mcp_api_tokens.rb
+- lib/generators/activeadmin_mcp/install/templates/migration.rb.erb
+homepage: https://github.com/OLIOEX/activeadmin_mcp
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/OLIOEX/activeadmin_mcp
+  source_code_uri: https://github.com/OLIOEX/activeadmin_mcp
+  changelog_uri: https://github.com/OLIOEX/activeadmin_mcp/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: MCP server for Rails apps with ActiveAdmin
+test_files: []