activerecord-mcp 0.1.0

data/docs/querying.md

@@ -0,0 +1,171 @@
+# Querying
+
+activerecord-mcp exposes five built-in tools. All queries go through hash conditions validated against actual column names — no raw SQL is accepted at any layer.
+
+## Default fields
+
+Every query tool returns only `id`, `created_at`, and `updated_at` by default. Pass a `fields` array to retrieve additional columns. This default can be changed via [`configuration`](configuration.md).
+
+## Tools
+
+### `list_models`
+
+Lists all accessible ActiveRecord model names.
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "tools/call",
+  "params": {
+    "name": "list_models",
+    "arguments": {}
+  },
+  "id": 1
+}
+```
+
+Response:
+```json
+["Order", "Post", "User"]
+```
+
+---
+
+### `describe_model`
+
+Returns columns (name, type, nullability, default), and associations for a model.
+
+```json
+{
+  "name": "describe_model",
+  "arguments": { "model": "User" }
+}
+```
+
+Response:
+```json
+{
+  "model": "User",
+  "table": "users",
+  "primary_key": "id",
+  "columns": [
+    { "name": "id",         "type": "integer", "null": false, "default": null },
+    { "name": "email",      "type": "string",  "null": false, "default": null },
+    { "name": "created_at", "type": "datetime","null": false, "default": null }
+  ],
+  "associations": [
+    { "name": "posts", "macro": "has_many", "class_name": "Post" }
+  ]
+}
+```
+
+Denied columns are excluded from the output — they do not appear in `columns` at all.
+
+---
+
+### `query_records`
+
+Queries records with hash conditions.
+
+| Argument | Type | Required | Description |
+|----------|------|----------|-------------|
+| `model` | string | yes | Model class name, e.g. `"User"` |
+| `conditions` | object | no | Column/value pairs for WHERE clause |
+| `fields` | array of strings | no | Columns to return (defaults to id + timestamps) |
+| `limit` | integer | no | Max records; silently capped at `max_limit` (default 100) |
+| `offset` | integer | no | Records to skip; raises an error if it exceeds `max_offset` (default 10,000) |
+| `order` | string | no | `"column_name ASC"` or `"column_name DESC"` |
+
+```json
+{
+  "name": "query_records",
+  "arguments": {
+    "model": "User",
+    "conditions": { "active": true },
+    "fields": ["id", "name", "email"],
+    "limit": 25,
+    "offset": 0,
+    "order": "created_at DESC"
+  }
+}
+```
+
+Response:
+```json
+[
+  { "id": 1, "name": "Alice", "email": "alice@example.com" },
+  { "id": 2, "name": "Bob",   "email": "bob@example.com" }
+]
+```
+
+**Condition values** must be scalars (`string`, `integer`, `float`, `boolean`, `null`) or arrays of scalars (for SQL `IN`). Hash values are rejected to prevent operator injection.
+
+```json
+{ "conditions": { "status": ["active", "pending"] } }
+```
+
+---
+
+### `find_record`
+
+Finds a single record by primary key.
+
+| Argument | Type | Required | Description |
+|----------|------|----------|-------------|
+| `model` | string | yes | Model class name |
+| `id` | integer | yes | Primary key value |
+| `fields` | array of strings | no | Columns to return |
+
+```json
+{
+  "name": "find_record",
+  "arguments": {
+    "model": "User",
+    "id": 42,
+    "fields": ["name", "email", "created_at"]
+  }
+}
+```
+
+Response:
+```json
+{ "name": "Alice", "email": "alice@example.com", "created_at": "2024-01-15T10:00:00.000Z" }
+```
+
+Returns an error if the record does not exist.
+
+---
+
+### `count_records`
+
+Counts records matching hash conditions.
+
+| Argument | Type | Required | Description |
+|----------|------|----------|-------------|
+| `model` | string | yes | Model class name |
+| `conditions` | object | no | Column/value pairs for WHERE clause |
+
+```json
+{
+  "name": "count_records",
+  "arguments": {
+    "model": "Order",
+    "conditions": { "status": "pending" }
+  }
+}
+```
+
+Response:
+```json
+{ "count": 17 }
+```
+
+---
+
+## Security model
+
+- **Column validation** — every column in `fields`, `conditions`, and `order` is checked against the allowed column list before the query runs. Unknown or denied columns raise an error.
+- **Value validation** — condition values must be scalars or arrays of scalars. Hash values (which could trigger Rails 7.1+ predicate operators) are rejected.
+- **Quoted identifiers** — `SELECT` columns are quoted via Arel; `ORDER BY` columns are quoted via `quote_column_name`. No raw string interpolation reaches the DB.
+- **Output strip** — denied columns are stripped from serialized output after the query, independent of the pre-query validation.
+- **No raw SQL** — there is no `sql:` or `raw:` parameter on any tool.

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module RailsMcp
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates an activerecord-mcp initializer in config/initializers"
+
+      def copy_initializer
+        template "initializer.rb", "config/initializers/rails_mcp.rb"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+RailsMcp.configure do |config|
+  # The database role used for every query.
+  # Queries run via ActiveRecord's connected_to(role:), so this maps directly
+  # to a role defined in your database.yml. The default :reading role works
+  # out of the box with Rails' standard replica setup. Set to :writing if
+  # your app uses a single database with no named roles.
+  #
+  # config.database_role = :reading
+
+  # Columns returned when no fields are specified in a tool call.
+  # These are also automatically included when a schema_file is configured,
+  # even if the file omits them.
+  #
+  # config.default_fields = [:id, :created_at, :updated_at]
+
+  # Allowlist of model names the MCP can access.
+  # When non-empty, any model not in this list returns an error.
+  # Ignored when schema_file is set — the file's model list takes precedence.
+  #
+  # config.allowed_models = %w[User Post Order]
+
+  # Denylist of model names that are never accessible, regardless of allowed_models.
+  # Ignored when schema_file is set.
+  #
+  # config.denied_models = %w[AdminUser AuditLog]
+
+  # Columns that are completely invisible across all models and all tools.
+  # Accepts exact strings and/or regexes. Matching columns cannot be returned,
+  # used in conditions, or used in order — even if they appear in schema_file.
+  # Applied as the final layer, so it always wins over every other config.
+  #
+  # config.denied_columns = [
+  #   "password_digest",
+  #   "encrypted_password",
+  #   /token/i,
+  #   /secret/i,
+  #   /api_key/i,
+  # ]
+
+  # Maximum number of records a single query_records call can return.
+  # Client-supplied limit values are silently capped to this. Nil or zero
+  # limits also resolve to this value.
+  #
+  # config.max_limit = 100
+
+  # Maximum offset value accepted by query_records.
+  # Unlike max_limit, exceeding this raises an error rather than silently
+  # clamping — a clamped offset would return the wrong page without any
+  # indication to the caller.
+  #
+  # config.max_offset = 10_000
+
+  # Path to a YAML file that defines exactly which models and columns are
+  # accessible. When set, allowed_models and denied_models are ignored —
+  # the file's model list is the authoritative allowlist. id, created_at,
+  # and updated_at are still auto-included from default_fields even if
+  # omitted from the file. denied_columns still applies on top.
+  #
+  # config.schema_file = Rails.root.join("config/rails_mcp.yml")
+
+  # OAuth scope that every Bearer token must include. Tokens that are
+  # otherwise valid (not expired, not revoked) but lack this scope are
+  # rejected with 403 insufficient_scope. Set to nil to disable the check.
+  # Your Doorkeeper config must declare the same scope via optional_scopes.
+  #
+  # config.scope = "mcp"
+end

data/lib/rails_mcp/auth/token_validator.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module RailsMcp
+  module Auth
+    class TokenValidator
+      WELL_KNOWN_PREFIX = "/.well-known/"
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        request = Rack::Request.new(env)
+
+        # CORS preflight and public discovery endpoints bypass auth
+        return @app.call(env) if request.options?
+        return @app.call(env) if request.path.start_with?(WELL_KNOWN_PREFIX)
+
+        token_string = extract_bearer_token(env)
+        return unauthorized("Bearer token required") if token_string.nil?
+
+        token = Doorkeeper::AccessToken.by_token(token_string)
+        return unauthorized("Invalid or expired token") if token.nil? || token.revoked? || token.expired?
+
+        required = RailsMcp.configuration.scope
+        return insufficient_scope(required) if required && !required.empty? && !token.scopes.include?(required)
+
+        env["rails_mcp.access_token"] = token
+        @app.call(env)
+      end
+
+      private
+
+      def extract_bearer_token(env)
+        auth = env["HTTP_AUTHORIZATION"]
+        return nil unless auth&.start_with?("Bearer ")
+
+        auth.delete_prefix("Bearer ").strip
+      end
+
+      def unauthorized(message)
+        body = { error: "invalid_token", error_description: message }.to_json
+        [
+          401,
+          { "Content-Type" => "application/json", "WWW-Authenticate" => 'Bearer realm="activerecord-mcp"' },
+          [body]
+        ]
+      end
+
+      def insufficient_scope(scope)
+        body = { error: "insufficient_scope", error_description: "Token missing required scope: #{scope}" }.to_json
+        [
+          403,
+          {
+            "Content-Type" => "application/json",
+            "WWW-Authenticate" => "Bearer realm=\"activerecord-mcp\", error=\"insufficient_scope\", scope=\"#{scope}\""
+          },
+          [body]
+        ]
+      end
+    end
+  end
+end

data/lib/rails_mcp/configuration.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module RailsMcp
+  class Configuration
+    attr_accessor :database_role,
+                  :default_fields,
+                  :allowed_models,
+                  :denied_models,
+                  :denied_columns,
+                  :max_limit,
+                  :max_offset,
+                  :schema_file,
+                  :scope
+
+    def initialize
+      @database_role  = :reading
+      @default_fields = %i[id created_at updated_at]
+      @allowed_models = []
+      @denied_models  = []
+      @denied_columns = []
+      @max_limit      = 100
+      @max_offset     = 10_000
+      @schema_file    = nil
+      @scope          = "mcp"
+    end
+
+    def column_denied?(name)
+      denied_columns.any? do |pattern|
+        pattern.is_a?(Regexp) ? pattern.match?(name.to_s) : pattern.to_s == name.to_s
+      end
+    end
+  end
+end

data/lib/rails_mcp/controllers/well_known_controller.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module RailsMcp
+  class WellKnownController < ActionController::API
+    def oauth_metadata
+      issuer = "#{request.scheme}://#{request.host_with_port}"
+      render json: {
+        issuer: issuer,
+        authorization_endpoint: "#{issuer}/oauth/authorize",
+        token_endpoint: "#{issuer}/oauth/token",
+        response_types_supported: ["code"],
+        grant_types_supported: ["authorization_code"],
+        code_challenge_methods_supported: ["S256"],
+        token_endpoint_auth_methods_supported: ["none"]
+      }
+    end
+  end
+end

data/lib/rails_mcp/database/column_policy.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module RailsMcp
+  module Database
+    # Single source of truth for which columns are visible for a given AR class.
+    # Applies schema_file allowlist, default_fields auto-include, and denied_columns
+    # in that order.
+    module ColumnPolicy
+      def self.allowed_for(klass)
+        schema = RailsMcp.schema_config
+        cols = if schema
+                 auto = RailsMcp.configuration.default_fields.map(&:to_s) & klass.column_names
+                 (schema.allowed_columns(klass.name) + auto).uniq
+               else
+                 klass.column_names
+               end
+        cols.reject { |col| RailsMcp.configuration.column_denied?(col) }
+      end
+    end
+  end
+end

data/lib/rails_mcp/database/model_resolver.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module RailsMcp
+  module Database
+    module ModelResolver
+      SAFE_CONSTANT_PATTERN = /\A[A-Z][A-Za-z0-9:]*\z/
+
+      class Error < StandardError; end
+      class AccessDenied < Error; end
+      class UnknownModel < Error; end
+
+      def self.resolve(model_name)
+        klass = find_class!(model_name)
+        assert_accessible!(klass)
+        klass
+      end
+
+      def self.all_accessible
+        eager_load_models!
+        ActiveRecord::Base.descendants
+                          .reject(&:abstract_class?)
+                          .select { |k| accessible?(k) }
+      end
+
+      private_class_method def self.find_class!(name)
+        raise UnknownModel, "Invalid model name: #{name.inspect}" unless name.to_s.match?(SAFE_CONSTANT_PATTERN)
+
+        klass = name.to_s.safe_constantize
+        unless klass && klass < ActiveRecord::Base && !klass.abstract_class?
+          raise UnknownModel, "Unknown model: #{name}"
+        end
+
+        klass
+      end
+
+      private_class_method def self.assert_accessible!(klass)
+        raise AccessDenied, "Model #{klass.name} is not accessible" unless accessible?(klass)
+      end
+
+      private_class_method def self.accessible?(klass)
+        # Schema file takes precedence over allowed_models/denied_models
+        schema = RailsMcp.schema_config
+        return schema.accessible?(klass.name) if schema
+
+        config = RailsMcp.configuration
+        name   = klass.name
+
+        return false if config.denied_models.include?(name)
+        return true  if config.allowed_models.empty?
+
+        config.allowed_models.include?(name)
+      end
+
+      private_class_method def self.eager_load_models!
+        return unless defined?(Rails)
+
+        Rails.application.eager_load! unless Rails.application.config.eager_load
+      rescue StandardError
+        # best-effort in environments where eager load is not fully available
+      end
+    end
+  end
+end

data/lib/rails_mcp/database/query_builder.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module RailsMcp
+  module Database
+    class QueryBuilder
+      class Error < StandardError; end
+
+      ALLOWED_ORDER_DIRECTIONS = %w[ASC DESC].freeze
+      SCALAR_TYPES = [String, Integer, Float, TrueClass, FalseClass, NilClass].freeze
+
+      def initialize(klass, conditions: {}, fields: [], limit: nil, offset: 0, order: nil)
+        @klass      = klass
+        @conditions = conditions.transform_keys(&:to_s)
+        @fields     = Array(fields).map(&:to_s)
+        @limit      = clamp_limit(limit)
+        @offset     = [offset.to_i, 0].max
+        @order      = order
+      end
+
+      def execute
+        validate_conditions!
+        validate_fields!
+        validate_order!
+        validate_offset!
+
+        scope = @klass.where(@conditions)
+        scope = scope.select(resolved_fields.map { |f| @klass.arel_table[f] })
+        scope = scope.limit(@limit)
+        scope = scope.offset(@offset) if @offset.positive?
+        scope = scope.order(safe_order_clause) if @order
+
+        scope.map { |record| serialize(record) }
+      end
+
+      private
+
+      def column_names
+        @column_names ||= ColumnPolicy.allowed_for(@klass)
+      end
+
+      def resolved_fields
+        return @fields unless @fields.empty?
+
+        RailsMcp.configuration.default_fields.map(&:to_s) & column_names
+      end
+
+      def clamp_limit(limit)
+        max = RailsMcp.configuration.max_limit
+        return max if limit.nil?
+
+        [limit.to_i, max].min.then { |n| n.positive? ? n : max }
+      end
+
+      def validate_conditions!
+        unknown = @conditions.keys - column_names
+        raise Error, "Unknown column(s) in conditions: #{unknown.join(", ")}" if unknown.any?
+
+        invalid = @conditions.reject { |_, v| valid_condition_value?(v) }
+        return unless invalid.any?
+
+        raise Error,
+              "Invalid condition value(s) for: #{invalid.keys.join(", ")} (scalars and arrays only)"
+      end
+
+      def validate_fields!
+        unknown = @fields - column_names
+        raise Error, "Unknown field(s): #{unknown.join(", ")}" if unknown.any?
+      end
+
+      def validate_offset!
+        max = RailsMcp.configuration.max_offset
+        raise Error, "Offset #{@offset} exceeds maximum allowed offset of #{max}" if @offset > max
+      end
+
+      def validate_order!
+        return unless @order
+
+        col, dir = @order.to_s.strip.split(/\s+/, 2)
+        raise Error, "Unknown order column: #{col}" unless column_names.include?(col)
+
+        return unless dir && !ALLOWED_ORDER_DIRECTIONS.include?(dir.upcase)
+
+        raise Error, "Invalid order direction: #{dir}. Use ASC or DESC"
+      end
+
+      def safe_order_clause
+        col, dir = @order.to_s.strip.split(/\s+/, 2)
+        dir = dir&.upcase == "DESC" ? "DESC" : "ASC"
+        quoted_col = @klass.connection.quote_column_name(col)
+        Arel.sql("#{quoted_col} #{dir}")
+      end
+
+      def serialize(record)
+        resolved_fields
+          .select { |field| column_names.include?(field) }
+          .reject { |field| RailsMcp.configuration.column_denied?(field) }
+          .to_h { |field| [field, record.public_send(field)] }
+      end
+
+      def valid_condition_value?(value)
+        if value.is_a?(Array)
+          value.all? { |v| SCALAR_TYPES.any? { |t| v.is_a?(t) } }
+        else
+          SCALAR_TYPES.any? { |t| value.is_a?(t) }
+        end
+      end
+    end
+  end
+end

data/lib/rails_mcp/database/role_proxy.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RailsMcp
+  module Database
+    module RoleProxy
+      def self.with_role(&)
+        ActiveRecord::Base.connected_to(role: RailsMcp.configuration.database_role, &)
+      end
+    end
+  end
+end

data/lib/rails_mcp/engine.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "rails"
+require "doorkeeper"
+
+module RailsMcp
+  class Engine < ::Rails::Engine
+    isolate_namespace RailsMcp
+
+    generators do
+      require "generators/rails_mcp/install/install_generator"
+    end
+
+    config.middleware.use RailsMcp::Auth::TokenValidator
+
+    initializer "rails_mcp.doorkeeper_pkce_check" do
+      ActiveSupport.on_load(:after_initialize) do
+        next unless defined?(Doorkeeper)
+
+        methods = Doorkeeper.configuration.pkce_code_challenge_methods
+        unless Array(methods).include?("S256")
+          Rails.logger.warn "[activerecord-mcp] Doorkeeper PKCE S256 is not enabled. " \
+                            "Add `pkce_code_challenge_methods %w[S256]` to your Doorkeeper config."
+        end
+      end
+    end
+  end
+end

data/lib/rails_mcp/schema_config.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module RailsMcp
+  class SchemaConfig
+    class Error < StandardError; end
+
+    def initialize(path)
+      @path = path.to_s
+      @data = load_yaml!
+    end
+
+    def accessible?(model_name)
+      @data.key?(model_name.to_s)
+    end
+
+    def model_names
+      @data.keys
+    end
+
+    # Returns the column allowlist for a model, or [] if model is not in schema.
+    def allowed_columns(model_name)
+      Array(@data[model_name.to_s]).map(&:to_s)
+    end
+
+    private
+
+    def load_yaml!
+      raise Error, "Schema file not found: #{@path}" unless File.exist?(@path)
+
+      data = YAML.safe_load_file(@path)
+      raise Error, "Schema file must contain a YAML mapping" unless data.is_a?(Hash)
+
+      validate!(data)
+      data
+    end
+
+    def validate!(data)
+      data.each do |model_name, columns|
+        unless model_name.is_a?(String) && model_name.match?(/\A[A-Z][A-Za-z0-9:]*\z/)
+          raise Error, "Invalid model name in schema: #{model_name.inspect}"
+        end
+
+        unless columns.is_a?(Array) && columns.all?(String)
+          raise Error, "Columns for #{model_name} must be an array of strings"
+        end
+      end
+    end
+  end
+end