rails-ai-bridge

Turn any Rails app into an AI-ready system — with real context, not guesswork.

One command. Zero config. Structured context + live introspection for AI assistants via compact project files and an MCP server.

AI coding tools are much better when they know your Rails app before they start editing. Without that context, they guess table names, miss routes, ignore conventions, and spend tokens rediscovering structure your app already has.

rails-ai-bridge turns a Rails app into an AI-readable project map:

• Static context files give assistants an immediate overview of your app, conventions, schema shape, routes, and important models.
• A read-only MCP server lets assistants ask for exact details only when needed, such as one model, one table, one controller, or one route group.
• Assistant-specific output keeps Claude Code, Cursor, Codex, Copilot, Windsurf, Gemini, and JSON consumers aligned without making you hand-write context files.

The goal is simple: help AI assistants produce code that fits your Rails app instead of generic Rails code.

Use the README as the shortest path to understanding and setup. Jump to deeper docs only when you need details.

This is useful when you want an AI assistant to work inside a real Rails codebase, especially if the app has:

• More than a few models or routes
• Existing conventions that new code should follow
• Auth, background jobs, API endpoints, Hotwire, engines, or service objects
• A team that wants shared AI guidance committed to the repo
• Large schemas where dumping everything into context would be noisy

For tiny apps or one-off scripts, manual context may be enough. For team Rails apps, generated context plus MCP gives the assistant a much better starting point.

flowchart LR
  app[Rails_app]
  intro[Introspectors]
  files[Static_context_files]
  mcp[MCP_server]
  clients[AI_clients]
  app --> intro
  intro --> files
  intro --> mcp
  files --> clients
  mcp --> clients

1. Introspect: built-in scanners read your Rails app structure: schema, models, routes, controllers, gems, tests, conventions, and optional full-stack details.
2. Generate: rails ai:bridge writes compact, assistant-specific files such as AGENTS.md, CLAUDE.md, .cursor/rules/, and Copilot instructions.
3. Serve: rails ai:serve exposes read-only rails_* MCP tools so an assistant can drill into exact details on demand.

This creates two complementary layers:

Compact files are ordered for usefulness: primary domain models, busy endpoints, recently migrated tables, and optional hot-table signals appear before lower-signal supporting details.

• MCP tools are read-only. They inspect Rails structure; they do not write files or mutate the database.
• database_stats is opt-in because it queries PostgreSQL table statistics.
• Generated assistant context avoids credential values and suppresses secret-bearing config paths such as .env*, Rails credentials, master.key, private key material, and custom config/secrets or config/private files.
• HTTP MCP should stay bound to 127.0.0.1 unless you add authentication and network controls. See docs/mcp-security.md.

From RubyGems (once published):

bundle add rails-ai-bridge
rails generate rails_ai_bridge:install

From GitHub (before or alongside RubyGems):

bundle add rails-ai-bridge --github=igmarin/rails-ai-bridge
rails generate rails_ai_bridge:install

Or add to your Gemfile:

gem "rails-ai-bridge", github: "igmarin/rails-ai-bridge"

Then bundle install and run the generator as above.

The install generator creates .mcp.json (MCP auto-discovery), sets up config/initializers/rails_ai_bridge.rb, and interactively guides you through generating your first bridge files.

The generator prompts you to pick a profile (or pass --profile to skip the prompt):

# Non-interactive — select profile upfront
rails generate rails_ai_bridge:install --profile=minimal

# CI/CD — skip file generation entirely
rails generate rails_ai_bridge:install --skip-context
rails ai:bridge   # generate later

Optional: gem install rails-ai-bridge installs the gem into your Ruby environment; you still add it to the app’s Gemfile for a Rails project.

