activerecord-mcp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c9497890ce1878eb9de6a624e8db95ecaa6e5b8e6d011e1392757cd62630d31f
+  data.tar.gz: a6910fcd4b686d11a5eb5e99dd57cea4b9fbb5fde7120d26d387a16f7ccada13
+SHA512:
+  metadata.gz: e3f176ad0d260adecf0ebd94229ad1bd81a8ca37613efc96883c32f1bcfe057c9ad5888bce9b5ed45a25b3062842e3e037ace65a95d665d7dcc10717abfc74b1
+  data.tar.gz: 1608b80a2888a30830ca9d2b96c3b305b32e5880702bc456b990f032d83a4b74a3594f90bcef36193b9c0885aa4fabe1d295ef9ffaf91b6ff402bc180ec009b5

data/.rubocop.yml

@@ -0,0 +1,51 @@
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - "bin/**/*"
+    - "vendor/**/*"
+    - "test/dummy/**/*"
+    - "test/tmp/**/*"
+
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120
+
+# Class/module docs are not required
+Style/Documentation:
+  Enabled: false
+
+# server_context: is required by the MCP SDK interface even when unused in a tool
+Lint/UnusedMethodArgument:
+  AllowUnusedKeywordArguments: true
+
+# Error subclasses nested in the same file is intentional
+Style/OneClassPerFile:
+  Enabled: false
+
+# We use compact nested module style throughout
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+# Tool and builder classes are data-heavy by design
+Metrics/MethodLength:
+  Max: 20
+Metrics/AbcSize:
+  Max: 30
+Metrics/CyclomaticComplexity:
+  Max: 10
+Metrics/PerceivedComplexity:
+  Max: 10
+Metrics/ClassLength:
+  Max: 150
+Metrics/ParameterLists:
+  Max: 8

