The problem

You've seen it. Your AI:

• Writes a migration for a column that already exists - didn't check the schema
• Creates a method that duplicates one in a concern - didn't know it was there
• Uses the wrong association name - user.posts when it's user.articles
• Generates tests that don't match your patterns - factories when you use fixtures, or the reverse
• Adds a gem you already have - or calls an API from one you don't
• Misses before_action filters from parent controllers - then wonders why auth fails
• Invents a method that isn't in your codebase - then you spend 10 minutes finding out

You catch it. You fix it. You re-prompt. It breaks something else.

The real cost of AI coding isn't the tokens - it's the correction loop. Every guess is a round-trip: you catch it, you fix it, you re-prompt, and something adjacent breaks. This gem kills the guessing at its source.

Two commands. Problem gone.

gem "rails-ai-context", group: :development
rails generate rails_ai_context:install

Or standalone - no Gemfile needed

gem install rails-ai-context
cd your-rails-app
rails-ai-context init     # interactive setup
rails-ai-context serve    # start MCP server

Now your AI doesn't guess - it asks your app directly. 45 tools and 5 resource templates that query your schema, models, routes, controllers, views, and conventions on demand. Model introspection uses Prism AST parsing - every result carries a [VERIFIED] or [INFERRED] confidence tag so AI knows what's ground truth and what needs runtime checking.

See the difference

One call returns: definition + source code + every caller grouped by type + tests. Replaces 4-5 sequential file reads.

What stops being wrong

Real scenarios where AI goes sideways - and what it does instead with ground truth:

# Schema: does AI know what columns exist?
rails 'ai:tool[schema]' table=users

# Trace: find every caller of a method across the codebase
rails 'ai:tool[search_code]' pattern=your_method match_type=trace

# Model: associations, scopes, callbacks, concerns - all resolved
rails 'ai:tool[model_details]' model=User

# Controllers: action source + inherited filters + strong params in one shot
rails 'ai:tool[controllers]' controller=UsersController action=create

Three ways to use it

rails ai:serve

→ rails_search_code(pattern: "publishable?", match_type: "trace")
→ rails_get_schema(table: "users")
→ rails_analyze_feature(feature: "billing")

# config/routes.rb
mount RailsAiContext::Engine, at: "/mcp"

rails 'ai:tool[search_code]' pattern="publishable?" match_type=trace
rails 'ai:tool[schema]' table=users
rails 'ai:tool[analyze_feature]' feature=billing

Full Guide → - every command, every parameter, every configuration option.

Real-world examples

rails 'ai:tool[schema]' table=users

## Table: users
| Column              | Type    | Null | Default |
|---------------------|---------|------|---------|
| email               | string  | NO   | [unique] |
| subscription_status | string  | yes  | "free"   |
| created_at          | datetime| NO   |          |

rails 'ai:tool[controllers]' controller=PostsController action=create

# PostsController#create

Filters: before_action :authenticate_user!, before_action :set_post (only: show, edit)
Strong params: post_params → title, body, published_at
Renders: redirect_to @post | render :new

# Check existing view patterns
rails 'ai:tool[view]' controller=dashboard
# → templates with ivars, Turbo frames, Stimulus controllers, partial locals

# See existing components + usage examples
rails 'ai:tool[component_catalog]' detail=standard
# → ViewComponent/Phlex props, slots, previews, sidecar assets

# Get Stimulus data-attributes
rails 'ai:tool[stimulus]' controller=chart
# → correct HTML with dashes (not underscores) + reverse view lookup

45 Tools

Every tool is read-only and returns data verified against your actual app - not guesses, not training data.

All 45 tools with parameters →  |  Real-world recipes →

Live Resources (VFS)

AI clients can also read structured data through resource templates - rails-ai-context:// URIs that introspect fresh on every request. Zero stale data.

Plus 9 static resources (schema, routes, conventions, gems, controllers, config, tests, migrations, engines) that AI clients read directly.

Anti-Hallucination Protocol

