administrate-mcp 0.1.0

data/app/models/administrate/mcp/feedback.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # Improvement feedback submitted by MCP users.
+    class Feedback < ApplicationRecord
+      self.table_name = 'administrate_mcp_feedbacks'
+
+      belongs_to_admin
+      belongs_to :api_key, class_name: 'Administrate::MCP::ApiKey', optional: true, inverse_of: :feedbacks
+
+      enum :category,
+           { description: 0, missing_filter: 1, missing_field: 2, missing_resource: 3, serialization: 4, other: 5 }
+      enum :status, { pending: 0, accepted: 1, rejected: 2, shipped: 3 }, prefix: true
+
+      validates :suggestion, presence: true
+      validates :category, presence: true
+    end
+  end
+end

data/app/models/administrate/mcp/o_auth_access_grant.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # Short-lived authorization code for the MCP OAuth 2.1 flow (10-minute TTL).
+    class OAuthAccessGrant < ApplicationRecord
+      self.table_name = 'administrate_mcp_oauth_access_grants'
+
+      DEFAULT_EXPIRES_IN = 10.minutes.to_i
+
+      belongs_to_admin
+      belongs_to :application, class_name: 'Administrate::MCP::OAuthApplication', inverse_of: :access_grants
+
+      validates :token_digest, presence: true, uniqueness: true
+      validates :redirect_uri, presence: true
+      validates :code_challenge, presence: true
+      validates :expires_in, presence: true
+
+      attr_reader :plaintext_token
+
+      class << self
+        def generate_token
+          SecureRandom.hex(32)
+        end
+
+        def digest(plaintext)
+          Digest::SHA256.hexdigest(plaintext)
+        end
+
+        def find_by_token(plaintext)
+          find_by(token_digest: digest(plaintext))
+        end
+
+        def issue(
+          admin:, application:, redirect_uri:, code_challenge:, code_challenge_method:, scopes:,
+          expires_in: DEFAULT_EXPIRES_IN
+        )
+          plaintext_token = generate_token
+
+          create!(
+            admin:,
+            application:,
+            token_digest: digest(plaintext_token),
+            redirect_uri:,
+            code_challenge:,
+            code_challenge_method:,
+            scopes:,
+            expires_in:
+          ).tap { |grant| grant.instance_variable_set(:@plaintext_token, plaintext_token) }
+        end
+      end
+
+      def reload(...)
+        @plaintext_token = nil
+        super
+      end
+
+      def expired?
+        created_at + expires_in.seconds < Time.current
+      end
+
+      def revoked?
+        revoked_at.present?
+      end
+
+      def revoke!
+        update!(revoked_at: Time.current)
+      end
+
+      def verify_code_challenge(verifier)
+        digest = Base64.urlsafe_encode64(Digest::SHA256.digest(verifier), padding: false)
+        ActiveSupport::SecurityUtils.secure_compare(digest, code_challenge)
+      end
+    end
+  end
+end

