administrate-mcp 0.1.0

data/lib/administrate/mcp/configuration.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require 'administrate/mcp/errors'
+require 'administrate/mcp/version'
+require 'administrate/mcp/authorization/base'
+require 'administrate/mcp/authorization/permissive'
+require 'administrate/mcp/authorization/pundit'
+
+module Administrate
+  module MCP
+    # Everything a host application supplies to the engine. Every entry has a default that works
+    # without the host, except the origins and `current_admin`, which the OAuth flow needs.
+    class Configuration
+      SKIPPED_FIELD_CLASSES = ['Administrate::Field::Password'].freeze
+
+      HAS_MANY_FIELD_CLASSES = ['Administrate::Field::HasMany'].freeze
+
+      FIELD_SERIALIZERS = {
+        'Administrate::Field::HasMany' => :has_many,
+        'Administrate::Field::Polymorphic' => :polymorphic,
+        'Administrate::Field::BelongsTo' => :belongs_to,
+        'Administrate::Field::HasOne' => :belongs_to,
+        'Administrate::Field::DateTime' => :datetime,
+        'Administrate::Field::Date' => :datetime,
+        'Administrate::Field::Time' => :datetime,
+        'Administrate::Field::Enum' => :enum,
+        'Administrate::Field::Select' => :enum,
+        'Administrate::Field::Shrine' => :attachment,
+        'Administrate::Field::String' => :scalar,
+        'Administrate::Field::Text' => :scalar,
+        'Administrate::Field::Email' => :scalar,
+        'Administrate::Field::Url' => :scalar,
+        'Administrate::Field::Number' => :scalar,
+        'Administrate::Field::Boolean' => :scalar
+      }.freeze
+
+      attr_accessor :server_name,
+                    :server_version,
+                    :issuer,
+                    :admin_origin,
+                    :current_admin,
+                    :admin_active,
+                    :identity_fallback,
+                    :oauth,
+                    :sign_in,
+                    :admin_class_name,
+                    :authorization,
+                    :default_required_roles,
+                    :tool_paths,
+                    :dashboard_paths,
+                    :instrument,
+                    :on_tool_call,
+                    :on_feedback,
+                    :on_error,
+                    :allow_localhost_redirects,
+                    :default_client_name,
+                    :sidekiq_stats_provider,
+                    :admin_route_namespace,
+                    :admin_url_options,
+                    :skipped_field_classes,
+                    :has_many_field_classes,
+                    :field_serializers
+
+      attr_reader :api_key_token_prefix
+
+      def initialize
+        assign_identity
+        assign_hooks
+        assign_fields
+      end
+
+      def assign_identity
+        @server_name = 'administrate_mcp'
+        @server_version = VERSION
+        @issuer = nil
+        @admin_origin = nil
+        @current_admin = ->(_controller) {}
+        @admin_active = ->(_admin) { true }
+        @identity_fallback = ->(_request) {}
+        @oauth = true
+        @sign_in = nil
+        @admin_class_name = 'Administrator'
+        @authorization = default_authorization
+        @default_required_roles = []
+        @tool_paths = []
+        @dashboard_paths = nil
+      end
+
+      def assign_hooks
+        @instrument = ->(tool_name:, admin:, &block) { block.call } # rubocop:disable Lint/UnusedBlockArgument
+        @on_tool_call = ->(tool_name:, admin:, arguments:, scopes:) {}
+        @on_feedback = ->(feedback) {}
+        @on_error = ->(exception) {}
+        @allow_localhost_redirects = true
+        @api_key_token_prefix = 'amcp_'
+        @default_client_name = 'MCP Client'
+        @sidekiq_stats_provider = nil
+      end
+
+      def assign_fields
+        @admin_route_namespace = :admin
+        @admin_url_options = {}
+        @skipped_field_classes = SKIPPED_FIELD_CLASSES.dup
+        @has_many_field_classes = HAS_MANY_FIELD_CLASSES.dup
+        @field_serializers = FIELD_SERIALIZERS.dup
+      end
+
+      # The prefix is what tells a bearer token apart from an OAuth token, so a blank one would send
+      # every OAuth token down the API key path.
+      def api_key_token_prefix=(prefix)
+        raise ArgumentError, 'api_key_token_prefix cannot be blank' if prefix.blank?
+
+        @api_key_token_prefix = prefix.to_s
+      end
+
+      def register_field(class_name, as: nil, &serializer)
+        @field_serializers = @field_serializers.merge(class_name.to_s => as || serializer)
+        self
+      end
+
+      def skip_field(*class_names)
+        @skipped_field_classes |= class_names.map(&:to_s)
+        self
+      end
+
+      def register_has_many_field(*class_names)
+        @has_many_field_classes |= class_names.map(&:to_s)
+        self
+      end
+
+      def issuer_for(request = nil)
+        resolve_origin(@issuer, request)
+      end
+
+      def admin_origin_for(request = nil)
+        resolve_origin(@admin_origin, request)
+      end
+
+      def dashboard_directories
+        Array(@dashboard_paths.presence || Rails.root.join('app/dashboards')).map(&:to_s)
+      end
+
+      private
+
+      def resolve_origin(origin, request)
+        return origin.arity.zero? ? origin.call : origin.call(request) if origin.respond_to?(:call)
+
+        origin.to_s
+      end
+
+      def default_authorization
+        defined?(::Pundit) ? Authorization::Pundit.new : Authorization::Permissive.new
+      end
+    end
+  end
+end