Every generated context file ships with 6 rules that force AI verification before writing code. The protocol targets the exact cognitive failures that produce confident-wrong code: statistical priors overriding observed facts, pattern completion beating verification, stale context lies.

How it works

graph TD
    A["Your Rails App\nmodels + schema + routes + controllers + views + jobs"] -->|"40 introspectors"| B

    B["rails-ai-context\nPrism AST parsing · Cached · Confidence-tagged\nVFS: rails-ai-context:// URIs introspected fresh"]

    B --> C["MCP Server\nstdio / HTTP\n45 tools · 5 templates"]
    B --> D["CLI Tools\nRake / Thor\nSame 45 tools"]
    B --> E["Static Files\nCLAUDE.md · .cursor/rules/ · .cursorrules\n.github/instructions/"]

    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

Install

Option A - In Gemfile:

gem "rails-ai-context", group: :development
rails generate rails_ai_context:install

Option B - Standalone (no Gemfile entry needed):

gem install rails-ai-context
cd your-rails-app
rails-ai-context init

Both paths ask which AI tools you use (Claude Code, Cursor, GitHub Copilot, OpenCode, Codex CLI) and whether you want MCP or CLI mode. Each tool gets its own MCP config file - auto-detected on project open.

Commands

Static tier: works even when the app can't boot

rails-ai-context attempts a full boot for live reflection. When boot fails (missing ENV vars, unreachable services, a broken initializer) the serve and tool commands fall back to the static tier instead of dying: routes come from parsing config/routes.rb, schema from db/schema.rb / db/structure.sql / migrations, models and controllers from their source files. Every response carries a banner explaining the degradation, static data is tagged [STATIC], and sections that genuinely need a booted app report [UNAVAILABLE] with the reason.

Flags:

• --no-boot (serve, tool) - skip the boot attempt entirely and serve static analysis. Fast, and immune to boot-time side effects.
• --app-path PATH (all app-reading commands) - run against a Rails app in another directory.
• --environment ENV (all commands) - set RAILS_ENV for the boot attempt.

rails-ai-context doctor still requires a bootable app: its job is diagnosing why boot fails.

App shapes

Beyond the conventional layout, code is discovered in packwerk packs (packs/*/app/*), in-repo engines (engines/*/app/*), and any directories listed in extra_app_paths in .rails-ai-context.yml. Rails multi-database schema dumps (db/queue_schema.rb and friends) are reported under a Secondary databases section. Mongoid apps get an honest [UNAVAILABLE] schema signal plus basic static model data (fields, embedded relations) instead of misleading empty output, and API-only apps get "not applicable" answers from view and frontend tools instead of silent empty listings.

Documentation

Build your own tools

Register custom MCP tools alongside the 45 built-in ones:

# app/mcp_tools/rails_get_business_metrics.rb
class RailsGetBusinessMetrics < MCP::Tool
  tool_name "rails_get_business_metrics"
  description "Key business metrics for this app"

  def call(period: "week")
    MCP::Tool::Response.new([{ type: "text", text: "Users this #{period}: #{User.recent.count}" }])
  end
end

# config/initializers/rails_ai_context.rb
config.custom_tools = ["RailsGetBusinessMetrics"]

Test with the built-in TestHelper (works with RSpec and Minitest):

include RailsAiContext::TestHelper

response = execute_tool("business_metrics", period: "month")
assert_tool_response_includes(response, "Users")

Custom Tools Guide →

Configuration

# config/initializers/rails_ai_context.rb
if defined?(RailsAiContext)
  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

All 40+ configuration options →

Observability

Every MCP tool call fires an ActiveSupport::Notifications event:

ActiveSupport::Notifications.subscribe("rails_ai_context.tools.call") do |event|
  ms = (event.payload[:duration].to_f * 1000).round
  Rails.logger.info "[MCP] #{event.payload[:tool_name]} - #{ms}ms"
end

Requirements

• Ruby >= 3.1    Rails >= 7.0
• Optional: brakeman for security scanning, listen for watch mode, ripgrep for fast search