1. bundle install must finish cleanly — until it does, bundle exec rails -T and rails ai:serve (from .mcp.json) cannot be verified. Merging this gem to main does not fix a broken or incomplete bundle on the host app.
2. Regenerate in one shot — run rails ai:bridge (not only a single format) so route/controller summaries and relevance ordering stay consistent across CLAUDE.md, .cursor/rules/, and .github/instructions/.
3. Keep team-specific rules — generated files are snapshots. Use config/rails_ai_bridge/overrides.md for org-specific constraints (merged only after you delete the first-line <!-- rails-ai-bridge:omit-merge --> stub). Until then, the gem does not inject placeholder text into Copilot/Codex. See overrides.md.example for an outline. Alternatively re-merge into generated files after each rails ai:bridge (see .codex/README.md).
4. Tune list sizes — RailsAiBridge.configure { |c| c.copilot_compact_model_list_limit = 5 } (and codex_compact_model_list_limit); set 0 to list no model names and point only to MCP.
5. Check your readiness — rails ai:doctor prints a 0–100 score and flags anything missing after first install.

Comparison reflects typical documented setups; verify against each project before treating any row as absolute.

rails ai:bridge generates assistant-specific files tailored to each AI workflow:

your-rails-app/
│
├── 🟣 Claude Code
│   ├── CLAUDE.md                                         ≤150 lines (compact)
│   └── .claude/rules/
│       ├── rails-context.md                              semantic layer (compact: capped per tier + MCP hint)
│       ├── rails-schema.md                               table listing
│       ├── rails-models.md                               model listing (includes semantic tier)
│       └── rails-mcp-tools.md                            full tool reference
│
├── 🟡 OpenAI Codex
│   ├── AGENTS.md                                         project instructions for Codex
│   └── .codex/
│       └── README.md                                     local Codex setup notes
│
├── 🟢 Cursor
│   ├── .cursorrules                                      legacy compat
│   └── .cursor/rules/
│       ├── rails-engineering.mdc                         alwaysApply: true (rules first)
│       ├── rails-project.mdc                             alwaysApply: true
│       ├── rails-models.mdc                              globs: app/models/**
│       ├── rails-controllers.mdc                         globs: app/controllers/**
│       └── rails-mcp-tools.mdc                           alwaysApply: true
│
├── 🔵 Windsurf
│   ├── .windsurfrules                                    ≤5,800 chars (6K limit)
│   └── .windsurf/rules/
│       ├── rails-context.md                              project overview
│       └── rails-mcp-tools.md                            tool reference
│
├── 🟠 GitHub Copilot
│   ├── .github/copilot-instructions.md                   ≤500 lines (compact)
│   └── .github/instructions/
│       ├── rails-models.instructions.md                  applyTo: app/models/**
│       ├── rails-controllers.instructions.md             applyTo: app/controllers/**
│       └── rails-mcp-tools.instructions.md               applyTo: **/*
│
├── 🔴 Gemini
│   └── GEMINI.md                                         directive briefing + MCP guide
│
├── 📋 .ai-context.json                                   full JSON (programmatic)
└── .mcp.json                                             MCP auto-discovery

Each file respects the AI tool's format and size limits. Commit these files so the same project guidance is available to your whole team.

Use rails ai:bridge:full to dump everything into the files (good for small apps <30 models).

The :full preset runs 27 introspectors. The :standard preset runs 9 core ones by default.

Start with :standard for most apps, then selectively enable additional introspectors (like :database_stats) as your use case requires. Use config.core_models to tell the generator which models are primary domain entities.

This keeps context focused and avoids unnecessary token usage while still allowing deep introspection when needed.

The gem exposes 12 built-in tools via MCP that AI clients call on-demand (hosts can append more via config.additional_tools):

All tools are read-only — they never modify your application or database.

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

# Start broad
rails_get_schema(detail: "summary")           # → all tables with column counts

# Drill into specifics
rails_get_schema(table: "users")              # → full detail for one table

# Paginate large schemas
rails_get_schema(detail: "summary", limit: 20, offset: 40)

# Filter routes by controller
rails_get_routes(controller: "users")

# Get one model's full details
rails_get_model_details(model: "User")

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

