activerecord-mcp 0.1.0

data/lib/rails_mcp/server.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module RailsMcp
+  module Server
+    class << self
+      def transport
+        @transport ||= build_transport
+      end
+
+      def tool(name, &)
+        dsl = ToolDSL.new(name)
+        dsl.instance_eval(&)
+        @custom_tools ||= []
+        @custom_tools << dsl.to_mcp_tool
+      end
+
+      def all_tools
+        built_in_tools + (@custom_tools || [])
+      end
+
+      # Allows tests and reloads to reset state
+      def reset!
+        @transport    = nil
+        @custom_tools = nil
+      end
+
+      private
+
+      def built_in_tools
+        [
+          Tools::ListModels,
+          Tools::DescribeModel,
+          Tools::QueryRecords,
+          Tools::FindRecord,
+          Tools::CountRecords
+        ]
+      end
+
+      def build_transport
+        mcp_server = MCP::Server.new(
+          name: "activerecord-mcp",
+          version: RailsMcp::VERSION,
+          tools: all_tools
+        )
+        MCP::Server::Transports::StreamableHTTPTransport.new(mcp_server, stateless: true)
+      end
+    end
+  end
+end

data/lib/rails_mcp/tool_dsl.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module RailsMcp
+  class ToolDSL
+    def initialize(name)
+      @name             = name.to_s
+      @description_text = nil
+      @parameters       = []
+      @call_block       = nil
+    end
+
+    def description(text)
+      @description_text = text
+    end
+
+    def parameter(name, type:, description: nil, required: false)
+      @parameters << { name: name.to_s, type: type.to_s, description: description, required: required }
+    end
+
+    def call(&block)
+      @call_block = block
+    end
+
+    def to_mcp_tool
+      name        = @name
+      description = @description_text
+      parameters  = @parameters
+      call_block  = @call_block
+
+      properties = parameters.to_h do |p|
+        schema = { type: p[:type] }
+        schema[:description] = p[:description] if p[:description]
+        [p[:name].to_sym, schema]
+      end
+      required = parameters.select { |p| p[:required] }.map { |p| p[:name] }
+      schema = { properties: properties }
+      schema[:required] = required if required.any?
+
+      Class.new(MCP::Tool) do
+        tool_name name
+        description description
+        input_schema(**schema)
+
+        define_singleton_method(:call) do |server_context:, **args|
+          call_block.call(args, server_context)
+        end
+      end
+    end
+  end
+end

data/lib/rails_mcp/tools/count_records.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module RailsMcp
+  module Tools
+    class CountRecords < MCP::Tool
+      tool_name "count_records"
+      description "Count records matching hash conditions"
+      input_schema(
+        properties: {
+          model: { type: "string", description: "Model class name, e.g. \"User\"" },
+          conditions: { type: "object", description: "Hash of column => value pairs" }
+        },
+        required: ["model"]
+      )
+
+      SCALAR_TYPES = [String, Integer, Float, TrueClass, FalseClass, NilClass].freeze
+
+      def self.call(model:, server_context:, conditions: {})
+        count = Database::RoleProxy.with_role do
+          klass      = Database::ModelResolver.resolve(model)
+          conditions = (conditions || {}).transform_keys(&:to_s)
+          allowed    = Database::ColumnPolicy.allowed_for(klass)
+
+          unknown = conditions.keys - allowed
+          raise Database::QueryBuilder::Error, "Unknown column(s): #{unknown.join(", ")}" if unknown.any?
+
+          invalid = conditions.reject { |_, v| valid_condition_value?(v) }
+          if invalid.any?
+            raise Database::QueryBuilder::Error,
+                  "Invalid condition value(s) for: #{invalid.keys.join(", ")} (scalars and arrays only)"
+          end
+
+          klass.where(conditions).count
+        end
+        MCP::Tool::Response.new([{ type: "text", text: { count: count }.to_json }])
+      end
+
+      def self.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
+
+      private_class_method :valid_condition_value?
+    end
+  end
+end