data/app/models/administrate/mcp/o_auth_access_token.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # MCP OAuth 2.1 access token (1-week TTL).
+    class OAuthAccessToken < ApplicationRecord
+      self.table_name = 'administrate_mcp_oauth_access_tokens'
+
+      DEFAULT_EXPIRES_IN = 1.week.to_i
+
+      belongs_to_admin
+      belongs_to :application, class_name: 'Administrate::MCP::OAuthApplication', inverse_of: :access_tokens
+
+      validates :token_digest, presence: true, uniqueness: true
+      validates :refresh_token_digest, presence: true, uniqueness: true
+      validates :expires_in, presence: true
+
+      scope :active, -> { where(revoked_at: nil) }
+
+      attr_reader :plaintext_token, :plaintext_refresh_token
+
+      class << self
+        def generate_token
+          SecureRandom.hex(32)
+        end
+
+        def generate_refresh_token
+          SecureRandom.hex(32)
+        end
+
+        def digest(plaintext)
+          Digest::SHA256.hexdigest(plaintext)
+        end
+
+        def find_by_token(plaintext)
+          find_by(token_digest: digest(plaintext))
+        end
+
+        def find_by_refresh_token(plaintext)
+          find_by(refresh_token_digest: digest(plaintext))
+        end
+
+        def issue(admin:, application:, scopes:, expires_in: DEFAULT_EXPIRES_IN)
+          plaintext_token = generate_token
+          plaintext_refresh_token = generate_refresh_token
+
+          create!(
+            admin:,
+            application:,
+            token_digest: digest(plaintext_token),
+            refresh_token_digest: digest(plaintext_refresh_token),
+            expires_in:,
+            scopes:
+          ).tap do |token|
+            token.instance_variable_set(:@plaintext_token, plaintext_token)
+            token.instance_variable_set(:@plaintext_refresh_token, plaintext_refresh_token)
+          end
+        end
+      end
+
+      def reload(...)
+        @plaintext_token = nil
+        @plaintext_refresh_token = nil
+        super
+      end
+
+      def expired?
+        created_at + expires_in.seconds < Time.current
+      end
+
+      def revoked?
+        revoked_at.present?
+      end
+
+      def accessible?
+        !revoked? && !expired?
+      end
+
+      def revoke!
+        update!(revoked_at: Time.current)
+      end
+    end
+  end
+end

data/app/models/administrate/mcp/o_auth_application.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # OAuth 2.1 client application registered via Dynamic Client Registration.
+    class OAuthApplication < ApplicationRecord
+      self.table_name = 'administrate_mcp_oauth_applications'
+
+      MAX_REDIRECT_URIS = 5
+
+      has_many :access_grants,
+               class_name: 'Administrate::MCP::OAuthAccessGrant',
+               foreign_key: :application_id,
+               dependent: :destroy,
+               inverse_of: :application
+      has_many :access_tokens,
+               class_name: 'Administrate::MCP::OAuthAccessToken',
+               foreign_key: :application_id,
+               dependent: :destroy,
+               inverse_of: :application
+
+      validates :client_id, presence: true, uniqueness: true
+      validates :name, presence: true, length: { maximum: 255 }
+      validates :redirect_uris, presence: true
+      validate :validate_redirect_uris
+
+      before_validation :sanitize_name
+
+      def self.generate_client_id
+        SecureRandom.hex(16)
+      end
+
+      private
+
+      def sanitize_name
+        self.name = ActionController::Base.helpers.strip_tags(name)&.strip if name.present?
+      end
+
+      def validate_redirect_uris
+        return if redirect_uris.blank?
+
+        if redirect_uris.length > MAX_REDIRECT_URIS
+          errors.add(:redirect_uris, "must not exceed #{MAX_REDIRECT_URIS} URIs")
+          return
+        end
+
+        redirect_uris.each { |uri_string| validate_single_redirect_uri(uri_string) }
+      end
+
+      def validate_single_redirect_uri(uri_string)
+        uri = URI.parse(uri_string)
+        return if uri.scheme == 'http' && loopback_allowed?(uri.hostname)
+
+        errors.add(:redirect_uris, "#{uri_string} must use https scheme") unless uri.scheme == 'https'
+      rescue URI::InvalidURIError
+        errors.add(:redirect_uris, "#{uri_string} is not a valid URI")
+      end
+
+      def loopback_allowed?(host)
+        Administrate::MCP.config.allow_localhost_redirects && LoopbackUri.localhost?(host)
+      end
+    end
+  end
+end

data/app/views/administrate/mcp/o_auth/authorize.html.erb