Early project-level trials suggest the biggest improvement is not always dramatic token reduction by itself. In several runs, rails-ai-bridge led to faster, more focused responses even when total token usage only dropped modestly.

This is expected: compact assistant-specific files and the summary-first MCP workflow reduce orientation overhead, help the model navigate the codebase earlier, and improve the quality of the initial context.

Observed benefits so far:

• Less exploratory reading before the assistant reaches the relevant files
• Faster first useful response in Cursor and Windsurf trials
• Similar or slightly better answer quality with clearer project grounding
• More predictable drill-down via detail:"summary" first, then focused lookups

Results will vary by client, model, project size, and task type. More formal benchmarks are still in progress.

The install generator creates .mcp.json for MCP-capable clients. Claude Code and Cursor can auto-detect it, while Codex can use the generated AGENTS.md plus your local Codex configuration.

This project keeps server.json aligned with GitHub metadata for MCP registry packaging when you choose to publish a release artifact.

To start manually: rails ai:serve

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "rails-ai-bridge": {
      "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

Or auto-mount inside your Rails app:

RailsAiBridge.configure do |config|
  config.auto_mount = true
  config.http_mcp_token = "generate-a-long-random-secret" # or ENV["RAILS_AI_BRIDGE_MCP_TOKEN"]
  # Production only: explicit opt-in + token required (see SECURITY.md)
  # config.allow_auto_mount_in_production = true
  config.http_path  = "/mcp"
  # Optional: reject HTTP requests when no Bearer/JWT/static auth is configured (safer beyond localhost)
  # config.mcp.require_http_auth = true
end

Clients must send Authorization: Bearer <token> when a token is configured.

Security note: keep the HTTP transport bound to 127.0.0.1 unless you add your own network and authentication controls. The tools are read-only, but they can still expose sensitive application structure. Generated context and the built-in conventions resource filter secret-bearing config paths, but MCP access should still be treated as internal. In production, rails ai:serve_http and auto_mount require a configured MCP token; auto_mount also requires allow_auto_mount_in_production = true. For operational hardening (tokens, proxies, require_http_auth, stdio threat model), see docs/mcp-security.md and SECURITY.md.

Codex support is centered on AGENTS.md at the repository root.

• Run rails ai:bridge:codex to regenerate AGENTS.md and .codex/README.md.
• Keep AGENTS.md committed so Codex sees project-specific instructions.
• Keep personal preferences in ~/.codex/AGENTS.md; use the repository AGENTS.md for shared guidance.
• When Codex is connected to the generated MCP server, prefer the rails_* tools and start with detail:"summary".

The shortest path to good results:

1. Commit generated static files so every teammate gets the same passive AI context.
2. Run MCP when doing real implementation work so assistants can drill into current schema, routes, models, controllers, and views.
3. Regenerate after meaningful app changes so static files do not drift from the code.
4. Start MCP calls with detail: "summary" and drill into one table, model, route group, or controller only when needed.
5. Put team-specific rules in config/rails_ai_bridge/overrides.md instead of hand-editing generated files.

Static files are snapshots. After a new model, migration, route change, significant refactor, or feature merge, run:

rails ai:bridge

For the full guide to client compatibility, token usage, overrides, staleness, and per-assistant workflow tips, read docs/BEST_PRACTICES.md.

Add individual introspectors on top of a preset for targeted additions:

config.preset = :standard
config.introspectors += %i[non_ar_models views auth api]

For PostgreSQL apps where row-volume context matters, opt into safe approximate table-size hints:

config.introspectors += %i[database_stats]

This adds small, medium, large, or hot hints to generated context without exposing row data.

rails ai:doctor

Prints a 0–100 AI readiness score and flags anything missing: .mcp.json, generated context files, MCP token in production, and more. Run it after initial setup and after major configuration changes.

# config/initializers/rails_ai_bridge.rb
RailsAiBridge.configure do |config|
  # Presets: :standard (9 introspectors, default) or :full (27). Add opt-in extras as needed.
  config.preset = :standard

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

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

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

  # Tag primary domain models as core_entity (semantic context for AI + Claude rules)
  # config.core_models += %w[User Order Project]

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

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

Other HTTP MCP knobs live only on the nested object, for example RailsAiBridge.configuration.mcp.authorize, mcp.mode, mcp.security_profile, and mcp.require_auth_in_production — see docs/GUIDE.md and docs/mcp-security.md.

If you need host-app or companion-gem extensions, register them explicitly in the initializer:

RailsAiBridge.configure do |config|
  config.additional_introspectors[:billing] = MyCompany::BillingIntrospector
  config.introspectors << :billing

  config.additional_tools << MyCompany::Tools::GetBillingContext

  config.additional_resources["rails://billing"] = {
    name: "Billing",
    description: "Billing-specific AI context",
    mime_type: "application/json",
    key: :billing
  }
end

Built-in MCP tools and resources now read through a shared runtime context provider, so tool calls and rails://... resource reads stay aligned to the same cached snapshot.

Rubydex is Shopify's high-performance Ruby static analysis toolkit. When installed, rails-ai-bridge can leverage rubydex for semantic code understanding:

Setup:

1. Add rubydex to your Gemfile:

   gem 'rubydex', '>= 0.1.0.beta9'

2. Enable in your initializer:

   RailsAiBridge.configure do |config|
     config.rubydex_enabled = true
   
     # Optional: enable the semantic introspector (adds :semantic to introspectors)
     config.semantic_introspector_enabled = true
     config.introspectors += %i[semantic]
   
     # Optional: control semantic context depth in generated files
     # config.semantic_context_depth = :standard  # :summary, :standard, or :full
   end

What you get:

Internal architecture: The RubydexAdapter wraps the rubydex API as a thin coordinator delegating to three single-responsibility collaborators: Serializer (hash conversion), Indexer (graph construction + source file scanning), and MethodCounter (flat method-counting pipeline). See CONTRIBUTING.md for the full project layout.

Configuration options:

Performance considerations: Rubydex indexes your Ruby source files at startup. For large codebases, the initial indexing may take a few seconds. The index is cached in memory and shared across MCP tool calls.

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.

Bridge modes:

rails ai:bridge                               # compact (default) — all formats
rails ai:bridge:full                          # full dump — all formats
CONTEXT_MODE=full rails ai:bridge:claude      # full dump — Claude only
CONTEXT_MODE=full rails ai:bridge:cursor      # full dump — Cursor only

Overwrite confirmation:

CONFIRM=1 rails ai:bridge      # prompt before overwriting any changed file
rails ai:bridge                # silent overwrite (default)

You can also control this programmatically via RailsAiBridge.generate_context(on_conflict: :skip) — accepts :overwrite (default), :skip, :prompt, or a Proc (filepath) -> bool.

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.

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

The docs are layered so new users do not need to read everything at once.

git clone https://github.com/igmarin/rails-ai-bridge.git
cd rails-ai-bridge && bundle install
bundle exec rspec       # runs the full suite
bundle exec rubocop     # lint

See CONTRIBUTING.md for the full guide: adding introspectors, adding MCP tools, code style rules, PR process, and the maintainer release checklist.

For contributors, key folders include local guides:

• lib/rails_ai_bridge/README.md
• lib/rails_ai_bridge/introspectors/README.md
• lib/rails_ai_bridge/tools/README.md
• lib/rails_ai_bridge/serializers/README.md
• lib/generators/rails_ai_bridge/README.md
• spec/lib/rails_ai_bridge/README.md

Bug reports and pull requests: github.com/igmarin/rails-ai-bridge/issues

This gem ships as rails-ai-bridge (Ruby RailsAiBridge, version 3.1.0). Earlier iterations of the same codebase were distributed as rails-ai-context.

RailsMCP evolved from crisnahine/rails-ai-context, an excellent foundation for Rails MCP integration. This project extends that work with Codex support, smart token optimization, and a different long-term direction. All original commits and contributors are preserved in the git history.

MIT