crisnahine/rails-ai-context

rails-ai-context makes your Rails app the source of truth for your AI coding assistant. The assistant stops guessing your schema, associations, routes and conventions from training data and asks your app instead: 35 read-only tools over MCP or the command line, plus context files written for Claude Code, Cursor, GitHub Copilot, OpenCode and Codex CLI.

Install in one paste

Open your AI tool at the root of your Rails app and paste this. It installs the gem, sets up the AI tool you’re in, checks the result and tells you the one step left.

Install the rails-ai-context gem in this Rails app so you can read its schema, models, routes and code through its tools instead of guessing.

1. Run `ruby -v` and `bundle exec rails -v`. rails-ai-context needs Ruby 3.1+ and Rails 7.0+. If either is older, stop and tell me.
2. Pick TOOL, the key for the AI tool you are: claude (Claude Code), cursor (Cursor), copilot (GitHub Copilot in VS Code), opencode (OpenCode), codex (Codex CLI). If you are another AI tool, stop and tell me to use the "Another MCP client" prompt instead.
3. Run `bundle add rails-ai-context --group development --version '>= 5.35.0'`. If the Gemfile already lists it, run `bundle update rails-ai-context --conservative` instead. Then run `bundle exec rails-ai-context version`: it must print 5.35.0 or newer, the first version with the flags used below. If it is older, the Gemfile pins it: change its rails-ai-context line to `gem "rails-ai-context", ">= 5.35.0", group: :development` and run `bundle update rails-ai-context --conservative`. If Bundler refuses (a frozen or deployment bundle), run `gem install rails-ai-context -v '>= 5.35.0'` instead and use `rails-ai-context init --tools TOOL --defaults` in step 4.
4. Run `bundle exec rails generate rails_ai_context:install --tools TOOL --defaults`. If it fails because the app can't boot, run `bundle exec rails-ai-context init --tools TOOL --defaults` instead; that one reads the source files when the app won't start.
5. Run `bundle exec rails-ai-context tool onboard` (or `rails-ai-context tool onboard` if you used gem install) and check it describes this app.
6. Tell me which files changed, then the "Next step" lines the install printed for TOOL, word for word. I have to do that step before your rails-ai-context MCP tools appear.

Something else in mind? There’s a prompt for it

Already installed? Prompts to change the setup, switch install type, upgrade, fix it, uninstall, and put it to work. Every one gives each install answer as a flag, so it never stalls on a question in the AI tool’s terminal.

Then one step in your AI tool

Every AI tool holds a new project MCP server back until you say yes. The install prints the step for each tool you picked:

Then ask something only your app knows, such as “what columns does the users table have?”, and watch it call rails_get_schema instead of guessing.

Why

You have seen your assistant do these:

• Write a migration for a column that already exists.
• Call user.posts when the association is user.articles.
• Scaffold tests with FactoryBot in a fixture-based suite.
• Miss a before_action inherited from a parent controller, then wonder why auth fails.
• Add a gem you already have, or call an API from one you don’t.
• Invent a method that isn’t in the codebase.

You catch it, fix it, re-prompt, and something next to it breaks. The tokens are cheap, but the correction loop costs you the afternoon. This gem removes the guess at the source.

What you get

Pick a setup

Switch any time with the change the setup prompt, or run the install again with the new flag and --prune.

How it works

graph TD
    A["Your Rails app\nmodels + schema + routes + controllers + views + jobs"] -->|"40 introspectors"| B
    B["rails-ai-context\nPrism AST · cached · confidence-tagged\nstatic tier when the app can't boot"]
    B --> C["MCP server\nstdio / HTTP\n35 tools · 5 templates · 9 resources"]
    B --> D["CLI\nrake / Thor\nsame 35 tools"]
    B --> E["Context files\nCLAUDE.md · .cursor/rules/ · .github/instructions/ · AGENTS.md"]

    style A fill:#4a9eff,stroke:#2d7ad4,color:#fff
    style B fill:#2d2d2d,stroke:#555,color:#fff
    style C fill:#0984e3,stroke:#0770c2,color:#fff
    style D fill:#00cec9,stroke:#00b5b0,color:#fff
    style E fill:#a29bfe,stroke:#8c83f0,color:#fff