data/lib/rails_mcp/tools/describe_model.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module RailsMcp
+  module Tools
+    class DescribeModel < MCP::Tool
+      tool_name "describe_model"
+      description "Return schema, columns, and associations for a model"
+      input_schema(
+        properties: {
+          model: { type: "string", description: "Model class name, e.g. \"User\"" }
+        },
+        required: ["model"]
+      )
+
+      def self.call(model:, server_context:)
+        result = Database::RoleProxy.with_role do
+          klass = Database::ModelResolver.resolve(model)
+          {
+            model: klass.name,
+            table: klass.table_name,
+            primary_key: klass.primary_key,
+            columns: column_info(klass),
+            associations: association_info(klass)
+          }
+        end
+        MCP::Tool::Response.new([{ type: "text", text: result.to_json }])
+      end
+
+      def self.column_info(klass)
+        klass.columns
+             .reject { |col| RailsMcp.configuration.column_denied?(col.name) }
+             .map { |col| { name: col.name, type: col.type.to_s, null: col.null, default: col.default } }
+      end
+
+      def self.association_info(klass)
+        klass.reflect_on_all_associations.map do |assoc|
+          { name: assoc.name.to_s, macro: assoc.macro.to_s, class_name: assoc.class_name }
+        end
+      end
+
+      private_class_method :column_info, :association_info
+    end
+  end
+end

data/lib/rails_mcp/tools/find_record.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module RailsMcp
+  module Tools
+    class FindRecord < MCP::Tool
+      tool_name "find_record"
+      description "Find a single record by primary key"
+      input_schema(
+        properties: {
+          model: { type: "string", description: "Model class name, e.g. \"User\"" },
+          id: { type: "integer", description: "Primary key value" },
+          fields: { type: "array", description: "Columns to return. Defaults to [id, created_at, updated_at]",
+                    items: { type: "string" } }
+        },
+        required: %w[model id]
+      )
+
+      def self.call(model:, id:, server_context:, fields: [])
+        result = Database::RoleProxy.with_role do
+          klass  = Database::ModelResolver.resolve(model)
+          record = klass.find_by(klass.primary_key => id)
+
+          raise Database::ModelResolver::UnknownModel, "#{model} with id=#{id} not found" unless record
+
+          # Pre-query: resolve and validate fields against the same allowed set QueryBuilder uses
+          allowed  = allowed_columns(klass)
+          resolved = Array(fields).map(&:to_s)
+          resolved = RailsMcp.configuration.default_fields.map(&:to_s) & allowed if resolved.empty?
+
+          unknown = resolved - allowed
+          raise Database::QueryBuilder::Error, "Unknown field(s): #{unknown.join(", ")}" if unknown.any?
+
+          # Post-query: strip denied columns from output regardless of how resolved was built
+          resolved
+            .reject { |f| RailsMcp.configuration.column_denied?(f) }
+            .to_h { |f| [f, record.public_send(f)] }
+        end
+        MCP::Tool::Response.new([{ type: "text", text: result.to_json }])
+      end
+
+      def self.allowed_columns(klass)
+        Database::ColumnPolicy.allowed_for(klass)
+      end
+
+      private_class_method :allowed_columns
+    end
+  end
+end

data/lib/rails_mcp/tools/list_models.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module RailsMcp
+  module Tools
+    class ListModels < MCP::Tool
+      tool_name "list_models"
+      description "List all accessible ActiveRecord model classes"
+      input_schema(properties: {})
+
+      def self.call(server_context:)
+        models = Database::RoleProxy.with_role do
+          Database::ModelResolver.all_accessible.map(&:name).sort
+        end
+        MCP::Tool::Response.new([{ type: "text", text: models.to_json }])
+      end
+    end
+  end
+end

