rails-ai-context

Give your AI coding assistant ground truth about your Rails app

:star: If this gem saves you a correction loop, star it on GitHub!

Why • Features • Getting started • Usage • Tools • Configuration • Documentation

rails-ai-context is a Ruby gem that turns your Rails app into the source of truth for AI coding assistants. Instead of guessing your schema, associations, routes and conventions from training data, the assistant asks your app: 45 read-only tools served over MCP or run from the CLI, plus generated context files for Claude Code, Cursor, GitHub Copilot, OpenCode and Codex CLI.

[!TIP] Nothing to add to your Gemfile if you don't want to. gem install rails-ai-context, then rails-ai-context init inside any Rails app. It also works on an app that won't boot: pass --no-boot and every tool answers from the source files.

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; the correction loop is what costs you the afternoon. This gem removes the guess at the source.

Features

• 45 read-only tools for schema, models, controllers, routes, views, Stimulus, Turbo, jobs, services, mailers, i18n, gems, config, tests, security, performance and more. Every answer comes from your app.
• Prism AST parsing for model introspection. Each result carries [VERIFIED] or [INFERRED] so the assistant knows what is ground truth and what needs a runtime check.
• Three ways in: MCP over stdio, MCP mounted inside your Rails app over HTTP, or plain CLI in any terminal.
• Generated context files for Claude Code, Cursor, GitHub Copilot, OpenCode and Codex CLI, with the MCP config each tool auto-detects on project open.
• Live resources: rails:// and rails-ai-context:// URIs that introspect fresh on every read.
• Anti-hallucination rules shipped in every generated context file, on by default.
• Static tier: when the app can't boot, tools answer from config/routes.rb, db/schema.rb, migrations and source files, and say so.
• Works with real app shapes: packwerk packs, in-repo engines, multi-database schema dumps, Mongoid, API-only apps.
• Custom tools: register your own MCP::Tool classes next to the built-in ones and test them with the bundled TestHelper.

Getting started

Requirements

• Ruby 3.1 or newer
• Rails 7.0 or newer
• Optional: brakeman for security_scan, listen for watch, ripgrep for faster search_code

Install in the Gemfile

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

The generator asks which AI tools you use and whether you want MCP or CLI mode, then writes the context files, the MCP config for each tool, and config/initializers/rails_ai_context.rb. Re-running it is safe; it keeps what you have and adds what is missing.

Install standalone

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

No Gemfile change. Config lives in .rails-ai-context.yml. Works with rbenv, rvm, asdf, mise, chruby and system Ruby. See Standalone.

Check it works

rails ai:doctor                                  # in-Gemfile: readiness score + diagnostics
rails-ai-context doctor                          # standalone

rails 'ai:tool[schema]' table=users
rails 'ai:tool[model_details]' model=User
rails 'ai:tool[search_code]' pattern=publishable? match_type=trace

Then open the project in your AI tool. The MCP config it wrote is picked up on open, and the assistant starts calling rails_get_model_details instead of guessing.

[!NOTE] The CLI commands above are for you. When MCP is connected the assistant calls the same tools itself; you never type them.

Usage

MCP over stdio

The default. Each AI tool gets its own config file (.mcp.json, .cursor/mcp.json, .vscode/mcp.json, opencode.json, .codex/config.toml) pointing at:

rails ai:serve             # in-Gemfile
rails-ai-context serve     # standalone

MCP over HTTP

Mount the server inside your app. It inherits your routing, auth and middleware, and needs no second process.

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

Point the client at http://localhost:3000/mcp. There is also a standalone HTTP process: rails-ai-context serve --transport http --port 6029.

[!WARNING] Each connected client that opens the SSE channel holds one server thread for the life of the connection. Fine for development; raise Puma's thread count or use the standalone HTTP process if several clients share the app.

CLI

Same 45 tools, no server, any terminal.

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

Tool names resolve loosely: schema, get_schema and rails_get_schema all work. Most tools take detail=summary|standard|full.

Commands

Flags shared by the app-reading commands: --app-path PATH to target another directory, --environment ENV to set RAILS_ENV, and --no-boot to skip the boot attempt and answer from source. Full list in the CLI reference.

Tools

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