MCP Tools Reference

All 35 read-only tools rails-ai-context gives an AI coding agent, with every parameter.

Quickstart · Recipes · Custom Tools · CLI Reference


Table of Contents


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.

↑ back to top


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

↑ back to top


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 :name is the definition of a method of that name when no def defines 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

↑ back to top


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

↑ back to top


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

↑ back to top


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)

↑ back to top


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)

↑ back to top


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 brakeman gem. 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 own bin/brakeman, run by the app's Ruby, not whatever brakeman is 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

↑ back to top


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

↑ back to top


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:

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 encrypts column also when query_allowed_columns lists it); it serialises a whole row; it carries a column-alias list that renames a wildcard (a VALUES-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, the mysql schema) or a PostgreSQL setting that can hold a password (primary_conninfo); it is a SHOW with a WHERE clause, SHOW ALL on PostgreSQL, or EXPLAIN FOR CONNECTION or a PROCEDURE clause 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 VIEW are allowed and their definition text is secret-redacted; other SHOW CREATE forms 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 as name: value lines); csv returns 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. With csv, a query that returns no rows answers the header row alone.

Cell rendering by format. A markdown table cell shows NULL as _NULL_, escapes a pipe (a\|b) so it cannot end the cell, renders a line break as the two characters \n so it cannot end the row, and shortens a value over 100 characters to … (a SHOW CREATE definition is not a table cell, so it is never shortened). A csv cell is the value itself: NULL is 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.

↑ back to top


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).

↑ back to top


← Quickstart · Recipes →

Back to Home