MCP Tools Reference
All 35 read-only tools rails-ai-context gives an AI coding agent, with every parameter.
Table of Contents
- Calling tools
- Quick navigation
- Search & Trace
- Understand
- Schema & Models
- Controllers & Routes
- Views & Frontend
- Testing & Quality
- App Config & Services
- Data & Debugging
- Live Resources (VFS)
Calling tools
# MCP - AI calls automatically via protocol
# CLI - you call from terminal:
rails 'ai:tool[schema]' table=users detail=full
rails-ai-context tool schema --table users --detail full
Tool name resolution is flexible - all of these work:
| You type | Resolves to |
|---|---|
schema |
rails_get_schema |
get_schema |
rails_get_schema |
rails_get_schema |
rails_get_schema |
Over MCP the name is exact. A name the server has no tool for fails with a JSON-RPC -32602 error, Tool not found: <name>, that names the nearest tools, or every tool when none is near; data.available lists them all.
Most lookup tools accept a detail parameter: summary (compact), standard (default), or full (everything). Start with summary, drill down as needed. Composite tools (rails_get_context, rails_analyze_feature) do not accept detail.
Quick navigation
| Category | Tools |
|---|---|
| Search & Trace | search_code, get_edit_context |
| Understand | analyze_feature, get_context, onboard |
| Schema & Models | get_schema, get_model_details, get_callbacks, get_concern |
| Controllers & Routes | get_controllers, get_routes |
| Views & Frontend | get_view, get_stimulus, get_partial_interface, get_turbo_map |
| Testing & Quality | get_test_info, generate_test, validate, security_scan, performance_check |
| App Config & Services | get_config, get_helper_methods, get_service_pattern, get_job_pattern, get_component_catalog, get_mailers |
| Data & Debugging | dependency_graph, migration_advisor, search_docs, query, read_logs, diagnose, review_changes, runtime_info, session_context |
Search & Trace
rails_search_code
Search your codebase with regex, ripgrep acceleration, and sensitive file blocking. Every line returned passes through redaction, so in a file no pattern names a string literal under a secret-named key (8+ characters, unless it is clearly not a credential: a message, URL, path, placeholder, version, date, header, env or parameter name, or a translation) or in a known credential format (vendor tokens, JWTs, a PEM or PGP private key) reads as [FILTERED]; code, ENV lookups, ERB and placeholders are never rewritten, so the text stays usable as the text to replace. A match that falls only inside a filtered value is not returned, so a pattern cannot confirm what a secret starts with.
| Parameter | Type | Default | Description |
|---|---|---|---|
pattern |
string | required | Regex pattern to search for. With definition or class, a plain method or constant name matches literally (valid?), anything else as a regex (generate_.*) |
path |
string | - | Subdirectory or file to search (relative to Rails root); a file is searched whatever its type or ignore files say, as ripgrep does, unless it is sensitive or over max_file_size (File too large). A path through a link inside the app is searched as the folder it leads to |
match_type |
enum | any |
any, definition (def lines whose method name contains the pattern), class (class/module lines whose name contains it), call, trace |
file_type |
string | - | Filter by extension (rb, erb, js, etc.) |
exact_match |
boolean | false |
Literal, whole-word match. def reblog? does not match def reblog |
exclude_tests |
boolean | false |
Skip test/spec directories |
group_by_file |
boolean | false |
Group results by file with counts |
context_lines |
integer | 2 |
Lines of context around each match, max 5 |
offset |
integer | 0 |
Skip this many emitted lines |
limit |
integer | auto | Max lines to return; the default is sized in matches, and a limit too small for one match and its context still returns that match |
The header counts matches, not emitted lines, so below the cap it does not move with context_lines. The cap always holds the first match and the context before it, so a max_search_results below context_lines + 1 is raised to that rather than answering "No results found". When the search hits the cap (a cap on emitted lines) the header says first N lines scanned and marks the count N+: it is then the matches among the lines that were scanned, a floor rather than the total, so it falls as context_lines grows. offset and limit count lines, so a search with context returns more lines than matches. A limit smaller than one match's context block would hold only context, so the page starts at the next match instead and says so.
Trace mode returns definition + source code + every caller grouped by file and labelled by type + tests - replaces 4-5 sequential file reads. A model's
scope :nameis the definition of a method of that name when nodefdefines one.
ripgrep follows no symlink while it walks, so a directory linked in from the app's git repository (a monorepo package linked into packs/) is handed to it as a path of its own, and its rows are named the way the app spells them (packs/billing/app/models/invoice.rb). path may name such a directory or a file in it. A link out of the repository, or out of the app when it is in none, is neither searched nor accepted as path.
Without ripgrep on the PATH, the Ruby fallback returns the rows ripgrep would, context lines and the line cap included, from the files ripgrep would search: no hidden files, no other symlinks followed, no binary files (a NUL byte in the first 64 KiB), and ignore files read with ripgrep's precedence, where the file type decides before depth: any .rgignore, then any .ignore, then any .gitignore, then .git/info/exclude, then the global excludes file, the deepest file first within a type. .ignore and .rgignore apply everywhere, including the directories above the app; the git files apply only inside a repository and only as far up as the nearest .git (a file for a worktree or submodule), whose info/exclude is the only one read. Patterns match case-sensitively.
Redaction treats a value under a secret-named key as a secret unless it is clearly something else: shorter than eight characters (four under a password-type key: password, passwd, pass, pin, passphrase, Redis's requirepass and masterauth, the MYSQL_PWD and REDISCLI_AUTH the mysql and redis-cli clients read, and a long password word that ends a name with another joined on before it, as Postgres's PGPASSWORD and a camel-cased userPassword have), containing whitespace (a message; not under passphrase, nor an app password written as four groups of four letters, abcd efgh ijkl mnop), a URL, an email address or a hostname (not under a password-type key), a URL query (?mode=safe) or a path (two slashes, no + or =), a placeholder (<token>, ${VAR}, %{var}, a {name} slot, xxxx, your-..., put-your-key-here), a version (2.4.1, v2) or a date, an HTTP header name (X-Api-Key; not under a password-type key), an env name (capitals joined by _, led by _ or HTTP_ or naming a secret word, like _FORUM_API), a name spelled from a secret word (user_api_key; not under a password-type key, where admin_password is the password), the key's own name in any case (an enum's password: 'password', currentPassword: "current_password"), a switch's value (true, false, null), or not ASCII. Keys ending _url, _error, _use, _file, _dir, _id and the like (in camel case too: tokenType) describe a secret rather than hold one, and so does a Stimulus target, action, controller, outlet or class (password_visibility_target). A quoted name joined by dashes, a header or an attribute, reads with its dashes as underscores, so "X-Api-Key" => "..." and req["x-auth-token"] = "..." hold an API key and a token, while "Content-Type" names no secret. A camel-cased name with Secret or Token among its words (accessToken, clientSecret, jwtSecretKey) is a secret's name, as JSON and JavaScript spell access_token, in source and in a log line. A call or block whose first argument names a secret holds its value too (ENV.fetch("SECRET_KEY_BASE", "..."), let(:api_key) { "..." }, option :client_secret, default: "...", a credentials.fetch default); a ternary's ? "a" : "b" is two values, not a key and its value. Under a name that ends in _KEY, Key or key without a secret word (ALGOLIA_ADMIN_KEY, apiKey), a value is filtered only when it looks like a credential: a run of 16+ characters mixing letters and digits, or a known token format; a cache or i18n key (views/posts/1, users.index.title), a storage key (wp-content/uploads/...), a word, a path or a header name is kept. Log lines use the same rule. An unquoted NAME=value with a secret-named name, in any file (shell, Dockerfile ENV, compose, env, code), a flag (--password=..., --requirepass=...) included, has its value filtered unless it is $VAR, ${...}, #{...} or ERB; the value ends at the first quote, bracket, &, ,, ; or space, so in a URL query (?token=...&page=2) only the value goes. A secret-named flag's value given as the next word (redis-server --requirepass ..., --token ...) is filtered, bare or quoted, when it has a digit and would be filtered under that name, so a word (the --password option), a metavariable (--token TOKEN), a variable, ERB, another flag, a --no-... switch, a path (~/.ssh/id_ed25519, ./keys/deploy.pem, keys/deploy.pem) or a name=value list (BuildKit's --secret id=...,env=...) stays. A :name= setter symbol, a (?<=name= lookbehind and a regex's wildcard (/--password=.+/) are not assignments. The credential after an auth scheme (Bearer, Basic, Token), under an Authorization key, in a curl line or a cassette, is filtered in any file when it is shaped like one: 16 or more letters and digits, both, read past a UUID's dashes and base64's +, / and =; the scheme stays, and Bearer #{token}, Bearer YOUR_TOKEN and Basic realm=... hold no credential. A log line's Authorization header goes whole in every spelling: Authorization: Basic ..., a quoted value, a hash or JSON key, HTTP_AUTHORIZATION, an unquoted name with = or => (HTTP_AUTHORIZATION=Basic ..., Authorization => Bearer ...), and a Token or Digest header with all its parameters; a switch's value (skip_authorization = true) stays. A log file shown as a file (a tracked log in a rails_review_changes diff, rotated or kept ones like .log.1, .log-20261001, .log.old and .log.bak included) gets the same filtering a log line does. In an example file (*.example, *.sample, *.template) a value under a secret-named key is kept only when it is plainly a placeholder: a placeholder shape above, or up to 20 characters of words with no digits (changeme, your_password_here). Locale files are filtered only for credential formats. In a YAML or JSON file read whole, a mapping a secret's name names holds that secret in its value: Heroku's app.json ("STRIPE_SECRET_KEY": { "value": "..." }, on one line or several), a YAML api_token: over value: ..., and a render.yaml or Kubernetes entry named by a sibling (- key: CLIENT_SECRET, - name: API_TOKEN) over its value:; a boolean, and the next entry's value, stay. A YAML key written as a Ruby symbol (:password: in config/sidekiq.yml) reads as its name.
rails_get_edit_context
Method-aware code extraction with surrounding class context. Every line returned passes through redaction, so in a file no pattern names a string literal under a secret-named key (8+ characters, unless it is clearly not a credential: a message, URL, path, placeholder, version, date, header, env or parameter name, or a translation) or in a known credential format (vendor tokens, JWTs, a PEM or PGP private key) reads as [FILTERED]; code, ENV lookups, ERB and placeholders are never rewritten, so the text stays usable as the text to replace. near is looked for in the lines as they are returned, so text only a filtered value holds is not found, and the context line names the enclosing method from those lines too, beside the class or module the match sits in (a class << self body counts as its class's).
| Parameter | Type | Default | Description |
|---|---|---|---|
file |
string | required | File path relative to Rails root |
near |
string | required unless line |
What to find in the file: a method name, keyword or string (e.g. def index, validates, STATUSES) |
context_lines |
integer | 5 |
Lines of context above and below the match |
line |
integer | - | Show context_lines either side of this line instead of searching for near; past the end of the file, near is searched for |
Understand
rails_analyze_feature
Full-stack feature analysis: models + controllers + routes + services (with the files that call them) + admin resources + jobs and Sidekiq workers + views + tests in one call.
| Parameter | Type | Default | Description |
|---|---|---|---|
feature |
string | required | Feature name (e.g., billing, auth, subscription) |
rails_get_context
Composite context: schema + model + controller + routes + views for a resource. Views come from the directory Rails resolves for the controller; a flat-directory fallback is labelled.
| Parameter | Type | Default | Description |
|---|---|---|---|
controller |
string | - | Controller name (e.g., PostsController) |
action |
string | - | Specific controller action; requires controller |
model |
string | - | Model name (e.g., Post) |
feature |
string | - | Feature keyword (e.g., post) |
include |
array | - | Extra context to add: stimulus, turbo, services, jobs, conventions, helpers, env, callbacks, tests, config, gems, security. A key is read in any capitalisation, and a key given twice runs once |
A model, controller or feature keyword the app does not have is answered as not found, with the closest name where there is one. An action the controller does not have is answered "Action 'nope' not found in PostsController. Available: create, destroy, ...", also when skip_tools lists rails_get_controllers. With rails_analyze_feature turned off, a feature keyword that only model names hold is answered with them: "The model names that hold 'comment': Comment." An include whose tool skip_tools turns off is answered by saying so, and that tool does not run.
An unexpected failure is an error response that starts "Tool rails_get_context failed:". A crash inside one section is an error response too: isError over MCP and exit 1 on the CLI. The text keeps every section, and the crashed one reads "Tool <name> failed: <Class>: <message>". A section that answers an error for another reason, such as a refusal or a failed Brakeman run, stays a section of an ordinary answer. rails_diagnose and rails_review_changes answer a crashed section the same way.
rails_onboard
Narrative app walkthrough for getting up to speed. The stack line counts the
tables of every database the app's own schema dumps declare, as
rails_get_schema reads them; the databases Rails 8 gives Solid Queue, Solid
Cache and Solid Cable get one line, without their tables. A database whose
dump was not read, or that has no dump on disk and no migrations of its own,
is named with "(tables not read)" and left out of the table count, and the
summary says so: "5 tables in 2 databases, the warehouse database not read".
It ends with the app's custom rake tasks (Rakefile, lib/tasks, rakelib),
each with its arguments, description and file: the first 15 at standard,
every one at full. Then the app's own generators under lib/generators (the
bin/rails generate command and its USAGE line), the lib/templates files
that replace a built-in generator's template, and the Railties under lib/
with their initializers.
| Parameter | Type | Default | Description |
|---|---|---|---|
detail |
enum | standard |
summary (one-paragraph overview), standard, full |
Schema & Models
rails_get_schema
Database schema with column types, indexes, defaults, encrypted hints. Booted,
a table db/schema.rb declares and the connected database does not have is
named as a migration that has not run, and the listing header says when the
two table counts disagree. Where two databases both dump to db/schema.rb (the
first one and the one named primary), the file may hold the other one's
tables, so such a table is named as not in the connected database, with no
word of a migration.
The other databases are listed after the primary's tables: every database any
environment in config/database.yml configures, so a Rails 8 app's queue,
cache and cable dumps are read even where only production configures them,
then any committed dump no environment names. A dump too large to read, or
holding no tables, is named with the reason, and so is a database with no dump
on disk and no migrations of its own, one with database_tasks: false
included. A replica is not listed. A secondary's dump is read from its own
path, else from the other format's file under its name (db/queue_schema.rb
or db/queue_structure.sql), whatever database_tasks or schema_format
says.
A database only another environment configures carries a mark, as in
cache (production only), and a first database that is not named primary
is listed under its own name where another database is the one named
primary. Both are the same under every preset, and so is each database's
adapter: with the multi_database introspector off, as on preset: standard,
the context still carries the app databases list.
Column hints follow the leftmost-prefix rule: [indexed] means some index leads
with the column, so a lookup on it alone can use one; [unique] means a unique
index covers the column alone; [unique with x] names the partners of a
composite unique index; [in index after x] marks a column that only trails
x in a plain index. An expression key is named as the expression.
| Parameter | Type | Default | Description |
|---|---|---|---|
table |
string | - | Specific table (omit for overview) |
detail |
enum | standard |
summary, standard, full |
limit |
integer | auto | Max tables when listing: 50 for summary, 25 for standard, 10 for full |
offset |
integer | 0 |
Skip this many tables |
format |
enum | markdown |
markdown, json |
rails_get_model_details
AST-parsed model internals. The model heading and each scope carry a confidence tag: [VERIFIED] or [INFERRED] on a booted app, [STATIC] without a boot. The method list says how many of the model's methods it is showing. On the static tier a model of the primary database whose table db/schema.rb does not declare says so: "widgets missing from db/schema.rb".
| Parameter | Type | Default | Description |
|---|---|---|---|
model |
string | - | Model name (e.g., User, Post). Omit to list all models |
detail |
enum | standard |
summary, standard, full |
limit |
integer | 50 |
Max models when listing |
offset |
integer | 0 |
Skip this many models |
Returns: associations, validations, scopes, enums, callbacks, macros, methods, concerns.
What the included concerns declare is merged in, so the answer does not stop
at the model file. A concern whose file could not be read is named under
Concerns as [UNAVAILABLE] rather than dropped.
rails_get_callbacks
Callbacks grouped by type, in Rails event order, with source code at
detail:"full". The list
covers concern-declared callbacks too, with the body read from the concern
file, and the "From Concerns" section says which concern declared each one.
Within one type the order is the order Rails runs them: base classes first, a
concern's callbacks where its include line stands, then the model's own, and
a before_ or around_ callback with prepend: true first. after_commit
and after_rollback are last declared first unless the app turns on
run_after_transaction_callbacks_in_order_defined (load_defaults 7.1). A
method declared again for one type shows once, with the later declaration's
conditions, as Rails keeps it. A block or a lambda is listed as
[inline_block], and detail:"full" prints its declaration. turbo-rails'
broadcasts, broadcasts_to, broadcasts_refreshes and
broadcasts_refreshes_to are listed as the commit callbacks they declare
(broadcasts_refreshes (turbo-rails) under after_create_commit,
after_update_commit and after_destroy_commit), and detail:"full" names
the method each one runs. The order is read from source in both tiers,
and dynamic dispatch is not evaluated: a callback registered through
send(:before_save, ...), through a method called with send or defined with
define_singleton_method, or through a module included in class << self is
not read, so the list can miss it or show the definition it replaces.
| Parameter | Type | Default | Description |
|---|---|---|---|
model |
string | - | Model name. Omit to list every model with its callbacks |
detail |
enum | standard |
summary, standard, full |
rails_get_concern
Concern methods, their source code at detail:"full", and which models include it. A class under
app/models/concerns that subclasses ActiveModel::Validator is listed as a
validator rather than a concern, and its users are the models that name it in
validates_with. The rule reads the class the file is named for, so a concern
that nests its own validator class stays a concern. Every concern is named by
the constant its file declares, so an app inflection (sdg/tag_list.rb
declaring SDG::TagList) is answered under the name the app has.
The private methods are listed under their own heading, since an includer
gets them too, and the listing counts them apart from the public ones. The
macros an included block declares are listed, helper_method among them. An
include under a condition (include Pagy::Backend if defined?(Pagy::Backend))
carries the condition; on a booted app it also says when the module is not
defined, so was never mixed in.
| Parameter | Type | Default | Description |
|---|---|---|---|
name |
string | - | Concern name (e.g., Trackable, Admin::ExportControllerConcern). Omit to list all concerns |
type |
string | all |
A type the listing's headings print: model, controller, mailer and the rest for app/*/concerns; the root a concern outside every concerns directory lives in (service, lib, ...); other for app/concerns or a configured directory. A type the app does not have is answered with the types it has |
detail |
enum | standard |
summary, standard, full |
Controllers & Routes
rails_get_controllers
Controller actions with inherited filters, render map, strong params. Includes schema hints for referenced models.
Strong params are the methods that return permitted params. A method named *_params counts when it calls permit, permit! or expect on params (directly, through a local or an ivar, on each item a block walks, or on ActionController::Parameters.new), or when what it returns comes from super (super.merge(...)), another strong params method (a call runs the nearest class's method of that name, so one the controller or a parent class defines counts whatever its name, such as params_slice(:min_id); any other named *_params or permitted_*, such as a concern's or Pundit's permitted_attributes(@post); and Devise's devise_parameter_sanitizer), or a call given the whole params (Filter.new(params).call), so a before_action that writes into another one's params is not one; a method of another name counts only when it returns the permitted params themselves. A parent controller's strong params are listed with the parent named unless the controller defines an instance method of that name itself, permit! is marked, and an action that permits inline is not one. A file that names another controller (GoogleController = OAuth2Controller) is listed as its alias, with that controller's actions. ADR-0006 records why a call is read as the nearest class's method.
Rails counts every public method that a concern or a parent controller gives among a controller's actions. A page_info in a concern that ApplicationController includes is an action of each controller. An app keeps the helpers its controllers share in such places, so the action lists take one of these methods only where a route names it for that controller, booted or not. An action lookup also finds one that no route names, under the rules the lists apply: no callback, no name that starts with _ or ends in ? or !, and no required argument. The answer reads the method from the file that defines it. It names the parent controller under Inherited when the method comes from one, and says under Not listed why the lists leave the method out. A private def of the same name lower down hides the method, as it does from Rails.
| Parameter | Type | Default | Description |
|---|---|---|---|
controller |
string | - | Controller name (e.g., UsersController) |
action |
string | - | Specific action; requires controller. Also finds one a concern or a parent controller gives that no route names (see above) |
detail |
enum | standard |
summary, standard, full |
limit |
integer | 50 |
Max controllers when listing |
offset |
integer | 0 |
Skip this many controllers |
rails_get_routes
Routes with code-ready helpers (post_path(@record)) and required params. A
fully qualified controller key answers with its own routes only; a short name
reaches the controller whose trailing segments it spells, and not the ones that
merely start with it. Rack apps attached with mount
or match ... to: are named with the path they answer on, when the source
spells one out. A mounted Grape API lists its endpoints under the mount (verb,
full path, declared params), read from its classes in app/api and lib/api;
the summary counts them.
app_only leaves out the routes Rails' engines and gems draw on their own:
Active Storage, Action Mailbox's ingresses and its conductor, Turbo Native's
navigation routes, and Rails' development pages (rails/info, rails/mailers,
rails/welcome), as config.excluded_route_prefixes lists them. A route the
app's own route files declare is an app route, so devise_for :users and the
get "up" => "rails/health#show" health check are listed. A controller filter
searches every route, so controller:"devise/sessions" or
controller:"active_storage/blobs" answers whatever app_only says.
| Parameter | Type | Default | Description |
|---|---|---|---|
controller |
string | - | Filter by controller; searches every route, framework ones included |
detail |
enum | standard |
summary, standard, full |
limit |
integer | auto | Max routes to return; the default depends on detail |
offset |
integer | 0 |
Skip this many routes |
app_only |
boolean | true |
Leave out the routes Rails' engines and gems draw on their own (see above) |
Views & Frontend
rails_get_view
View templates with instance variables, Turbo frames, Stimulus controllers, partial locals. Includes schema hints for detected ivars. At standard detail the listing opens with the form builders the views call, each with its count (form_with (2)), and the ViewComponents they render, from the views introspector of the default full preset. In an ERB or Ruby template (Phlex, jbuilder) only the Ruby it runs counts, so a render or a helper call inside a comment, a string or page text is not listed. A template directly under app/views is grouped as (app/views root), which path: reaches and controller: does not.
| Parameter | Type | Default | Description |
|---|---|---|---|
controller |
string | - | Controller name |
path |
string | - | Specific view path relative to app/views (e.g., posts/index.html.erb); returns its content |
detail |
enum | standard |
summary, standard, full |
rails_get_stimulus
Stimulus controller data-attributes (with dashes, not underscores) + targets +
values + actions + reverse view lookup. Controllers are read from app/javascript,
app/frontend, app/webpacker, frontend, client and app/components
sidecars alike, packs and in-repo engines included, and both file conventions
count (*_controller.js and *.controller.ts). Outside a JS root's own
controllers/ directory the source has to name Stimulus, so a React component
or an AngularJS controller with the same filename is not counted. Outside
app/javascript/controllers the identifier the path gives is a guess, since an
app's own loader can strip a segment the path still carries, so it is checked
against the identifiers the templates and components name (data-controller,
targets, action descriptors, a content_controller helper) and corrected to
the one they use. A guess no template confirms is marked inferred, and takes
the naming rule of its directory when one is known: a loader that imports the
directory by a derived path (import(./dynamic/${path}.controller.ts)), or
two or more confirmed neighbours that all drop the directory's segment.
The change callbacks Stimulus runs itself (countValueChanged,
itemTargetConnected, resultsOutletDisconnected) are listed with the
lifecycle hooks, not as actions. The copy-paste markup at full detail wires
each action to the events the app's own templates use (input->search#queue),
and to no named event, so the element's default, when no template wires it; it
leaves out a method no template names that the controller calls itself, and
carries a data-*-class and data-*-outlet attribute for each class and
outlet the controller reads.
| Parameter | Type | Default | Description |
|---|---|---|---|
controller |
string | - | Stimulus controller name |
detail |
enum | standard |
summary, standard, full |
limit |
integer | 50 |
Max controllers when listing |
offset |
integer | 0 |
Skip this many controllers |
rails_get_partial_interface
What locals to pass to a partial and what methods are called on them. Render sites are render calls, a partial: passed to a Turbo Stream action (turbo_stream.prepend) or a broadcast (broadcast_prepend_to in a model, controller, job or channel), and jbuilder's json.partial! and json.array! ..., partial:. A site counts only where Rails would render this file: _post.html.erb gets the html, Turbo Stream and broadcast sites and _post.json.jbuilder the jbuilder ones, and render "comments/form" names comments' form, never the one beside the view. A bare name is looked up in the view's own folder, then in application/, as a controller's prefixes are. A collection: or object: hands the partial its record under the as: name or the partial's own (item), and a collection adds item_counter and item_iteration. A call that names formats: among the options it renders with - beside partial: (render partial: "posts/post", formats: [:json]), or among json.partial!'s keywords - counts for those formats. Rails reads no other key as one: a format: is a local, as is any key inside locals:, and render "shared/date", date: d, format: :short passes every key as a local. In a controller or helper a call inside format.json { } counts for json, and any other renders the request's format, so it counts for both. A jbuilder partial's locals are the bare names it reads; a helper, a route helper or a call with parentheses is not a local.
| Parameter | Type | Default | Description |
|---|---|---|---|
partial |
string | required | Partial path (e.g., users/form); a bare name that matches several partials lists them instead of answering |
detail |
enum | standard |
summary, standard, full |
rails_get_turbo_map
Turbo Stream broadcast-to-subscription wiring with mismatch warnings. Streams are compared the way Turbo names them, part by part: a record by its model, a symbol or string by its text. So broadcast_prepend_to [product, :reviews] (or broadcast_prepend_to product, :reviews) in Review, whose product is a belongs_to, reaches turbo_stream_from @product, :reviews, and broadcasts_refreshes reaches turbo_stream_from @product on update and destroy and the model's plural stream on create. In a view, current_user and Current.user name a User record. A stream or controller filter narrows which streams are shown, each with every broadcaster and subscriber the app has for it, so a stream heard in another controller's views is not called unheard. A part that names nothing the map can resolve (no model by that name, a method rather than an association) is reported as "can't tell", never as a mismatch.
| Parameter | Type | Default | Description |
|---|---|---|---|
detail |
enum | standard |
summary, standard, full |
stream |
string | - | Filter by stream or channel name (e.g., notifications); a name no broadcast or subscription carries says so and lists the app's streams |
controller |
string | - | Filter by controller name (e.g., messages) |
Testing & Quality
rails_get_test_info
Test fixtures, relationships, and template matching your project's patterns.
| Parameter | Type | Default | Description |
|---|---|---|---|
model |
string | - | Model to find tests for |
controller |
string | - | Controller to find tests for: its controller or request spec, then the system, feature, request and integration tests named for it or reaching its routes, each labelled by type |
detail |
enum | standard |
summary, standard, full |
rails_generate_test
Test scaffolding that matches your project's patterns (fixtures vs factories, RSpec vs Minitest).
| Parameter | Type | Default | Description |
|---|---|---|---|
model |
string | - | Model to generate a model test for (e.g., User) |
controller |
string | - | Controller to generate a request test for (e.g., PostsController) |
file |
string | - | File to generate tests for, relative to Rails root; the type is detected (a job gets a job test under test/jobs or spec/jobs) |
type |
enum | unit |
unit, request, system. With model or controller, system writes a system test that visits the subject's index and show pages |
When the subject's test file exists already, the cases come anyway, addressed to that file, to add the ones it lacks. A controller behind a login filter gets a test that signs in with the app's own sign-in helper and a users fixture or factory where that helper answers the filter: Rails 8's sign_in_as for its require_authentication, or a sign_in for Devise's authenticate_<scope>!. Any other filter (a token check, a hand-written one) and any ActionController::API controller gets a TODO instead, naming the filter and saying the requests are redirected or refused until the test signs in. Devise and Doorkeeper keep their own sign-in lines.
rails_validate
Syntax + semantic + Brakeman security validation in one call.
An ERB template is parsed as the method body Rails compiles it into, with the trim tags <%- and -%> read as tags, as Rails reads them.
JavaScript (.js, .mjs, .cjs) is parsed by node --check as the module system Node would load it with: the extension, else the nearest package.json's type, else a module when CommonJS rejects only its import/export (a Stimulus controller). A failure names the line and column node reports. A file node cannot judge is listed as skipped with the reason, not as passed, so the pre-commit hook never stops a commit for syntax the app's own toolchain compiles: JSX or a decorator (@observable, export @controller class), named by the line node stopped at; a file that declares Flow (// @flow), or one Babel compiles - a babel.config.* or .babelrc* file, or a "babel" key in package.json, in its folder or one above it, up to the top of the app's repository - where node's error is named beside the skip, since it may be the toolchain's syntax or the file's own mistake; or no node on the PATH, where only an unmatched bracket still fails. Type annotations in a .js file nothing compiles still fail, as TypeScript and esbuild refuse them there too.
| Parameter | Type | Default | Description |
|---|---|---|---|
files |
array | required | File paths to validate |
level |
enum | syntax |
syntax, rails (rails includes a Brakeman security pass over the given files only: a view's warning that comes from its controller's params shows when both are passed, and rails_security_scan scans the whole app) |
rails_security_scan
Brakeman static analysis: SQL injection, XSS, mass assignment, command injection. A scan that fails, on an unknown check name for one, answers "Brakeman scan failed: ..." as an error response: isError over MCP and exit 1 on the CLI. A brakeman run from outside the bundle that started and failed is an error response too. One that could not start is an ordinary answer.
| Parameter | Type | Default | Description |
|---|---|---|---|
files |
array | - | File paths to filter results to (omit to scan the whole app) |
confidence |
enum | weak |
Minimum confidence: high, medium, weak (weak shows every warning) |
checks |
array | - | Run only these Brakeman checks, by class name (e.g., CheckSQL) |
detail |
enum | standard |
summary, standard, full |
Requires the
brakemangem. When the app's bundle does not carry it but the machine has it, the scan runs brakeman as its own process from outside the bundle and says so: the installed gem's ownbin/brakeman, run by the app's Ruby, not whateverbrakemanis on PATH. When no scan can run, the answer says which case it is: brakeman is nowhere on the machine, or it is installed and produced no report. For the second it quotes what brakeman said, or says "it wrote no report and printed nothing" or "its report could not be read".
rails_performance_check
N+1 query risks, missing indexes, missing counter_cache, eager load candidates.
An N+1 risk is an association call on a record that a loop hands out. Each
action's body and the before filters that run for it say what its instance
variables hold (@reviews = @product.reviews.latest, @orders =
current_user.orders), and its templates and the partials they render say what
walks them: @reviews.each do |review|, render @reviews, render partial:,
collection:, json.array!, a loop record passed to a partial as a local, or a
loop in a partial rendered with no locals (render "dashboard/list").
A review.user read there is a risk; the same name anywhere else is not. The
row names the action and the view the call sits in. high means the query
preloads nothing, medium that it preloads other associations, and low that
it preloads this one; a named scope in the query counts with its body, so
Post.with_author preloads what scope :with_author, -> { includes(:user) }
does. .count on an association runs a query per record even when preloaded,
so it stays high. .size, .any?, .empty? and .none? on a has_many
whose other side keeps a counter_cache read the counter column, so they are
not a risk. The inverse Rails sets on each record of
@product.reviews (review.product) is not a risk, and a branch on a local
the render passes as a literal (show_seller: false) is not read. ERB and
jbuilder are read; Haml and Slim templates are not, and neither are serializers.
Missing indexes and counter caches are checked in every database's dump, and a
finding outside the primary names its database. A dump on disk under a
database's name is read whatever database_tasks or schema_dump says. A
database whose tables could not be read is listed under Not checked with
the reason: its dump is not on disk or is over max_schema_file_size, or its
config/database.yml entry turns database_tasks or schema_dump off and no
dump is on disk, or "schema_dump in its database.yml entry names no file to
read". A database another environment configures carries its mark:
**Not checked:** warehouse (production only, db/warehouse_schema.rb is not on disk).
| Parameter | Type | Default | Description |
|---|---|---|---|
model |
string | - | Filter results to one model |
category |
enum | all |
n_plus_one, counter_cache, indexes, model_all, eager_load, all |
detail |
enum | standard |
summary, standard, full |
App Config & Services
rails_get_config
The app's configuration, one section per call. section picks it; the default, app, is what the tool answered before it took sections. Ten tools that each answered one section were folded in, and their old names still work: the CLI resolves gems, rails_get_gems and the rest to their section, and a call to an old name is answered from its section with a note naming the new call and the arguments the section reads. Under tool_mode: :cli the note is the command. A value goes into the note's call when it is a number, a boolean, or at most 80 characters of letters, digits, _, . and -. Any other value is named after the call: "rails_get_i18n is now rails_get_config(section:"i18n"), with the same locale; call that instead." A parameter the asked section does not read is named in the answer as ignored.
| Parameter | Type | Default | Description |
|---|---|---|---|
section |
enum | app |
app, gems, frontend, api, engines, conventions, autoload, active_support, env, env_config, i18n |
detail |
enum | standard |
summary, standard, full. Read by frontend, api, env |
category |
enum | all |
Read by gems. See below |
environment |
string | - | Read by env_config. One environment, by exact name (e.g. production) |
locale |
string | - | Read by i18n. One locale's files and coverage, by exact name |
offset |
integer | 0 |
Read by gems, env_config, i18n. Skip this many entries |
limit |
integer | 50 |
Read by gems, env_config, i18n. Max entries to return |
skip_tools turns one section off by its old tool's name (rails_get_env turns env off); rails_get_config turns off app alone. The tool leaves tools/list only when every section is off.
With app off, section is required: the published schema marks it required, the description says so, and a call with no section is answered with the sections that are on.
A section the tool does not have, or one skip_tools turned off, is refused with the sections that are on. A call to an old name that sends a parameter no section reads is refused with that section's own parameters, and a refused call to an old name carries no note about the new call.
A custom tool named rails_get_config takes the built-in's place when skip_tools lists that name. The ten sections go with the built-in, so a retired name such as rails_get_gems is then an unknown tool.
app (default)
Database config, auth framework, assets, cache, queue, Action Cable. The use and map calls in config.ru are listed apart from the stack, since they run before Rails.
gems (was rails_get_gems)
Notable gems with versions, categories, and config file locations. A config
location is printed only when the app has that file, and an initializer is
found under a load-order prefix too (config/initializers/3_omniauth.rb).
A notable gem counts when the Gemfile names it, when a gemspec or path gem the
Gemfile pulls in depends on it, when it is a Rails engine or OmniAuth that
another gem brings in, or, for a framework rails pulls in, when
config/application.rb loads it; a gem the lockfile holds only for another
gem's own use is left out.
category takes: auth, jobs, frontend, api, database, files, testing, deploy, monitoring, admin, pagination, search, forms, server, notifications, validation, utilities, services, payments, all.
frontend (was rails_get_frontend_stack)
Auto-detects React/Vue/Svelte/Angular, Hotwire, TypeScript, Vite/Shakapacker, package manager, monorepo layout.
api (was rails_get_api)
API layer: api_only mode, serialization strategy (Jbuilder, serializers), GraphQL, versioning, rate limiting, OpenAPI specs, CORS, pagination.
engines (was rails_get_engines)
What config/routes.rb mounts - engines and plain Rack apps alike, with known-engine descriptions, each with the path it answers on when the source spells one out - the app's own in-repo engines, plugins and modules read from the tree, each with the models the model scan filed under its path, and loaded engine classes with route/model counts.
conventions (was rails_get_conventions)
Auth checks, flash messages, create action template, test patterns, and the admin resources ActiveAdmin, Administrate, Avo, Madmin and Trestle register (with ActiveAdmin's permitted params).
autoload (was rails_get_autoload)
Autoloading setup: Zeitwerk autoloaders with collapsed/ignored dirs, autoload/eager-load paths, custom inflections.
active_support (was rails_get_active_support)
ActiveSupport surface: concerns registry, deprecators, MessageVerifier/MessageEncryptor usage, the ActiveSupport::Notifications events the app subscribes to (subscribe, monotonic_subscribe, and a Subscriber's attach_to) with file and line, read from source in both tiers, tagged logging, subscribed on_load hooks, cache store. Validator classes living among the concerns are counted and listed apart from them, as rails_get_concern does.
env (was rails_get_env)
Environment variables + credentials keys (values are never exposed). Scans .rb, .rake, ERB views and config YAML under app, config and lib, plus config.ru, db/seeds.rb, db/seeds/ and the Ruby scripts in bin/. A tag on a YAML comment line is not read: ERB runs it, but what it writes goes with the comment. Config YAML matching sensitive_patterns (config/database.yml, config/cable.yml, config/storage.yml and the rest) is read only for the ENV names in its ERB tags, so a default there is listed as present and not read; credentials and keys are never read, and the answer says so. A default is read from a second argument or from a block whose one statement is a literal (ENV.fetch("REDIS_URL") { "redis://localhost:6379/1" }). The env Kamal's config/deploy.yml gives the app container is listed too: secret names only, and clear values, except one holding a URL or a key-like token, or under a secret-named variable, which shows as hidden, and one an ERB tag sets, which says so. A Dockerfile ENV or ARG value, an .env.example value and a default in code read [FILTERED] when their shape can carry a secret: a URL whose user part is a key or holds a password, a webhook's address, a token in a query, a key-like run of characters, or a BUNDLE_<HOST> gem server credential (Credential handling). An .env.example value in quotes keeps a #, and an inline comment is hidden when it holds a credential or one of those shapes. So are the setting keys in the config gem's config/settings.yml and config/settings/<env>.yml when the bundle has the config gem, and the attributes of each Anyway::Config class in config/configs or app/configs with the env name it reads (PAYMENT_API_KEY), never their values. A variable whose call sites pass different defaults is labelled as such rather than with one site's default; detail:"full" names each site's. A default is redacted by the rule a source literal gets: a credential format under any name, a URL's password, and under a secret-named variable a value that is not clearly something else, so an address, a hostname or a URL of none of the shapes above prints as written.
env_config (was rails_get_env_config)
Per-environment configuration from config/environments/*.rb: notable toggles (force_ssl, eager_load, caching, log level, queue adapter, mailer delivery) and every config key each environment sets. A key assigned in more than one branch reports every value with its condition; booted, the running environment reports the value the app resolved. An
"Every environment" block above them lists the keys config/application.rb
sets (config.x included) and, for each config_for(:name), the keys
config/name.yml gives the running environment, shared merged in, names
only.
i18n (was rails_get_i18n)
I18n setup: default/available locales, backend, locale files with key counts, per-locale coverage, fallbacks.
rails_get_helper_methods
Application and framework helpers, with view cross-references at detail:"full".
| Parameter | Type | Default | Description |
|---|---|---|---|
helper |
string | - | Helper module name (e.g., ApplicationHelper). Omit to list all helpers |
detail |
enum | standard |
summary, standard, full |
offset |
integer | 0 |
Skip this many helpers |
limit |
integer | 50 |
Max helpers to return |
rails_get_service_pattern
Service object interface, dependencies, side effects, callers, read from
app/services/, app/interactions/ and app/interactors/. An interactor
organizer lists the steps it runs, in order. An
ActiveInteraction's inputs include the ones it inherits, with the filters
nested inside a hash filter shown under it. Callers are read from every
app/ and lib/ tree, and on a booted app from any other directory it
autoloads, and the page says when the twenty-caller display cap or the scan's
own file ceiling left the list partial. A module under
app/services/concerns/ is a concern rather than a service object, so
rails_get_concern lists it and this tool does not. The listing counts
services, and when the service directories hold more Ruby files than that,
one line under the heading says how many it left out and of which kind: base
classes, concerns, modules with no entry point that other code mixes in,
mailers, and files too large to read.
| Parameter | Type | Default | Description |
|---|---|---|---|
service |
string | - | Service class name or filename. Omit to list all services |
detail |
enum | standard |
summary, standard, full |
rails_get_job_pattern
Background job queue, retries, guard clauses, broadcasts, schedules. Jobs are
read from app/jobs, app/workers and app/sidekiq alike, packs and in-repo
engines included: ActiveJob subclasses are listed as jobs and Sidekiq classes
as workers, whichever directory each one lives in. A worker carries its
sidekiq_options, any sidekiq_throttle, and the perform signature, and a
worker that inherits its Sidekiq mixin from a base worker is one of them. A class whose
ancestry reaches neither, but which declares perform - a Resque job, a PORO
enqueued by hand - is listed marked [unknown base]. An abstract base another
job inherits from is not counted as a job; the listing names the ones it left
out, in the sentence the service and mailer listings use, and job: answers
for one of them with what every job below it inherits: its queue, options,
retries, mixins, throttle and callbacks, and which jobs inherit it. job:
answers a worker name as well as a job name. A job's own page shows its
queue_with_priority, enqueue_after_transaction_commit and Solid Queue
limits_concurrency (its own or the nearest base's), every retry_on option,
Sidekiq's sidekiq_retry_in and sidekiq_retries_exhausted blocks, and its
enqueue, perform and discard callbacks as written. A job that includes
ActiveJob::Continuable (itself or through a base) is marked continuable, with
the steps its perform runs in order, each a block or a method. A model method
delayed_job's handle_asynchronously wraps is listed as a background method with
its options, here and on the model's rails_get_model_details page. The listing names the queues
config/sidekiq.yml declares and the queues Solid Queue's workers poll in
config/queue.yml (this environment's section), and names each job queue no
worker polls; that job's page says so beside its queue.
| Parameter | Type | Default | Description |
|---|---|---|---|
job |
string | - | Specific job name |
detail |
enum | standard |
summary, standard, full |
rails_get_component_catalog
ViewComponent/Phlex components: props, slots, previews, sidecar assets, usage examples. Components are read from every app/components, packs and in-repo engines included. The type follows the superclass chain through the app's own base classes; anything the chain cannot place is counted in the header rather than left out of it. A short name several components share is answered with the list of them and a request for the full one. A base-named component other components inherit from is named on a bases line rather than counted, and previews are read from the default directories and the ones the config sets.
| Parameter | Type | Default | Description |
|---|---|---|---|
component |
string | - | Specific component name |
detail |
enum | standard |
summary, standard, full |
offset |
integer | 0 |
Skip this many components |
limit |
integer | 50 |
Max components to return |
rails_get_mailers
ActionMailer mailers: every mailer class with its delivery actions and delivery method. The actions include the public methods a mailer inherits from the app's own mailers below ApplicationMailer, on both tiers. A mailer that declares no action of its own - one taking them from a gem base or a mixin, or one called through class methods - is listed with where its actions come from when that is a gem base it reaches without passing ApplicationMailer, such as Devise::Mailer, and never Rails' own base. A base other mailers inherit from is not one: it leaves the listing, and a line above names the ones left out. Asked for by name, a base answers with what every mailer below it inherits - its layout, helpers, defaults, callbacks and mixins as the app wrote them, the methods it defines - and which mailers inherit it.
Each mailer also shows its own default, layout, helper and action and
deliver callbacks as written, the template formats of each action under
app/views/<mailer>, and its preview class with the emails it previews (read
from test/mailers/previews, spec/mailers/previews and the
action_mailer.preview_paths the config adds). The full listing opens with the
queue deliver_later uses (ActionMailer's setting booted; the config's
statically, ActiveJob's default queue from load_defaults 6.1 on), the
interceptors and observers the config registers, and the preview paths.
The full listing ends with the Action Mailbox mailboxes: the routing rules in
the order Rails tries them, the mailbox each sends to (and whether app/mailboxes
defines it), and each mailbox's processing callbacks.
| Parameter | Type | Default | Description |
|---|---|---|---|
mailer |
string | - | One mailer, by exact name |
offset |
integer | 0 |
Pagination offset |
limit |
integer | 50 |
Max mailers to return |
Data & Debugging
rails_dependency_graph
Model association graph in Mermaid or text format.
| Parameter | Type | Default | Description |
|---|---|---|---|
model |
string | - | Center the graph on this model |
depth |
integer | 2 |
Hops from the centre model (1-3) |
format |
enum | mermaid |
mermaid, text |
show_cycles |
boolean | false |
List circular dependencies: chains of foreign keys that lead back to the model they start from, through another |
show_sti |
boolean | false |
Show Single Table Inheritance hierarchies |
The graph is capped at 50 nodes, with or without model, and says so when it cuts.
A polymorphic belongs_to lists the models that implement it, the ones that declare as: for it. A cycle follows foreign keys, one edge per key from the table that holds it: a belongs_to and the has_many or has_one at its other end are one key, so two models joined both ways are not a cycle, and neither is a key to the model's own table. With show_cycles and no cycle, the answer says none.
rails_migration_advisor
Migration code generation with duplicate/nonexistent column warnings, reversibility flags, table name normalization. The generated class is stamped with the app's own Rails version (from the booted app, or from Gemfile.lock under --no-boot); when neither names one, the output says which version it fell back to.
Before the code it warns about what the app's migrations already hold: a
file already named what the generator would name this one (rails generate
migration refuses that name), and a migration not yet run that already adds
the column or creates the table when it runs (a def down, a dir.down or a
revert block only undoes, so what it adds does not count). It also warns
about a create_table for a table that exists and a null: false column with
no default on a table with rows. The row count is the primary database's
estimate, so a table on another database has no count and the warning says
"if <table> holds any rows". It refuses a column type no adapter knows, and
a column or new_name that is not a plain lowercase identifier (each name in
a create_table list too). add_column with type references or
belongs_to writes add_reference. A create_table definition takes
index or uniq after its type (title:string:index), as Rails' generator
does, and options go on the create_table line. The down of
change_type restores the whole column: its limit, precision, scale, null
and default. For
remove_column, rename_column and change_type it lists the lines in
app/, lib/ and config/ that name the column, the code the change breaks.
Index and lock advice follows the database family of the database that holds
the table.
It refuses a table, type or new_name longer than 256 characters, a
column that long outside create_table, and options longer than 1,024
characters: no migration takes one, and the code it writes would carry it
whole.
| Parameter | Type | Default | Description |
|---|---|---|---|
action |
enum | required | add_column, remove_column, rename_column, add_index, add_association, change_type, create_table |
table |
string | required | Table name |
column |
string | - | Column name; for add_association, the reference (user, parent) |
type |
string | - | Column type (e.g., string, integer, references); for add_association with column, the table the reference points at. A parent reference with no parents table points at its own table |
new_name |
string | - | New column name, for rename_column only |
options |
string | - | Extra options (e.g., null: false, default: 0) |
rails_search_docs
Bundled topic index with weighted keyword search. Optional on-demand GitHub fetch.
| Parameter | Type | Default | Description |
|---|---|---|---|
query |
string | required | Search query |
source |
enum | all |
all, guides, stimulus, turbo, hotwire |
limit |
integer | 5 |
Max results to return (1-20) |
fetch |
boolean | false |
Fetch the full content from GitHub (cached 24h in tmp/) |
rails_query
Safe read-only SQL with layered security: the SQL gate, a PostgreSQL plan check (whole-row leaks, expanded secret columns and VOLATILE admin functions refused before anything runs), SET TRANSACTION READ ONLY, timeout, and column redaction. Learn about the security model →
It runs on PostgreSQL, MySQL (with MariaDB) and SQLite, each with its own read-only transaction and statement timeout. On any other adapter it answers with that adapter's name and runs nothing. A statement that runs past query_timeout is answered as a timeout and any other database error as an SQL error. Both are error responses: isError over MCP and a non-zero exit on the CLI. So is a database no connection reaches, which the answer names with what to do about it. So are a locked SQLite database and the refusal in production.
On PostgreSQL, MySQL and MariaDB every statement a call sends has a time limit, apart from the reads of a setting's own value for the settings note, which wait on no lock. The query has query_timeout to itself and the reads beside it share a second one, so the statements of a call take about twice query_timeout at most. On SQLite the query has query_timeout, and the reads beside it run on the app's own connection with no statement limit. A SQLite statement that names something the app's connection alone holds, such as a temp table or an attached database, runs on that connection, and its answer says it ran without a time limit. The security model says what bounds each statement and lists the stated limits.
On MySQL, MariaDB and SQLite a statement that names a view whose definition names a secret column is refused. So is a * inside a subquery when the statement names a table that holds a secret column, and on SQLite IN before a table's name (x IN t). On PostgreSQL a materialized view whose definition names a secret column is refused. On SQLite a virtual table that holds a secret column, a shadow table and the page modules are refused, and only the pragma functions that describe the schema or the database file run.
The secret column rule reads the columns of every schema and database a statement reaches: the ones its text names, on PostgreSQL the ones its plan names, and the ones the views it names lead to, three reads deep. So a secret column of a table in another one is refused by name too.
On MySQL and MariaDB the text checks read a backslash in a string both ways, and a statement that either reading refuses is refused. There a [ outside a string or a quoted name, a user variable assignment (:=) and LAST_INSERT_ID with an argument are refused too. On every family the text checks give up with a refusal when they have run longer than query_timeout.
| Parameter | Type | Default | Description |
|---|---|---|---|
sql |
string | required | SQL query. Only SELECT, WITH, SHOW, EXPLAIN, DESCRIBE are allowed |
limit |
integer | 100 |
Maximum rows to return (hard cap: 1000) |
format |
enum | table |
table, csv |
explain |
boolean | false |
Show query plan instead of results |
database |
string | the primary | The app database to query, by its config/database.yml name (queue, cache). The secret column rule and the database family are that database's |
database is checked when the tool runs, against the databases the app has then:
- A name the app does not have is answered with the closest one and every name it has.
- A database only another environment configures, a replica and one with
database_tasksoff included, is answered with the environments that do. - A top-level entry of
config/database.ymlthat code connects to by name (establish_connection(:reporting)) is an environment to Rails, sodatabasedoes not take its name: the answer lists every database the app has, as in "No database named reporting. This app has: primary, cache, queue". - One that only a committed dump names is answered as such.
- On the static tier the whole tool is unavailable, with or without
database. - A SQLite database whose file is not there is an error, with or without
database. The message starts "The<name>database does not exist yet" and namesbin/rails db:prepare, and nothing is created. Afile:URI is checked at the path inside it. - A SQLite database other than the primary that lives in memory (
:memory:, or afile:URI withmode=memory) is refused by name. It exists only inside the process that created it, and a new connection would open an empty one. - A database whose columns cannot be read is not queried. The answer is "The columns of the
<name>database could not be read, so its secret columns cannot be told and no query runs on it." - When a statement or an
explain: truefails on a table this database does not have and another database's schema holds it, the answer names that database and thedatabasevalue to use. The pointer is built from the schema dumps, so a table on a database with no dump gets none.
Each database other than the primary is reached through a connection handler of its own for the length of the call, so the app's own connection pools are left as they are and two calls at once never share a connection.
Disabled in production by default.
Name the columns you need. A query is refused, with a message that says why, when it does one of these: it references a secret column (directly, or through an alias or expression; an
encryptscolumn also whenquery_allowed_columnslists it); it serialises a whole row; it carries a column-alias list that renames a wildcard (aVALUES-body list such as(VALUES (1,'a')) AS v(id, name)is allowed, since it renames no table column); it uses UNION; it calls a session-effecting function, a function that returns a whole table as one value (table_to_xml), or any function by a quoted name; it reads a statistics, session or credential relation (pg_stats,pg_stat_activity,pg_settings,performance_schema, themysqlschema) or a PostgreSQL setting that can hold a password (primary_conninfo); it is aSHOWwith aWHEREclause,SHOW ALLon PostgreSQL, orEXPLAIN FOR CONNECTIONor aPROCEDUREclause on MySQL and MariaDB; or it is over 1,000,000 bytes long.SELECT *is allowed and its secret columns come back[FILTERED].SHOW CREATE TABLE/SHOW CREATE VIEWare allowed and their definition text is secret-redacted; otherSHOW CREATEforms are refused. In the default format a definition is shown whole, as the DDL in a fenced code block with its line breaks kept (a view's character set and collation follow asname: valuelines);csvreturns it as one quoted field. When the row limit holds rows back - only when the query really returned more than the cap - the answer says so in every format. Withcsv, a query that returns no rows answers the header row alone.
Cell rendering by format. A
markdowntable cell showsNULLas_NULL_, escapes a pipe (a\|b) so it cannot end the cell, renders a line break as the two characters\nso it cannot end the row, and shortens a value over 100 characters to…(aSHOW CREATEdefinition is not a table cell, so it is never shortened). Acsvcell is the value itself:NULLis an empty field, nothing is escaped beyond RFC 4180 quoting (a field holding a comma, a quote or a line break is wrapped in quotes with its quotes doubled), and nothing is truncated - so a line break stays a real line break inside the quoted field. Binary (non-text) data shows as[BLOB]in both.
rails_read_logs
Reverse file tail with level filtering and sensitive data redaction. A value an SQL statement holds inline is filtered when the column it meets is a secret, and so are the values a database error repeats (Redaction).
| Parameter | Type | Default | Description |
|---|---|---|---|
file |
string | current environment's log | Log file name in log/ (e.g., production, sidekiq); the .log suffix is optional. A log that links out of the app is refused and not listed |
lines |
integer | 50 |
Number of lines, max 500. With search, the number of matching lines to show |
level |
enum | all |
Minimum level: DEBUG, INFO, WARN, ERROR, FATAL, all |
search |
string | - | Keep lines matching this term, searched for in the last 4 MB of the file (about 50,000 lines of a typical Rails log); the answer says how many lines that was, and whether older ones were left unsearched. The match runs on the redacted line, so a redacted value cannot be searched for |
rails_diagnose
One-call error diagnosis with classification, context, recent git changes, and log correlation. It does not call a method undefined when the model's method list could be missing one - a concern's, a parent's, or anything past the payload's own cap.
A NoMethodError is a nil reference only when the receiver is nil; on any other receiver it is an undefined method, and on a booted app the answer names the receiver's closest method (totl → total). An error it has no rule for names the gem or app file that defines the exception class. The error can be pasted as Ruby prints it (NoMethodError: ...) or as a Rails log writes it (NoMethodError (...)).
Log correlation reads the last megabyte of the current environment's log, the window rails_read_logs reads, and shows the latest entry for the error: the request that raised it (path, controller action, parameters, status, request id when the log is tagged), the error line and the first backtrace frames, redacted. It says so when the log holds no entry for the error.
| Parameter | Type | Default | Description |
|---|---|---|---|
error |
string | required | Error message or class |
file |
string | - | File where error occurred. A path refused on policy is named in the answer, which still diagnoses the error and comes back as an error result (how a refusal is reported) |
line |
integer | - | Line number |
action |
string | - | controller#action (e.g., posts#create); adds that action's context |
rails_review_changes
PR/commit review with per-file context and warnings.
A removed validation is a validates line the diff takes out, or moves into a comment, a heredoc or an =begin block, when no line it adds validates the same attribute; an edited validates line is not one.
A changed migration lists the tables it affects: the table each schema method takes first (add_column, remove_columns, rename_index, add_foreign_key, ...), every table drop_table drops, a renamed table's new name, and for create_join_table and drop_join_table the join table, named as Rails names it, and the two tables it joins. The first two are shown with the columns the schema has now.
An app in a subfolder of its repository (a monorepo's backend/) is reviewed on its own: its changed files, named from the app root as rails_validate takes them, and the commits that touched it.
Each diff line is shown as the line of its side, redacted with the whole of that side the way every tool's source is, so a secret a change adds or takes out reads [FILTERED], and so does a key's body in a hunk that opens inside the key, in a hunk header's line too. A changed file on sensitive_patterns (config/database.yml, .env, a key) is listed with its line counts and none of its lines, and so is one whose diff is over max_file_size and a merge conflict's combined diff. The diff is read with the repository's colour, external diff and textconv settings off, and a submodule's change shows as the commits it moves between.
| Parameter | Type | Default | Description |
|---|---|---|---|
ref |
string | HEAD |
Git ref to diff against: a branch, a tag, HEAD~3 or a commit SHA. HEAD reviews uncommitted changes. Any other ref reviews the commits since HEAD left it, as a pull request does: the file list and each file's diff run from the commit the two last shared to HEAD. A ref that names no commit is refused |
files |
array | - | Review only these changed files, or the changed files under these directories (omit for all). A path matches whole, so Gemfile is not Gemfile.lock |
rails_runtime_info
Live database pool stats, table sizes, pending migrations, cache stats, queue depth.
Table sizes come from PostgreSQL, MySQL (base tables only) and SQLite, and index usage from PostgreSQL. On MySQL, MariaDB and SQLite the full detail says "Index usage is not available for the MySQL database family.", or SQLite. On an adapter with no database family the database section says table sizes and index usage are not available for that adapter. A read that failed or took longer than query_timeout is said in one line: "Table sizes were not read: the read failed or took longer than query_timeout.", and at detail: "full" "Index usage was not read: the read failed or took longer than query_timeout."
The pool and the cache are read inside the MCP server process, and the answer says so: the pool's counts are that process's own connections, and a MemoryStore's entries are its own, since each app server process holds its own. A store the processes share (Redis, Memcached, Solid Cache, a file store) is the app's. Another environment that configures a shared store is named, as where the app's cache lives there. Solid Cache's stats are read from its database, so when that is a SQLite file that is not there, the cache section says the database does not exist yet and creates nothing.
The jobs section names the Active Job adapter the running environment uses. Queue counts are read from Sidekiq alone: they are the app's when Sidekiq is that adapter, and under another adapter they are shown under their own heading only when the app has Sidekiq workers of its own, as those workers' counts.
| Parameter | Type | Default | Description |
|---|---|---|---|
detail |
enum | standard |
summary, standard, full |
section |
enum | - | One section only: database, cache, jobs, connections |
database |
string | the primary | The app database whose adapter, table sizes, index usage and pending migrations the database section shows, named and checked as rails_query's database is, whatever the section. A name that cannot be reached is an error for every section, and a section that does not read database says so |
With no database, pending migrations are read for every database the running environment configures and migrates, each from its own schema_migrations. With more than one, the line names the databases that were read (**Migrations:** all up to date in primary, queue). A database that could not be read gets a line of its own with the reason, _Pending migrations could not be read for <name>: <reason>_, and the others are still reported. An in-memory database is left out. Under a named database the section shows that database's own. For a replica, or a database whose config/database.yml entry turns database_tasks off, it says Rails runs no migrations on it. The connections section is always about the app's own pools.
A named database is an error whatever the section when it is not configured here, lives in memory outside the primary, has a SQLite file that is not there, has an adapter whose gem did not load, or has a server that does not answer. The last two answers name the database, say what stopped the connection and say what to do. With no database, a primary whose SQLite file is not there or that cannot be reached is a note in the Database section, and the other sections still answer. Nothing is created either way. On the static tier the whole tool is unavailable, with or without database.
rails_session_context
Session-aware context tracking across tool calls within a conversation. Pass action or mark; a call with neither is an error. A conversation's record keeps its latest 200 queries, and status and summary say how many older ones it dropped; a param longer than 80 characters is kept as its first 80 and its length.
| Parameter | Type | Default | Description |
|---|---|---|---|
action |
enum | - | status (queried tools with timestamps), summary (short recap), reset (clear this conversation's record) |
mark |
string | - | Record a tool and its params as already queried (e.g., get_schema:users). The tool must be one the server has; a short name such as schema is taken, and a tool skip_tools turned off answers that it is turned off. A retired name such as get_gems is recorded as rails_get_config with its section |
Each conversation has its own record: over HTTP, one server process serves every client, and each client's Mcp-Session-Id keeps its calls, and its reset, to itself. A tool that answers by calling others (rails_get_context, rails_diagnose, rails_review_changes) is recorded as the one call the client made.
Live Resources (VFS)
In addition to tools, AI clients can read structured data through resource templates - rails-ai-context:// URIs answered from the context the tools share, which every request checks against the files first, reloading the app's code and introspecting again after any edit.
| URI Pattern | Returns |
|---|---|
rails-ai-context://controllers/{name} |
Actions, inherited filters, strong params |
rails-ai-context://controllers/{name}/{action} |
Action source with applicable filters |
rails-ai-context://views/{path} |
View template content |
rails-ai-context://routes/{controller} |
Live route map for controller |
rails-ai-context://models/{name} |
Model details: associations, validations, schema |
The legacy rails://models/{name} form is still accepted.
In a Claude Code session started in a folder of several apps, the plugin's server names the app in each URI: rails-ai-context://apps/<app>/models/{name}, rails-ai-context://apps/<app>/schema for a static resource, with <app> one of the names its tools' app argument lists. The read goes to that app's own server.
controllers/{name}/{action} also reads an action that a concern or a parent controller gives and no route names, as the rails_get_controllers action lookup does. inherited_from names the parent controller an action comes from. note says why the controller's actions leave out one that no route names. For a controller that cannot load - its file, or one its class body needs, does not compile - both reads give its error and file and nothing read from its source.
A read for a name the app does not have - a model, a controller, an action, a view - fails with a JSON-RPC -32602 error whose message gives the reason and whose data.available lists the names there are: for a view, the ones in its directory, else the app's first twenty. So does a view over the size cap, and a URI the server does not serve, whose data.available lists the resources and templates it does. A path refused on policy fails as Resource not found, without saying why.
Plus 9 static resources (schema, routes, conventions, gems, controllers, config, tests, migrations, engines).