@@ -0,0 +1,63 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Authorize MCP access</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <style>
+    body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; background: #f5f5f5; display: flex; justify-content: center; align-items: center; min-height: 100vh; margin: 0; }
+    .card { background: #fff; border-radius: 8px; box-shadow: 0 2px 8px rgba(0,0,0,0.1); padding: 2rem; max-width: 400px; width: 100%; }
+    h1 { font-size: 1.25rem; margin: 0 0 1rem; }
+    p { color: #555; line-height: 1.5; }
+    .actions { display: flex; gap: 0.75rem; margin-top: 1.5rem; }
+    button { flex: 1; padding: 0.75rem; border-radius: 6px; font-size: 1rem; cursor: pointer; border: 1px solid #ddd; }
+    .approve { background: #2563eb; color: #fff; border-color: #2563eb; }
+    .approve:hover { background: #1d4ed8; }
+    .deny { background: #fff; }
+    .deny:hover { background: #f5f5f5; }
+    .details { margin: 1.25rem 0 0; border: 1px solid #eee; border-radius: 6px; padding: 0.75rem 1rem; background: #fafafa; }
+    .details dt { font-size: 0.75rem; text-transform: uppercase; letter-spacing: 0.03em; color: #888; margin-top: 0.5rem; }
+    .details dt:first-child { margin-top: 0; }
+    .details dd { margin: 0.2rem 0 0; color: #222; word-break: break-all; }
+    .details .host { font-weight: 600; }
+    .details code { background: #eee; border-radius: 4px; padding: 0.05rem 0.35rem; font-size: 0.85rem; }
+    .scope-write { color: #b45309; font-weight: 600; }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <h1>Authorize MCP access</h1>
+    <p><strong><%= @application.name %></strong> is requesting access to the admin MCP server on your behalf.</p>
+    <dl class="details">
+      <dt>Redirects to</dt>
+      <dd>
+        <span class="host"><%= @redirect_host || 'unknown host' %></span>
+        <div><%= @redirect_uri %></div>
+      </dd>
+      <dt>Access requested</dt>
+      <dd>
+        <% if @scopes.empty? %>
+          Read-only
+        <% else %>
+          <% @scopes.each do |scope| %>
+            <code class="<%= 'scope-write' if scope == 'write' %>"><%= scope %></code>
+          <% end %>
+        <% end %>
+      </dd>
+    </dl>
+    <p>Only authorize if you recognize this application and the destination above.</p>
+    <%= form_tag(request.fullpath, method: :post) do %>
+      <%= hidden_field_tag :client_id, params[:client_id] %>
+      <%= hidden_field_tag :redirect_uri, params[:redirect_uri] %>
+      <%= hidden_field_tag :state, params[:state] %>
+      <%= hidden_field_tag :code_challenge, params[:code_challenge] %>
+      <%= hidden_field_tag :code_challenge_method, params[:code_challenge_method] %>
+      <%= hidden_field_tag :scope, params[:scope] %>
+      <%= hidden_field_tag :response_type, params[:response_type] %>
+      <div class="actions">
+        <button type="submit" name="deny" value="1" class="deny">Deny</button>
+        <button type="submit" class="approve">Authorize</button>
+      </div>
+    <% end %>
+  </div>
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+Administrate::MCP::Engine.routes.draw do
+  Administrate::MCP::Routes.draw_mcp_origin(self)
+  Administrate::MCP::Routes.draw_admin_origin(self, path: '/oauth/authorize')
+end

data/db/migrate/20260101000001_create_administrate_model_context_protocol_api_keys.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class CreateAdministrateModelContextProtocolApiKeys < ActiveRecord::Migration[8.1]
+  def change
+    create_table :administrate_mcp_api_keys, id: :uuid, if_not_exists: true do |t|
+      t.uuid :admin_id, null: false
+      t.string :token_digest, null: false
+      t.string :token_prefix, null: false
+      t.string :name, null: false
+      t.boolean :write_access, null: false, default: false
+      t.datetime :last_used_at
+      t.datetime :revoked_at
+
+      t.timestamps
+    end
+
+    add_index :administrate_mcp_api_keys, :admin_id, if_not_exists: true
+    add_index :administrate_mcp_api_keys, :token_digest, unique: true, if_not_exists: true
+  end
+end

data/db/migrate/20260101000002_create_administrate_model_context_protocol_feedbacks.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+class CreateAdministrateModelContextProtocolFeedbacks < ActiveRecord::Migration[8.1]
+  def change
+    create_table :administrate_mcp_feedbacks, id: :uuid, if_not_exists: true do |t|
+      t.uuid :admin_id
+      t.uuid :api_key_id
+      t.integer :category, null: false
+      t.string :resource_name
+      t.text :suggestion, null: false
+      t.integer :status, null: false, default: 0
+
+      t.timestamps
+    end
+
+    add_index :administrate_mcp_feedbacks, :admin_id, if_not_exists: true
+    add_index :administrate_mcp_feedbacks, :api_key_id, if_not_exists: true
+  end
+end

data/db/migrate/20260101000003_create_administrate_model_context_protocol_authorization_tables.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+class CreateAdministrateModelContextProtocolAuthorizationTables < ActiveRecord::Migration[8.1]
+  def change
+    create_table :administrate_mcp_oauth_applications, id: :uuid, if_not_exists: true do |t|
+      t.string :client_id, null: false
+      t.text :client_secret_digest
+      t.text :redirect_uris, array: true, default: [], null: false
+      t.string :grant_types, array: true, default: ['authorization_code'], null: false
+      t.string :name, null: false
+
+      t.timestamps
+    end
+
+    add_index :administrate_mcp_oauth_applications, :client_id, unique: true, if_not_exists: true
+
+    create_table :administrate_mcp_oauth_access_grants, id: :uuid, if_not_exists: true do |t|
+      t.uuid :admin_id, null: false
+      t.uuid :application_id, null: false
+      t.string :token_digest, null: false
+      t.integer :expires_in, null: false
+      t.text :redirect_uri, null: false
+      t.string :scopes, default: ''
+      t.string :code_challenge, null: false
+      t.string :code_challenge_method, null: false, default: 'S256'
+      t.datetime :revoked_at
+
+      t.datetime :created_at, null: false
+    end
+
+    add_index :administrate_mcp_oauth_access_grants, :admin_id, if_not_exists: true
+    add_index :administrate_mcp_oauth_access_grants, :application_id, if_not_exists: true
+    add_index :administrate_mcp_oauth_access_grants, :token_digest, unique: true, if_not_exists: true
+
+    create_table :administrate_mcp_oauth_access_tokens, id: :uuid, if_not_exists: true do |t|
+      t.uuid :admin_id, null: false
+      t.uuid :application_id, null: false
+      t.string :token_digest, null: false
+      t.string :refresh_token_digest, null: false
+      t.integer :expires_in, null: false
+      t.string :scopes, default: ''
+      t.datetime :revoked_at
+
+      t.datetime :created_at, null: false
+    end
+
+    add_index :administrate_mcp_oauth_access_tokens, :admin_id, if_not_exists: true
+    add_index :administrate_mcp_oauth_access_tokens, :application_id, if_not_exists: true
+    add_index :administrate_mcp_oauth_access_tokens, :token_digest, unique: true, if_not_exists: true
+    add_index :administrate_mcp_oauth_access_tokens, :refresh_token_digest, unique: true, if_not_exists: true
+  end
+end

data/docs/admin-integration.md

@@ -0,0 +1,56 @@
+# Admin integration
+
+[Back to README](../README.md)
+
+## Exposing the engine's own tables in your admin
+
+The engine's records keep their namespace in `model_name`, so `Administrate::MCP::ApiKey` routes as
+`administrate_mcp_api_keys` and never shadows a resource of your own called `api_keys`. Administrate
+needs three things to manage a namespaced model:
+
+```ruby
+# config/routes.rb, inside your admin namespace
+namespace :admin do
+  resources :administrate_mcp_api_keys
+  resources :administrate_mcp_feedbacks, only: %i[index show destroy]
+end
+
+# app/dashboards/administrate_mcp/api_key_dashboard.rb
+module AdministrateMcp
+  class ApiKeyDashboard < Administrate::BaseDashboard
+    ATTRIBUTE_TYPES = { id: Field::String, name: Field::String, admin: Field::BelongsTo }.freeze
+    COLLECTION_ATTRIBUTES = %i[id name].freeze
+    SHOW_PAGE_ATTRIBUTES = %i[id name admin].freeze
+    FORM_ATTRIBUTES = %i[name].freeze
+
+    def self.model
+      Administrate::MCP::ApiKey
+    end
+  end
+end
+
+# app/controllers/admin/administrate_mcp_api_keys_controller.rb
+module Admin
+  class AdministrateMcpApiKeysController < Admin::ApplicationController
+    def resource_class = Administrate::MCP::ApiKey
+    def dashboard_class = AdministrateMcp::ApiKeyDashboard
+  end
+end
+```
+
+The MCP registry finds the dashboard through `self.model`, registers it as
+`administrate/mcp/api_key`, and builds record URLs from the namespaced route key.
+
+## Customising the consent screen
+
+Override `app/views/administrate/mcp/o_auth/authorize.html.erb` in your application. The template
+has `@application`, `@redirect_uri`, `@redirect_host` and `@scopes`.
+
+## Feedback housekeeping
+
+`Administrate::MCP::CleanOldFeedbacks.call(till: 2.months.ago)` deletes one batch of 10,000 and
+reports `more?`; schedule it however your app schedules work.
+
+`ReportImprovement`, which backs the `report_mcp_improvement` tool, is a plain object in the same
+style: it returns a result struct and does no scheduling of its own. Both services leave the decision
+of how and when to run them to the host application.

data/docs/authentication.md

@@ -0,0 +1,116 @@
+# Authentication
+
+[Back to README](../README.md)
+
+A request is authenticated in this order: an API key, then, if `oauth` is enabled, the engine's own
+OAuth access token, then `identity_fallback`. The first credential the request presents that the
+engine recognises settles the call; `identity_fallback` is only consulted when nothing the engine
+issued matched.
+
+**API keys.** Create one yourself and hand the plaintext to the user once:
+
+```ruby
+token = Administrate::MCP::ApiKey.generate_token
+Administrate::MCP::ApiKey.create!(admin:, name: 'Laptop', token_digest: Administrate::MCP::ApiKey.digest_token(token),
+                                  token_prefix: token[0, 13])
+```
+
+Only the digest is stored. Keys are read-only unless `write_access` is set.
+
+If you are migrating keys that were issued before you adopted this gem, set `api_key_token_prefix`
+to the prefix those keys already carry. The plaintext is not recoverable, only its digest and the
+first 13 characters are stored in `token_prefix`, so a changed prefix makes every existing key stop
+matching, and the holders have to be issued new ones.
+
+**OAuth 2.1.** Clients register themselves, send the user to the consent screen on the admin origin,
+and exchange the code with PKCE. Access tokens last a week, authorization codes ten minutes, and
+refreshing revokes the old token. See [OAuth](oauth.md) for turning it off.
+
+## Identity fallback
+
+Some deployments authenticate the caller before the request reaches Rails. Cloudflare Access managed
+OAuth is the common case: Access resolves the client's bearer token at its own edge and forwards an
+assertion, so the application only ever sees a token no row of ours matches. `identity_fallback` is
+where you turn that assertion into an admin:
+
+```ruby
+c.identity_fallback = lambda do |request|
+  email = CloudflareAccess.email(request) # your own verification of the Access JWT
+  next nil unless email
+
+  admin = Administrator.find_by(email:)
+  unless admin
+    raise Administrate::MCP::Authentication::ExternalIdentityError.new(
+      "No admin account for #{email}",
+      auth_error_type: 'cloudflare_access'
+    )
+  end
+
+  Administrate::MCP::Authentication::Identity.new(admin:, scopes: ['write'])
+end
+```
+
+It is consulted only when nothing the engine issued matched: an absent `Authorization` header, or a
+bearer token that is neither an API key by prefix nor a row in the OAuth tokens table. A key or token
+that _is_ recognised and then fails, revoked, expired, unknown digest, raises as before and never
+reaches the fallback, so a revoked credential cannot be laundered into an Access identity. Returning
+nil leaves that refusal in place. Raising `ExternalIdentityError` is how you say "I know who
+this is and they have no account": it answers 401 with the `auth_error_type` you pass as
+`X-Auth-Error` and JSON-RPC code `-32001`. `admin_active` applies to fallback identities too.
+
+A credential outlives the admin who holds it: revoking someone's admin role, deactivating or
+anonymizing their account does nothing to a key or token they were already issued, and a tool such as
+`sidekiq_retries` never consults the authorization adapter. Set `admin_active` so every call
+re-checks the person, not only the credential.
+
+The JSON-RPC endpoint authenticates by bearer token only and never reads the session cookie: hosts
+routinely share a session across sibling subdomains, and a browser signed into the admin UI must not
+thereby be able to drive the protocol endpoint.
+
+### Cloudflare Access
+
+Edge-managed OAuth in front of an MCP server is a common deployment, so one verifier for it ships
+with the gem. `Administrate::MCP::CloudflareAccess` implements the `identity_fallback` contract shown
+above: a callable taking the request, returning an `Authentication::Identity` or nil, and raising
+`ExternalIdentityError` to signal an identity Access has asserted but that has no admin account. Use
+it as a template for any other provider.
+
+It answers `call(request)`, so it can be assigned to `identity_fallback` directly, in the same
+`config/initializers/administrate_mcp.rb` as the rest of your configuration: no `to_prepare` wrapper
+and no deferred reference, the class is requirable the moment the gem is. It lives in `lib/`, not
+`app/`, alongside `Routes` and `RackAttack`, so an initializer can name it before autoloading is
+available.
+
+```ruby
+Administrate::MCP.configure do |c|
+  c.oauth = false
+  c.identity_fallback = Administrate::MCP::CloudflareAccess.new(
+    team_domain: -> { ENV.fetch('CLOUDFLARE_ACCESS_TEAM_DOMAIN', nil) },
+    audience: -> { ENV.fetch('CLOUDFLARE_ACCESS_MCP_AUD', nil) },
+    find_admin: ->(email) { Administrator.find_by(email:) },
+    scopes_for: ->(admin) { admin.mcp_write_access? ? ['write'] : [] }
+  )
+end
+```
+
+It reads the `Cf-Access-Jwt-Assertion` header, verifies the RS256 signature against the JWKS at
+`<team_domain>/cdn-cgi/access/certs` (cached an hour, refetched once when a key id is unknown, which
+is what a key rotation looks like), and checks the issuer and audience. `find_admin` receives the
+lowercased email and `scopes_for` the admin it returned; returning no admin raises
+`ExternalIdentityError` with `X-Auth-Error: cloudflare_access`.
+
+`team_domain` and `audience` each take a value or a callable. Pass lambdas, as above. The object is
+built once, in an initializer, and reads these two settings again on every call rather than at
+construction: a plain `ENV.fetch` at construction time would be read once at boot, and in an
+environment where those variables are set later, or not set at all, the object would be permanently
+unconfigured and would quietly refuse every request. A lambda re-read on each call lets the settings
+arrive after boot, and lets a spec change them.
+
+A blank `team_domain` or `audience` means the verifier accepts **nothing**. It returns nil for every
+assertion without calling Cloudflare; it does not fall through to an unverified one, and it does not
+skip the audience check. Configuring it everywhere and enabling it per environment is therefore safe,
+but so is getting it wrong: a typo in the audience variable refuses all callers rather than admitting
+assertions minted for some other Access application.
+
+Access must be in front of the JSON-RPC origin for this to mean anything: the assertion is only
+trustworthy because nothing can reach the application without passing through Access.