data/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-23
+
+### Added
+
+- Five built-in ActiveRecord query tools: `list_models`, `describe_model`, `query_records`, `find_record`, `count_records`
+- Read-only by default via `database_role` config (uses Rails' `connected_to`)
+- `schema_file` option — YAML file defining per-model column allowlists; `id`, `created_at`, `updated_at` auto-included
+- `denied_columns` config accepting exact strings and regexes; applied as a final layer over all other config
+- Two-pass security model: denied columns blocked before query (validation) and stripped after (output sanitisation)
+- `ColumnPolicy` as the single source of truth for allowed columns across all query paths
+- Hash condition value validation — rejects Hash values to block Rails 7.1+ predicate operators
+- Quoted SELECT via Arel — column identifiers are always fully qualified and DB-quoted
+- `max_limit` config (default 100) — silently caps `query_records` limit
+- `max_offset` config (default 10,000) — raises an error on deep pagination attempts
+- OAuth 2.1 + PKCE authentication via Doorkeeper; `TokenValidator` Rack middleware
+- `scope` config (default `"mcp"`) — tokens without the required scope are rejected with `403 insufficient_scope`
+- `GET /.well-known/oauth-authorization-server` — public OAuth discovery endpoint
+- Custom tool DSL — `RailsMcp::Server.tool("name") { ... }` registers tools before first request
+- `bin/rails generate rails_mcp:install` — scaffolds a documented initializer with all options commented out
+- Streamable HTTP transport via the official MCP Ruby SDK (`mcp` gem); no SSE, no standalone process
+- Mounts as a Rails Engine — shares Puma thread pool and ActiveRecord connection pool
+- Full documentation in `docs/`: authentication, querying, configuration, advanced usage

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paulo Ancheta
+
+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,133 @@
+# activerecord-mcp
+
+[![CI](https://github.com/pauloancheta/rails-mcp/actions/workflows/main.yml/badge.svg)](https://github.com/pauloancheta/rails-mcp/actions/workflows/main.yml)
+
+The read-only MCP server Rails developers have been looking for.
+
+Drop it into any Rails app and your AI tools can introspect your ActiveRecord models and query your database instantly — no standalone process, no raw SQL, no credentials handed to a client. By default every query runs against a read-only database role, so production data stays safe. If you need writes, swap in any role your app already has.
+
+Built on the [official MCP Ruby SDK](https://github.com/modelcontextprotocol/ruby-sdk) and mounted as a Rails Engine, it shares Puma's thread pool and your existing connection pool. Nothing extra to run.
+
+## Why activerecord-mcp
+
+- **Read-only by default** — queries run against a named database role (`:reading`); your write replica or primary is never touched unless you configure it
+- **No raw SQL** — all queries go through hash conditions validated against actual column names; no string interpolation reaches the database
+- **Fine-grained access control** — allowlist models, denylist columns by exact name or regex, or define a per-model column allowlist in a YAML file
+- **OAuth 2.1 + PKCE** — every request requires a scoped Bearer token via [Doorkeeper](https://github.com/doorkeeper-gem/doorkeeper); tokens from other clients are rejected at the middleware layer
+- **Zero extra infrastructure** — mounts as a Rails Engine; shares Puma threads and ActiveRecord connections with the rest of your app
+- **Extensible** — register custom tools alongside the built-ins using a simple DSL
+
+## Table of contents
+
+- [Installation](#installation)
+- [Basic setup](#basic-setup)
+- [Quick example](#quick-example)
+- [Documentation](#documentation)
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "activerecord-mcp"
+gem "doorkeeper"
+```
+
+```bash
+bundle install
+bin/rails generate doorkeeper:install
+bin/rails generate doorkeeper:migration
+bin/rails db:migrate
+```
+
+## Basic setup
+
+**1. Configure Doorkeeper** (`config/initializers/doorkeeper.rb`):
+
+```ruby
+Doorkeeper.configure do
+  orm :active_record
+  pkce_code_challenge_methods %w[S256]
+
+  resource_owner_authenticator do
+    current_user || redirect_to(new_user_session_url)
+  end
+end
+```
+
+**2. Mount the engine** (`config/routes.rb`):
+
+```ruby
+Rails.application.routes.draw do
+  use_doorkeeper
+  mount RailsMcp::Engine, at: "/mcp"
+end
+```
+
+**3. Generate the initializer:**
+
+```bash
+bin/rails generate rails_mcp:install
+```
+
+This creates `config/initializers/rails_mcp.rb` with every option documented and commented out. Edit it to restrict access:
+
+
+```ruby
+RailsMcp.configure do |config|
+  config.allowed_models = %w[User Post Order]
+  config.denied_columns = ["password_digest", /token/i, /secret/i]
+end
+```
+
+That's it — the five built-in query tools are live at `/mcp`.
+
+## Quick example
+
+```bash
+# Get a Bearer token (see docs/authentication.md)
+TOKEN="eyJhbGc..."
+
+# List accessible models
+curl -X POST https://your-app.com/mcp \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"list_models","arguments":{}},"id":1}'
+
+# Query records
+curl -X POST https://your-app.com/mcp \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "method": "tools/call",
+    "params": {
+      "name": "query_records",
+      "arguments": {
+        "model": "User",
+        "conditions": { "active": true },
+        "fields": ["id", "name", "email"],
+        "limit": 10
+      }
+    },
+    "id": 2
+  }'
+```
+
+## Documentation
+
+| Topic | Description |
+|-------|-------------|
+| [Authentication](docs/authentication.md) | OAuth 2.1 + PKCE setup, Bearer tokens, discovery endpoint |
+| [Querying](docs/querying.md) | All five built-in tools with full argument reference |
+| [Configuration](docs/configuration.md) | All config options with defaults and explanations |
+| [Advanced usage](docs/advanced.md) | YAML model allowlist, explicit column deny, custom tools DSL |
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+Bug reports and pull requests welcome at https://github.com/pauloancheta/rails-mcp.

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/config/routes.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+RailsMcp::Engine.routes.draw do
+  mount RailsMcp::Server.transport => "/"
+  get "/.well-known/oauth-authorization-server", to: "rails_mcp/well_known#oauth_metadata"
+end

data/docs/advanced.md

@@ -0,0 +1,137 @@
+# Advanced Usage
+
+## YAML model allowlist
+
+For production deployments you typically want an explicit, auditable list of which models and columns the MCP can expose. The `schema_file` option points to a YAML file that defines this.
+
+### Format
+
+```yaml
+# config/rails_mcp.yml
+User:
+  - name
+  - email
+  - active
+  - created_at
+
+Post:
+  - title
+  - body
+  - published_at
+  - created_at
+```
+
+Each key is a model name; each value is the list of columns that can appear in `fields`, `conditions`, and `order`. Model names must match your AR class name exactly (including namespace, e.g. `Admin::User`).
+
+You do **not** need to include `id`, `created_at`, or `updated_at` — they are auto-included from `default_fields` regardless of what the file lists. If you want to exclude them, override `default_fields` in the initializer.
+
+### Behaviour when set
+
+- Only models listed in the file are accessible. Any other model name returns an error.
+- Each model's columns are restricted to the listed set plus `default_fields`.
+- `allowed_models` and `denied_models` config options are ignored — the file is the authoritative list.
+- `denied_columns` still applies on top of the file — a column listed in the YAML but matching a denied pattern is still denied.
+
+### Referencing it in the initializer
+
+```ruby
+# config/initializers/rails_mcp.rb
+RailsMcp.configure do |config|
+  config.schema_file = Rails.root.join("config/rails_mcp.yml")
+end
+```
+
+---
+
+## Explicit column deny
+
+`denied_columns` lets you block specific columns across all models regardless of any other configuration. It is the right tool for sensitive columns that should never be accessible — password hashes, tokens, secrets, PII you want excluded from AI context.
+
+### Strings and regexes
+
+```ruby
+config.denied_columns = [
+  "password_digest",           # exact match
+  "encrypted_password",        # exact match
+  /token/i,                    # case-insensitive regex — matches reset_token, api_token, etc.
+  /secret/i,                   # matches client_secret, secret_key, etc.
+  /api_key/i,
+  /ssn/i,
+  /credit_card/i
+]
+```
+
+### What "denied" means
+
+A denied column is invisible at every layer:
+
+- **`describe_model`** — the column does not appear in the schema output
+- **`query_records` / `find_record`** — requesting the column in `fields` raises an error
+- **`query_records` / `count_records`** — using the column in `conditions` raises an error; this closes the count-oracle attack where an attacker could confirm a hash value by filtering on it and checking the count
+- **`query_records`** — using the column in `order` raises an error
+- **Output strip** — denied columns are removed from serialized results after the query, as a second independent safety net
+
+### Interaction with schema_file
+
+`denied_columns` always wins. If your YAML file lists `email` and you also have `/email/i` in `denied_columns`, the column is denied.
+
+```ruby
+# config/rails_mcp.yml lists email
+# config/initializers/rails_mcp.rb denies it
+config.schema_file    = Rails.root.join("config/rails_mcp.yml")
+config.denied_columns = [/email/i]
+# result: email is inaccessible despite being in the YAML
+```
+
+---
+
+## Custom tools
+
+Register your own MCP tools alongside the built-ins. Tools must be registered **before the first request** because the MCP server is built at boot time. An initializer is the right place.
+
+```ruby
+# config/initializers/rails_mcp.rb
+RailsMcp::Server.tool("business_summary") do
+  description "Return a revenue summary for a given date"
+
+  parameter :date,     type: :string,  description: "ISO 8601 date (e.g. 2024-01-15)", required: true
+  parameter :currency, type: :string,  description: "Currency code, defaults to USD"
+
+  call do |params, _server_context|
+    date   = Date.parse(params[:date])
+    orders = Order.where(created_at: date.all_day)
+    {
+      date:     date.iso8601,
+      count:    orders.count,
+      total:    orders.sum(:amount_cents),
+      currency: params[:currency] || "USD"
+    }
+  end
+end
+```
+
+### DSL reference
+
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `description` | string | Human-readable description shown in `tools/list` |
+| `parameter` | `name, type:, description: nil, required: false` | Declares an input parameter |
+| `call` | block `\|params, server_context\|` | The tool's implementation; return value is JSON-serialized |
+
+Supported `type` values: `:string`, `:integer`, `:number`, `:boolean`, `:array`, `:object`.
+
+### Accessing `server_context`
+
+`server_context` contains request-scoped data set by the middleware layer. The Doorkeeper access token is available as:
+
+```ruby
+call do |params, server_context|
+  token = server_context["rails_mcp.access_token"]
+  user  = token&.resource_owner
+  # ...
+end
+```
+
+### Registration timing
+
+The MCP server is memoized on first use. Registering a tool after the server has been built has no effect. All `RailsMcp::Server.tool` calls must complete before the first request reaches the engine. Rails initializers run before the server is built, so they are the correct place.

data/docs/authentication.md

@@ -0,0 +1,122 @@
+# Authentication
+
+activerecord-mcp uses [Doorkeeper](https://github.com/doorkeeper-gem/doorkeeper) for OAuth 2.1 server-side authentication with PKCE. Every request to the MCP endpoint requires a valid Bearer token.
+
+## How it works
+
+A Rack middleware (`RailsMcp::Auth::TokenValidator`) sits in front of the MCP transport. It validates the Bearer token against Doorkeeper before the request ever reaches the JSON-RPC layer. Invalid, expired, or revoked tokens are rejected with a `401` response — no tool code runs.
+
+Two paths bypass the middleware:
+- `OPTIONS` requests (CORS preflight)
+- `/.well-known/` paths (OAuth discovery — must be public)
+
+## Setup
+
+### 1. Install Doorkeeper
+
+```ruby
+# Gemfile
+gem "doorkeeper"
+gem "activerecord-mcp"
+```
+
+```bash
+bin/rails generate doorkeeper:install
+bin/rails generate doorkeeper:migration
+bin/rails db:migrate
+```
+
+### 2. Configure Doorkeeper with PKCE
+
+```ruby
+# config/initializers/doorkeeper.rb
+Doorkeeper.configure do
+  orm :active_record
+
+  # PKCE S256 is required — activerecord-mcp warns at boot if this is missing
+  pkce_code_challenge_methods %w[S256]
+
+  resource_owner_authenticator do
+    current_user || redirect_to(new_user_session_url)
+  end
+end
+```
+
+activerecord-mcp logs a warning at boot if PKCE S256 is not enabled. It does not raise — Doorkeeper config is owned by the host app.
+
+### 3. Add routes
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  use_doorkeeper
+  mount RailsMcp::Engine, at: "/mcp"
+end
+```
+
+## Required scope
+
+Every token must carry the `mcp` scope (configurable via `config.scope`). A valid, non-expired token that lacks the scope is rejected with `403 insufficient_scope` before any tool code runs. This prevents tokens issued to other parts of your app (e.g. a mobile API client) from being used to access the MCP endpoint.
+
+To issue a token with the right scope, ensure your Doorkeeper config includes it:
+
+```ruby
+# config/initializers/doorkeeper.rb
+Doorkeeper.configure do
+  optional_scopes :mcp
+  # ...
+end
+```
+
+Then request or create tokens that include the `mcp` scope. To use a different scope name, or to disable the check entirely, see [`configuration.scope`](configuration.md#scope).
+
+## Making authenticated requests
+
+Include the token in the `Authorization` header:
+
+```
+Authorization: Bearer <access_token>
+```
+
+Example:
+
+```bash
+curl -X POST https://your-app.com/mcp \
+  -H "Authorization: Bearer eyJhbGc..." \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}'
+```
+
+## OAuth discovery
+
+The endpoint `GET /mcp/.well-known/oauth-authorization-server` is public and returns standard OAuth 2.1 discovery metadata pointing to your Doorkeeper endpoints. MCP clients that support OAuth discovery can use this to auto-configure themselves.
+
+```bash
+curl https://your-app.com/mcp/.well-known/oauth-authorization-server
+```
+
+## Error responses
+
+| Condition | Status | Body |
+|-----------|--------|------|
+| Missing `Authorization` header | `401` | `{"error":"invalid_token"}` |
+| Token not found | `401` | `{"error":"invalid_token"}` |
+| Token revoked | `401` | `{"error":"invalid_token"}` |
+| Token expired | `401` | `{"error":"invalid_token"}` |
+| Token lacks required scope | `403` | `{"error":"insufficient_scope"}` |
+
+All `401` responses include a `WWW-Authenticate: Bearer realm="activerecord-mcp"` header.
+
+## Creating tokens (development)
+
+```ruby
+# bin/rails console
+app   = Doorkeeper::Application.create!(
+  name:          "my-mcp-client",
+  redirect_uri:  "urn:ietf:wg:oauth:2.0:oob",
+  confidential:  false,
+  scopes:        ""
+)
+token = Doorkeeper::AccessToken.create!(application: app, expires_in: 7200)
+puts token.token
+```

data/docs/configuration.md

@@ -0,0 +1,152 @@
+# Configuration
+
+Configure activerecord-mcp in an initializer. All settings have defaults — you only need to set what you want to change.
+
+```ruby
+# config/initializers/rails_mcp.rb
+RailsMcp.configure do |config|
+  config.database_role  = :reading
+  config.default_fields = [:id, :created_at, :updated_at]
+  config.allowed_models = []
+  config.denied_models  = []
+  config.denied_columns = []
+  config.max_limit      = 100
+  config.schema_file    = nil
+end
+```
+
+## Options
+
+### `database_role`
+
+**Default:** `:reading`
+
+The ActiveRecord role passed to `connected_to(role:)` for every query. Use any role defined in your `database.yml`.
+
+```ruby
+config.database_role = :reading
+```
+
+Requires Rails 6.1+. If your app uses a single database without named roles, set this to `:writing` (the default primary role in Rails).
+
+---
+
+### `default_fields`
+
+**Default:** `[:id, :created_at, :updated_at]`
+
+Columns returned when a tool call includes no `fields` argument. Also automatically included when a `schema_file` is configured, even if the file omits them.
+
+```ruby
+config.default_fields = [:id, :name, :created_at, :updated_at]
+```
+
+---
+
+### `allowed_models`
+
+**Default:** `[]` (empty — all models accessible)
+
+When non-empty, only the listed model names are accessible. Any other model name returns an error.
+
+```ruby
+config.allowed_models = %w[User Post Order]
+```
+
+Ignored when `schema_file` is set — the schema file's top-level keys serve as the allowlist.
+
+---
+
+### `denied_models`
+
+**Default:** `[]` (none denied)
+
+Model names that are never accessible, regardless of `allowed_models`.
+
+```ruby
+config.denied_models = %w[AdminUser AuditLog]
+```
+
+Ignored when `schema_file` is set.
+
+---
+
+### `denied_columns`
+
+**Default:** `[]` (none denied)
+
+An array of exact strings and/or regexes. Any matching column is completely invisible across all models and all tools — it cannot appear in query results, conditions, fields, or order clauses.
+
+```ruby
+config.denied_columns = [
+  "password_digest",
+  "encrypted_password",
+  /token/i,
+  /secret/i,
+  /api_key/i
+]
+```
+
+`denied_columns` is applied after all other column resolution (schema file, `default_fields`). It always wins — a column listed in a schema file but matching a denied pattern is still denied.
+
+See [Advanced Usage → Explicit column deny](advanced.md#explicit-column-deny) for details.
+
+---
+
+### `max_limit`
+
+**Default:** `100`
+
+Maximum number of records any `query_records` call can return. Client-supplied `limit` values are silently capped to this. Nil or zero limits also resolve to this value.
+
+```ruby
+config.max_limit = 50
+```
+
+---
+
+### `max_offset`
+
+**Default:** `10_000`
+
+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 telling the caller. Negative offsets are silently treated as `0`.
+
+```ruby
+config.max_offset = 5_000
+```
+
+---
+
+### `scope`
+
+**Default:** `"mcp"`
+
+The OAuth scope that every Bearer token must include. Tokens with a valid signature and expiry but without this scope are rejected with `403 insufficient_scope`. This prevents tokens issued to other clients (mobile apps, webhooks, etc.) from reaching the MCP endpoint.
+
+```ruby
+config.scope = "mcp"          # default
+config.scope = "admin:mcp"    # custom scope name
+config.scope = nil            # disable scope check entirely
+```
+
+Your Doorkeeper config must declare the scope you choose:
+
+```ruby
+Doorkeeper.configure do
+  optional_scopes :mcp
+end
+```
+
+---
+
+### `schema_file`
+
+**Default:** `nil`
+
+Path to a YAML file that defines exactly which models and columns the MCP can access. When set, it replaces `allowed_models` / `denied_models` with the file's model list.
+
+```ruby
+config.schema_file = Rails.root.join("config/rails_mcp.yml")
+```
+
+See [Advanced Usage → YAML model allowlist](advanced.md#yaml-model-allowlist) for the file format.