data/lib/administrate/mcp/dashboard_extension.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'administrate/base_dashboard'
+
+module Administrate
+  module MCP
+    # Adds the MCP declarations to every Administrate dashboard: the `mcp_action` macro and the
+    # `mcp_action_specs` store it writes to. `MCP_DESCRIPTION` and `MCP_BASE_SCOPE` stay plain
+    # constants, read by the registry.
+    module DashboardExtension
+      module ClassMethods
+        def mcp_action(name, **, &)
+          self.mcp_action_specs = [*mcp_action_specs, Administrate::MCP::Actions.build_spec(name, **, &)]
+        end
+      end
+
+      def self.install!
+        return if Administrate::BaseDashboard.respond_to?(:mcp_action_specs)
+
+        Administrate::BaseDashboard.class_attribute :mcp_action_specs, default: []
+        Administrate::BaseDashboard.singleton_class.prepend(ClassMethods)
+      end
+    end
+  end
+end

data/lib/administrate/mcp/engine.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # Mounts the models, controllers, tools and dashboard DSL into the host application.
+    class Engine < ::Rails::Engine
+      isolate_namespace Administrate::MCP
+
+      initializer 'administrate_mcp.inflection', before: :set_autoload_paths do
+        Rails.autoloaders.each { |loader| loader.inflector.inflect('mcp' => 'MCP') }
+      end
+
+      config.to_prepare do
+        require 'administrate/mcp/dashboard_extension'
+        Administrate::MCP::DashboardExtension.install!
+        Administrate::MCP::DashboardRegistry.reset!
+        Administrate::MCP::Actions.reset!
+      end
+    end
+  end
+end

data/lib/administrate/mcp/errors.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    class Error < StandardError
+    end
+
+    # Raised when the caller may not perform the requested action on the resource.
+    class UnauthorizedError < Error
+    end
+
+    # Raised when the host asked for something the configuration cannot deliver.
+    class ConfigurationError < Error
+    end
+
+    # Raised when the caller passes an argument the resource cannot honour. Surfaced verbatim so the
+    # caller can correct the call, rather than as an "Internal error".
+    class InvalidArgumentError < Error
+    end
+  end
+end

data/lib/administrate/mcp/loopback_uri.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # Recognises loopback redirect targets (RFC 8252). Subdomains of `.localhost` are used by
+    # parallel dev checkouts and are safe. Matches on the parsed host, never a string prefix —
+    # `localhost.attacker.com` is a normal, attacker-controlled DNS name and is rejected.
+    module LoopbackUri
+      HOSTS = %w[localhost 127.0.0.1 ::1].freeze
+
+      def self.localhost?(host)
+        return false if host.blank?
+
+        HOSTS.include?(host) || host.end_with?('.localhost')
+      end
+    end
+  end
+end

