rails-ai-context

Turn any Rails app into an AI-ready codebase — one gem install.

Built by a Rails dev who got tired of burning tokens explaining his app to AI assistants every single session.

The Problem

You open Claude Code, Cursor, or Copilot and ask: "Add a draft status to posts with a scheduled publish date."

The AI doesn't know your schema, your Devise setup, your Sidekiq jobs, or that Post already has an enum :status. It generates generic code that doesn't match your app.

rails-ai-context fixes this. It auto-introspects your entire Rails app and feeds everything to your AI assistant — schema, models, routes, controllers, jobs, gems, auth, API, tests, config, and conventions — through the Model Context Protocol (MCP).

Proof: 37% Token Savings (Real Benchmark)

Same task — "Add status and date range filters to the Cooks index page" — 4 scenarios in parallel, same Rails app:

No rails-ai-context          45,477 tk  █████████████████████████████████████████████
Normal Claude /init           40,700 tk  █████████████████████████████████████████     -11%
rails-ai-context CLAUDE.md    33,106 tk  █████████████████████████████████             -27%
rails-ai-context (full)       28,834 tk  █████████████████████████████                 -37%

https://github.com/user-attachments/assets/14476243-1210-4e62-9dc5-9d4aa9caef7e

What each layer gives you:

~16,600 fewer tokens per task vs no gem at all.

This was a simple task on a small 5-model app. Real-world tasks are 3-10x more complex. A feature touching auth + payments + mailers + tests on a 50-model app? Without the gem, Claude reads db/schema.rb (2,000+ lines), every model file, every controller, every view — easily 200K+ tokens per session. With rails-ai-context, MCP tools return only what's needed: rails_get_schema(table:"users") returns 25 lines instead of 2,000. The bigger your app and the harder the task, the more you save.

Medium/large estimates based on schema.rb scaling (40 lines/table), model file scaling, and MCP summary-first workflow eliminating full-file reads.

Quick Start

bundle add rails-ai-context
rails generate rails_ai_context:install
rails ai:context

That's it. Three commands. Your AI assistant now understands your entire Rails app.

The install generator creates .mcp.json for auto-discovery — Claude Code and Cursor detect it automatically. No manual MCP config needed.

Full Guide — complete documentation with every command, parameter, and configuration option.

How It Saves Tokens

• /init saves 11% — knows the framework but wastes tokens discovering models and tables
• CLAUDE.md saves 27% — complete Rails-specific map, zero discovery overhead
• Full MCP saves 37% — structured queries replace expensive full-file reads
• MCP tools return detail:"summary" first (~55 tokens), then drill into specifics
• Split rule files only activate in relevant directories

13 Live MCP Tools

The gem exposes 13 read-only tools via MCP that AI clients call on-demand:

Smart Detail Levels

Schema, routes, models, and controllers tools support a detail parameter — critical for large apps:

rails_get_schema(detail: "summary")           # → all tables with column counts
rails_get_schema(table: "users")              # → full detail for one table
rails_get_routes(controller: "users")         # → routes for one controller
rails_get_model_details(model: "User")        # → associations, validations, scopes

A safety net (max_tool_response_chars, default 120K) truncates oversized responses with hints to use filters.

What Gets Generated

rails ai:context generates context files tailored to each AI assistant:

your-rails-app/
│
├── 🟣 Claude Code
│   ├── CLAUDE.md                                         ≤150 lines (compact)
│   └── .claude/rules/
│       ├── rails-context.md                              app overview
│       ├── rails-schema.md                               table listing + column types
│       ├── rails-models.md                               model listing
│       ├── rails-ui-patterns.md                          CSS/Tailwind component patterns
│       └── rails-mcp-tools.md                            full tool reference
│
├── 🟢 Cursor
│   └── .cursor/rules/
│       ├── rails-project.mdc                             alwaysApply: true
│       ├── rails-models.mdc                              globs: app/models/**
│       ├── rails-controllers.mdc                         globs: app/controllers/**
│       ├── rails-ui-patterns.mdc                         globs: app/views/**
│       └── rails-mcp-tools.mdc                           alwaysApply: true
│
├── ⚡ OpenCode
│   ├── AGENTS.md                                        native OpenCode context
│   ├── app/models/AGENTS.md                             auto-loaded when editing models
│   └── app/controllers/AGENTS.md                        auto-loaded when editing controllers
│
├── 🔵 Windsurf
│   ├── .windsurfrules                                    ≤5,800 chars (6K limit)
│   └── .windsurf/rules/
│       ├── rails-context.md                              project overview
│       ├── rails-ui-patterns.md                          CSS component patterns
│       └── rails-mcp-tools.md                            tool reference
│
├── 🟠 GitHub Copilot
│   ├── .github/copilot-instructions.md                   ≤500 lines (compact)
│   └── .github/instructions/
│       ├── rails-context.instructions.md                 applyTo: **/*
│       ├── rails-models.instructions.md                  applyTo: app/models/**
│       ├── rails-controllers.instructions.md             applyTo: app/controllers/**
│       ├── rails-ui-patterns.instructions.md             applyTo: app/views/**
│       └── rails-mcp-tools.instructions.md               applyTo: **/*
│
├── 📋 .ai-context.json                                   full JSON (programmatic)
└── .mcp.json                                             MCP auto-discovery

Root files (CLAUDE.md, AGENTS.md, etc.) use section markers — your custom content outside the markers is preserved on re-generation. Set config.generate_root_files = false to only generate split rules.

What Your AI Learns

29 introspectors total. The :standard preset runs 13 core ones by default; use :full for 28 (database_stats is opt-in, PostgreSQL only).

MCP Server Setup

The install generator creates .mcp.json — Claude Code and Cursor auto-detect it. No manual config needed.

This server is also listed on the official MCP Registry as io.github.crisnahine/rails-ai-context.

To start manually: rails ai:serve

{
  "mcpServers": {
    "rails-ai-context": {
      "command": "bundle",
      "args": ["exec", "rails", "ai:serve"],
      "cwd": "/path/to/your/rails/app"
    }
  }
}

rails ai:serve_http  # Starts at http://127.0.0.1:6029/mcp

RailsAiContext.configure do |config|
  config.auto_mount = true
  config.http_path  = "/mcp"
end

Configuration

# config/initializers/rails_ai_context.rb
RailsAiContext.configure do |config|
  # Presets: :standard (13 introspectors, default) or :full (all 28)
  config.preset = :standard

  # Cherry-pick on top of a preset
  # config.introspectors += %i[views turbo auth api]

  # Context mode: :compact (≤150 lines, default) or :full (dump everything)
  # config.context_mode = :compact

  # Exclude models from introspection
  config.excluded_models += %w[AdminUser InternalAuditLog]

  # Exclude paths from code search
  config.excluded_paths += %w[vendor/bundle]

  # Cache TTL for MCP tool responses (seconds)
  config.cache_ttl = 30

  # Live reload: auto-invalidate MCP caches on file changes
  # :auto (default), true, or false
  # config.live_reload = :auto

  # Skip root files (CLAUDE.md, .windsurfrules, etc.) — only generate split rules
  # Lets you manage root files yourself while still getting .claude/rules/, .cursor/rules/, etc.
  # config.generate_root_files = false
end

Commands

Rake tasks (recommended)

Standalone CLI

The gem also ships a rails-ai-context executable — an alternative to rake tasks.

Run from your Rails app root. Use rails-ai-context help for all options.

Stack Compatibility

Works with every Rails architecture — auto-detects what's relevant:

Frontend introspectors (views, Turbo, Stimulus, assets) degrade gracefully — they report nothing when those features aren't present.

Works Without a Database

The gem parses db/schema.rb as text when no database is connected. Works in CI, Docker build stages, and Claude Code sessions without a running DB.

Requirements

• Ruby >= 3.2, Rails >= 7.1
• mcp gem (installed automatically)
• Optional: listen gem for watch mode, ripgrep for fast code search

vs. Other Ruby MCP Projects

Contributing

git clone https://github.com/crisnahine/rails-ai-context.git
cd rails-ai-context && bundle install
bundle exec rspec       # 491 examples
bundle exec rubocop     # Lint

Bug reports and pull requests welcome at github.com/crisnahine/rails-ai-context.

Sponsorship

If rails-ai-context helps your workflow, consider becoming a sponsor.

License

MIT