data/lib/rails_mcp/tools/query_records.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module RailsMcp
+  module Tools
+    class QueryRecords < MCP::Tool
+      tool_name "query_records"
+      description "Query records using hash conditions. Returns only id, created_at, and updated_at " \
+                  "by default — specify fields to retrieve other columns."
+      input_schema(
+        properties: {
+          model: { type: "string", description: "Model class name, e.g. \"User\"" },
+          conditions: { type: "object", description: "Hash of column => value pairs, e.g. {\"active\": true}" },
+          fields: { type: "array", description: "Columns to return. Defaults to [id, created_at, updated_at]",
+                    items: { type: "string" } },
+          limit: { type: "integer", description: "Max records to return (capped at max_limit, default 100)" },
+          offset: { type: "integer",
+                    description: "Number of records to skip (must not exceed max_offset, default 10000)" },
+          order: { type: "string", description: "Order clause, e.g. \"created_at DESC\"" }
+        },
+        required: ["model"]
+      )
+
+      def self.call(model:, server_context:, conditions: {}, fields: [], limit: nil, offset: 0, order: nil)
+        records = Database::RoleProxy.with_role do
+          klass = Database::ModelResolver.resolve(model)
+          Database::QueryBuilder.new(
+            klass,
+            conditions: conditions || {},
+            fields: Array(fields),
+            limit: limit,
+            offset: offset || 0,
+            order: order
+          ).execute
+        end
+        MCP::Tool::Response.new([{ type: "text", text: records.to_json }])
+      end
+    end
+  end
+end

data/lib/rails_mcp/version.rb

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

data/lib/rails_mcp.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "rails_mcp/version"
+require "rails_mcp/configuration"
+require "rails_mcp/schema_config"
+require "rails_mcp/database/role_proxy"
+require "rails_mcp/database/model_resolver"
+require "rails_mcp/database/column_policy"
+require "rails_mcp/database/query_builder"
+require "rails_mcp/tools/list_models"
+require "rails_mcp/tools/describe_model"
+require "rails_mcp/tools/query_records"
+require "rails_mcp/tools/find_record"
+require "rails_mcp/tools/count_records"
+require "rails_mcp/tool_dsl"
+require "rails_mcp/server"
+require "rails_mcp/auth/token_validator"
+require "rails_mcp/engine"
+
+module RailsMcp
+  class << self
+    def configure
+      yield configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def schema_config
+      return nil unless configuration.schema_file
+
+      @schema_config ||= SchemaConfig.new(configuration.schema_file)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+      @schema_config = nil
+    end
+  end
+end

data/rails-mcp.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "lib/rails_mcp/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "activerecord-mcp"
+  spec.version = RailsMcp::VERSION
+  spec.authors = ["Paulo Ancheta"]
+  spec.email = ["paulo.ancheta@gmail.com"]
+
+  spec.summary = "MCP server for Rails apps — safe, role-aware database query tools over Streamable HTTP"
+  spec.description = "A Rails Engine that implements a Model Context Protocol (MCP) server using " \
+                     "HTTP-only Streamable HTTP transport. Provides built-in ActiveRecord query tools " \
+                     "with configurable database roles, field filtering, and OAuth 2.1 + PKCE auth via Doorkeeper."
+  spec.homepage = "https://github.com/pauloancheta/rails-mcp"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.1.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ spec/ .git .github appveyor Gemfile])
+    end
+  end
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "doorkeeper", "~> 5.6"
+  spec.add_dependency "mcp", "~> 0.17"
+  spec.add_dependency "rails", ">= 7.0"
+end

data/test/dummy/app/models/post.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class Post < ActiveRecord::Base
+  belongs_to :user
+  validates :title, presence: true
+end

data/test/dummy/app/models/user.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class User < ActiveRecord::Base
+  has_many :posts
+  validates :name, :email, presence: true
+end

data/test/dummy/config/application.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "rails"
+require "active_record/railtie"
+require "action_controller/railtie"
+require "action_dispatch/railtie"
+require "doorkeeper"
+require "rails_mcp"
+
+module Dummy
+  class Application < Rails::Application
+    config.root = File.expand_path("..", __dir__)
+    config.load_defaults 7.0
+    config.eager_load = false
+    config.logger = Logger.new(nil)
+    config.active_record.sqlite3_adapter_strict_strings_by_default = false
+  end
+end

data/test/dummy/config/database.yml

@@ -0,0 +1,13 @@
+default: &default
+  adapter: sqlite3
+  pool: 5
+  timeout: 5000
+
+test:
+  <<: *default
+  database: ":memory:"
+
+# Alias reading role to the same connection so connected_to(:reading) works in tests
+test_reading:
+  <<: *default
+  database: ":memory:"