data/lib/administrate/mcp/rack_attack.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # Recommended Rack::Attack throttles for the OAuth endpoints. The gem does not depend on
+    # rack-attack: call this from the host's own Rack::Attack initializer.
+    module RackAttack
+      THROTTLES = [
+        { name: 'mcp_oauth/register/ip', limit: 5, period: 60, method: 'POST', path: '/oauth/register' },
+        { name: 'mcp_oauth/register/ip-day', limit: 50, period: 86_400, method: 'POST', path: '/oauth/register' },
+        { name: 'mcp_oauth/token/ip', limit: 10, period: 60, method: 'POST', path: '/oauth/token' }
+      ].freeze
+
+      AUTHORIZE_THROTTLE = {
+        name: 'mcp_oauth/authorize/ip',
+        limit: 20,
+        period: 60,
+        method: 'GET',
+        path: Routes::AUTHORIZE_PATH
+      }.freeze
+
+      # `host` is the MCP origin host, or a substring of it; the authorize throttle applies on the
+      # admin origin and is not host-scoped.
+      def self.throttles(host:)
+        THROTTLES.each do |rule|
+          ::Rack::Attack.throttle(rule[:name], limit: rule[:limit], period: rule[:period]) do |req|
+            req.remote_ip if req.request_method == rule[:method] && req.path == rule[:path] &&
+                             req.host.include?(host)
+          end
+        end
+
+        rule = AUTHORIZE_THROTTLE
+        ::Rack::Attack.throttle(rule[:name], limit: rule[:limit], period: rule[:period]) do |req|
+          req.remote_ip if req.request_method == rule[:method] && req.path == rule[:path]
+        end
+      end
+    end
+  end
+end

data/lib/administrate/mcp/routes.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # Route helpers for hosts that serve the protocol endpoints and the consent screen on different
+    # origins. Call them from inside the host's own `constraints` blocks. With `config.oauth` false
+    # only the JSON-RPC endpoint is drawn.
+    #
+    # Endpoints are Rack lambdas rather than "controller#action" strings so that resolving them
+    # never depends on an `MCP` acronym being registered in the host's global inflections.
+    module Routes
+      AUTHORIZE_PATH = '/mcp/oauth/authorize'
+
+      class << self
+        def draw_mcp_origin(mapper)
+          if oauth?
+            mapper.get '/.well-known/oauth-protected-resource', to: o_auth(:resource_metadata)
+            mapper.get '/.well-known/oauth-authorization-server', to: o_auth(:server_metadata)
+            mapper.post '/oauth/register', to: o_auth(:register)
+            mapper.post '/oauth/token', to: o_auth(:token)
+          end
+
+          mapper.match '/', to: json_rpc, via: %i[get post delete]
+        end
+
+        # A no-op when the OAuth server is off, so a host needs no conditional around the call.
+        def draw_admin_origin(mapper, path: AUTHORIZE_PATH)
+          return unless oauth?
+
+          mapper.get path, to: o_auth(:authorize)
+          mapper.post path, to: o_auth(:approve)
+        end
+
+        def oauth?
+          Administrate::MCP.config.oauth
+        end
+
+        def json_rpc
+          ->(env) { Administrate::MCP::JsonRpcController.action(:handle).call(env) }
+        end
+
+        def o_auth(action)
+          ->(env) { Administrate::MCP::OAuthController.action(action).call(env) }
+        end
+      end
+    end
+  end
+end

data/lib/administrate/mcp/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    VERSION = '0.1.0'
+  end
+end