Internals are in Architecture and Introspectors.

Tools

Every tool is read-only and answers from your app.

Four worth knowing on day one:

• search_code with match_type=trace returns the definition, the source, every caller grouped by file and labelled by type, and the tests, in one call. That replaces 4 to 5 file reads.
• get_controllers returns the action source with inherited filters, strong params and the render map.
• get_model_details returns associations, validations, scopes, enums and macros from the AST, tagged [VERIFIED] or [INFERRED].
• query runs read-only SQL with a timeout, a row limit and column redaction.

Over MCP each name gets a rails_ prefix (rails_get_schema). From the CLI the short name works: schema, get_schema and rails_get_schema all resolve. Parameters for all 35 are in the tools reference; worked examples in recipes.

Three ways to connect

MCP over stdio is the default. Each AI tool gets its own config file (.mcp.json, .cursor/mcp.json, .vscode/mcp.json, opencode.json, .codex/config.toml) that starts bundle exec rails-ai-context serve, or rails-ai-context serve standalone. On Windows each starts it through cmd /c, since a gem’s executables there are batch files.

MCP over HTTP mounts the server inside your app, where it inherits your routing, auth and middleware:

# config/routes.rb
mount RailsAiContext::Engine, at: "/mcp" if defined?(RailsAiContext::Engine)

The if keeps the routes file loading where the gem is not installed, as in production, where Bundler skips the development group. Outside development and test the endpoint refuses every request with a 403 unless you set config.allow_http_in_production = true, since it has no authentication of its own (Security). There is also a standalone HTTP process: rails-ai-context serve --transport http --port 6029.

CLI runs the same 35 tools with no server, in any terminal:

bin/rails 'ai:tool[search_code]' pattern="publishable?" match_type=trace
rails-ai-context tool schema --table users --detail full

About half the tools take detail=summary|standard|full.

When the app can’t boot

The app-reading commands try a full boot for live reflection. When boot fails (missing ENV vars, an unreachable service, a broken initializer) they fall back to the static tier instead of dying: routes from config/routes.rb, schema from db/schema.rb, db/structure.sql or migrations, models and controllers from their source. Every response carries a banner naming the degradation, static data is tagged [STATIC], and a section that needs a booted app says [UNAVAILABLE] with the reason. --no-boot skips the attempt outright. doctor still needs a bootable app, since diagnosing the boot is its job.

Code is found in the conventional layout, in packwerk packs (packs/*/app/*), in in-repo engines (engines/*/app/*), and in any extra_app_paths from .rails-ai-context.yml. Details in Compatibility.

Commands

The binary finds the app the way bin/rails does, so it runs from any subdirectory. Flags shared by the app-reading commands: --app-path PATH to target another directory, --environment ENV to set RAILS_ENV, and --no-boot to answer from source. Full list in the CLI reference.

[!NOTE] These commands are for you. With MCP connected the assistant calls the same tools itself.

Configuration

# config/initializers/rails_ai_context.rb
if defined?(RailsAiContext) && RailsAiContext.respond_to?(:configure)
  RailsAiContext.configure do |config|
    config.ai_tools  = %i[claude cursor]   # which AI tools to generate for
    config.tool_mode = :mcp                # :mcp (default) or :cli
    config.preset    = :full               # :full (40 introspectors) or :standard (17)
  end
end

Standalone installs use the same keys in .rails-ai-context.yml. All options with defaults are in Configuration.

Uninstall

bundle exec rails-ai-context uninstall && bundle remove rails-ai-context   # in the Gemfile
rails-ai-context uninstall                                                 # standalone

It removes the context files, the MCP entries, its config, its .gitignore lines and its pre-commit hook, and keeps what you wrote: your lines in CLAUDE.md, other servers in an MCP config, a hook you edited. Or paste the uninstall prompt.

Documentation