data/test/dummy/config/environment.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "application"
+
+Rails.application.initialize!

data/test/dummy/config/initializers/doorkeeper.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+Doorkeeper.configure do
+  orm :active_record
+  resource_owner_authenticator { nil }
+  default_scopes
+  optional_scopes :mcp
+  pkce_code_challenge_methods %w[S256]
+  access_token_expires_in 2.hours
+  skip_authorization { true }
+end

data/test/dummy/config/routes.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+Rails.application.routes.draw do
+  use_doorkeeper
+  mount RailsMcp::Engine, at: "/mcp"
+end

data/test/dummy/db/schema.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+ActiveRecord::Schema.define(version: 1) do
+  create_table :users, force: true do |t|
+    t.string  :name,   null: false
+    t.string  :email,  null: false
+    t.integer :age
+    t.boolean :active, default: true
+    t.timestamps
+  end
+
+  create_table :posts, force: true do |t|
+    t.string     :title,   null: false
+    t.text       :body
+    t.references :user,    null: false, foreign_key: true
+    t.timestamps
+  end
+
+  # Doorkeeper tables
+  create_table :oauth_applications, force: true do |t|
+    t.string  :name,          null: false
+    t.string  :uid,           null: false
+    t.string  :secret,        null: false, default: ""
+    t.text    :redirect_uri,  null: false
+    t.text    :scopes,        null: false, default: ""
+    t.boolean :confidential,  null: false, default: true
+    t.timestamps null: false
+  end
+  add_index :oauth_applications, :uid, unique: true
+
+  create_table :oauth_access_grants, force: true do |t|
+    t.references :resource_owner, null: false, index: true
+    t.references :application,    null: false
+    t.string     :token,          null: false
+    t.integer    :expires_in,     null: false
+    t.text       :redirect_uri,   null: false
+    t.text       :scopes,         null: false, default: ""
+    t.string     :code_challenge
+    t.string     :code_challenge_method
+    t.datetime   :revoked_at
+    t.timestamps null: false
+  end
+  add_index :oauth_access_grants, :token, unique: true
+
+  create_table :oauth_access_tokens, force: true do |t|
+    t.references :resource_owner, index: true
+    t.references :application
+    t.text       :token,              null: false
+    t.text       :refresh_token
+    t.integer    :expires_in
+    t.text       :scopes
+    t.datetime   :revoked_at
+    t.string     :previous_refresh_token, null: false, default: ""
+    t.timestamps null: false
+  end
+  add_index :oauth_access_tokens, :token,         unique: true
+  add_index :oauth_access_tokens, :refresh_token, unique: true, where: "(refresh_token IS NOT NULL)"
+end

data/test/fixtures/rails_mcp.yml

@@ -0,0 +1,5 @@
+User:
+  - name
+  - email
+Post:
+  - title

data/test/test_helper.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+ENV["RAILS_ENV"] = "test"
+
+require_relative "dummy/config/environment"
+require "minitest/autorun"
+require "active_support/test_case"
+require "action_dispatch/testing/integration"
+
+# Load schema into the in-memory DB
+ActiveRecord::Schema.verbose = false
+load File.expand_path("dummy/db/schema.rb", __dir__)
+
+# Stub connected_to so SQLite :reading role works in tests
+module ActiveRecord
+  class Base
+    class << self
+      alias _original_connected_to connected_to
+
+      def connected_to(**_kwargs)
+        yield
+      end
+    end
+  end
+end
+
+class ActiveSupport::TestCase
+  setup do
+    RailsMcp.reset_configuration!
+    RailsMcp::Server.reset!
+  end
+
+  teardown do
+    User.delete_all
+    Post.delete_all
+  end
+
+  # Build a valid Doorkeeper access token for request tests
+  def create_access_token
+    app = Doorkeeper::Application.create!(
+      name: "test",
+      redirect_uri: "urn:ietf:wg:oauth:2.0:oob",
+      confidential: false
+    )
+    Doorkeeper::AccessToken.create!(application: app, expires_in: 3600)
+  end
+end

data/test/tmp/generator_output/config/initializers/rails_mcp.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