data/lib/administrate/mcp.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'mcp'
+require 'administrate'
+
+require 'administrate/mcp/version'
+require 'administrate/mcp/errors'
+require 'administrate/mcp/loopback_uri'
+require 'administrate/mcp/configuration'
+require 'administrate/mcp/routes'
+require 'administrate/mcp/rack_attack'
+require 'administrate/mcp/cloudflare_access'
+require 'administrate/mcp/engine'
+
+module Administrate
+  # Model Context Protocol server for Administrate dashboards.
+  module MCP
+    def self.table_name_prefix
+      'administrate_mcp_'
+    end
+
+    def self.config
+      @config ||= Configuration.new
+    end
+
+    def self.configure
+      yield(config)
+      config
+    end
+
+    def self.reset_config!
+      @config = Configuration.new
+    end
+  end
+end

data/lib/administrate-mcp.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'administrate/mcp'

metadata

@@ -0,0 +1,160 @@
+--- !ruby/object:Gem::Specification
+name: administrate-mcp
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sorare
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: administrate
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0.beta3
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0.beta3
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+description: Rails engine exposing Administrate dashboards over the Model Context
+  Protocol, with API key and OAuth 2.1 authentication.
+email:
+- engineering@sorare.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- app/controllers/administrate/mcp/json_rpc_controller.rb
+- app/controllers/administrate/mcp/o_auth_controller.rb
+- app/lib/administrate/mcp/actions.rb
+- app/lib/administrate/mcp/admin_dashboard_tool.rb
+- app/lib/administrate/mcp/authentication.rb
+- app/lib/administrate/mcp/base_tool.rb
+- app/lib/administrate/mcp/clean_old_feedbacks.rb
+- app/lib/administrate/mcp/dashboard_registry.rb
+- app/lib/administrate/mcp/fast_search.rb
+- app/lib/administrate/mcp/field_serializer.rb
+- app/lib/administrate/mcp/o_auth_service.rb
+- app/lib/administrate/mcp/report_improvement.rb
+- app/lib/administrate/mcp/server_builder.rb
+- app/lib/administrate/mcp/tools/admin_resource_list.rb
+- app/lib/administrate/mcp/tools/admin_resource_list_resources.rb
+- app/lib/administrate/mcp/tools/admin_resource_show.rb
+- app/lib/administrate/mcp/tools/report_improvement.rb
+- app/lib/administrate/mcp/tools/sidekiq_retries.rb
+- app/lib/administrate/mcp/tools/sidekiq_stats.rb
+- app/models/administrate/mcp/api_key.rb
+- app/models/administrate/mcp/application_record.rb
+- app/models/administrate/mcp/feedback.rb
+- app/models/administrate/mcp/o_auth_access_grant.rb
+- app/models/administrate/mcp/o_auth_access_token.rb
+- app/models/administrate/mcp/o_auth_application.rb
+- app/views/administrate/mcp/o_auth/authorize.html.erb
+- config/routes.rb
+- db/migrate/20260101000001_create_administrate_model_context_protocol_api_keys.rb
+- db/migrate/20260101000002_create_administrate_model_context_protocol_feedbacks.rb
+- db/migrate/20260101000003_create_administrate_model_context_protocol_authorization_tables.rb
+- docs/admin-integration.md
+- docs/authentication.md
+- docs/configuration.md
+- docs/dashboards.md
+- docs/development.md
+- docs/oauth.md
+- docs/routes.md
+- lib/administrate-mcp.rb
+- lib/administrate/mcp.rb
+- lib/administrate/mcp/authorization/base.rb
+- lib/administrate/mcp/authorization/permissive.rb
+- lib/administrate/mcp/authorization/pundit.rb
+- lib/administrate/mcp/cloudflare_access.rb
+- lib/administrate/mcp/configuration.rb
+- lib/administrate/mcp/dashboard_extension.rb
+- lib/administrate/mcp/engine.rb
+- lib/administrate/mcp/errors.rb
+- lib/administrate/mcp/loopback_uri.rb
+- lib/administrate/mcp/rack_attack.rb
+- lib/administrate/mcp/routes.rb
+- lib/administrate/mcp/version.rb
+homepage: https://github.com/sorare/administrate-mcp
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/sorare/administrate-mcp
+  changelog_uri: https://github.com/sorare/administrate-mcp/blob/master/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.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Model Context Protocol server for Administrate dashboards
+test_files: []