rails-ai-context

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

rails-ai-context automatically introspects your Rails application and exposes your models, routes, schema, controllers, views, jobs, gems, auth, API, tests, config, and conventions to AI assistants through the Model Context Protocol (MCP).

Your AI assistant instantly understands your entire Rails app. No configuration. No manual tool definitions. Just bundle add and go.

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

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

bundle add rails-ai-context

That's it. Now your AI assistant knows:

• Every table, column, index, and foreign key in your database
• Every model with associations, validations, scopes, enums, callbacks, and macros (has_secure_password, encrypts, normalizes, etc.)
• Every controller with actions, filters, strong params, and concerns
• Every view with layouts, templates, partials, helpers, and template engines
• Every route with HTTP verbs, paths, and controller actions
• Every background job, mailer, and Action Cable channel
• Hotwire/Turbo — Turbo Frames, Turbo Streams, model broadcasts
• Every notable gem (70+) and what it means (Devise = auth, Sidekiq = jobs, Turbo = Hotwire)
• Auth & security — Devise modules, Pundit policies, CanCanCan, CORS, CSP
• API layer — serializers, GraphQL, versioning, rate limiting
• Test infrastructure — framework, factories/fixtures, CI config, coverage
• Configuration — cache store, session store, middleware, initializers
• Asset pipeline — Propshaft/Sprockets, importmaps, CSS framework, JS bundler
• DevOps — Puma config, Procfile, Docker, deployment tools
• Your architecture patterns: service objects, STI, polymorphism, state machines, multi-tenancy
• Stimulus controllers with targets, values, actions, outlets, and classes

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

rails ai:context

This creates:

• CLAUDE.md — for Claude Code (with behavioral rules)
• .cursorrules — for Cursor (compact rules format)
• .windsurfrules — for Windsurf (compact rules format)
• .github/copilot-instructions.md — for GitHub Copilot (task-oriented)

Each file is tailored to the AI assistant's preferred format. Commit these files. Your entire team gets smarter AI assistance.

The install generator creates a .mcp.json file that Claude Code and Cursor auto-detect — no manual config needed. Just open your project.

To start manually:

rails ai:serve

Or configure manually in ~/.claude/claude_desktop_config.json:

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

The gem exposes 9 tools via MCP that AI clients can call:

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

In addition to tools, the gem registers MCP resources that AI clients can read directly:

┌─────────────────────────────────────────┐
│            Your Rails App               │
│                                         │
│  models/  routes  schema  jobs  gems    │
│     │        │       │      │     │     │
│     └────────┴───────┴──────┴─────┘     │
│                  │                       │
│         ┌───────┴────────┐              │
│         │  Introspector  │              │
│         └───────┬────────┘              │
│                 │                        │
│    ┌────────────┼────────────┐          │
│    ▼            ▼            ▼          │
│  CLAUDE.md   MCP Server   .cursorrules  │
│  (static)   (live tools)   (static)     │
└─────────────────────────────────────────┘
         │            │
         ▼            ▼
    Claude Code    Cursor / Windsurf /
    (reads file)   any MCP client

Three modes:

1. Static files (rails ai:context) — generates markdown files that AI tools read as project context. Zero runtime cost. Works everywhere.
2. MCP server (rails ai:serve) — live introspection tools that AI clients call on-demand. Richer, always up-to-date.
3. Watch mode (rails ai:watch) — auto-regenerates context files when your code changes.

# config/initializers/rails_ai_context.rb
RailsAiContext.configure do |config|
  # Introspector presets:
  #   :standard — 8 core introspectors (default, fast)
  #   :full     — all 26 introspectors (thorough)
  config.preset = :standard

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

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

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

  # Auto-mount HTTP MCP endpoint (for remote AI clients)
  # config.auto_mount = true
  # config.http_path  = "/mcp"
  # config.http_port  = 6029

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

Check your app's AI readiness:

rails ai:doctor

Reports pass/warn/fail for schema, models, routes, gems, controllers, views, i18n, tests, context files, MCP server, and ripgrep. Includes fix suggestions and an AI readiness score (0-100).

The gem automatically detects Stimulus controllers and extracts:

• Controller names (derived from filenames)
• Static targets, values, outlets, and classes
• Action methods

This gives AI assistants context about your frontend JavaScript alongside your backend Ruby.

zsh users: The bracket syntax rails ai:context_for[claude] requires quoting in zsh (rails 'ai:context_for[claude]'). The named tasks above (rails ai:context:claude) work without quoting in any shell.

The gem gracefully degrades when no database is connected — it parses db/schema.rb as text. This means it works in:

• CI environments
• Claude Code sessions (no DB running)
• Docker build stages
• Any environment where you have the source code but not a running database

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

rails-ai-context is not another MCP SDK. It's a product that gives your Rails app AI superpowers with one bundle add.

git clone https://github.com/crisnahine/rails-ai-context.git
cd rails-ai-context
bundle install
bundle exec rspec

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

If rails-ai-context helps your workflow, consider supporting the project — become a monthly sponsor or buy me a coffee.

MIT License