RailsInsight [Experimental Beta version]

A Rails-aware codebase indexer that runs as an MCP (Model Context Protocol) server, giving AI coding agents deep structural understanding of your Rails application — models, associations, routes, schema, authentication, jobs, components, and 56 total file categories — without reading every file.

Why RailsInsight?

Generic code-analysis tools treat Ruby files as plain text. RailsInsight understands Rails conventions: has_many :through, before_action filters, Devise modules, Pundit policies, Turbo Stream broadcasts, Solid Queue jobs, and more. It builds a directed weighted graph of your entire app and exposes it through MCP tools so your AI agent can reason about impact, dependencies, and architecture — without consuming your entire codebase in tokens.

Installation

First insall the package globally, which will install the MCP server locally, allowing your AI agents to run the indexing tooling.

npm install -g @reinteractive/rails-insight

Claude Code Integration

Add to your Claude Code MCP configuration:

{
  "mcpServers": {
    "railsinsight": {
      "command": "node",
      "args": ["/opt/homebrew/lib/node_modules/@reinteractive/rails-insight/bin/railsinsight.js", "-p", "."]
    }
  }
}

Cursor Integration

In your .cursor/mcp.json:

{
  "mcpServers": {
    "railsinsight": {
      "command": "node",
      "args": ["/opt/homebrew/lib/node_modules/@reinteractive/rails-insight/bin/railsinsight.js", "-p", "."]
    }
  }
}

VS Code Integration

In your VS Code .mcp.json file (or .vscode/mcp.json):

{
  "servers": {
    "railsinsight": {
      "type": "stdio",
      "command": "node",
      "args": ["/opt/homebrew/lib/node_modules/@reinteractive/rails-insight/bin/railsinsight.js"]
    }
  }
}

Available Tools

All 17 tools are available with no tier restrictions.

Core Tools

| Tool | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | index_project | Re-index the Rails project. In local mode, re-scans the project root. Accepts force (boolean) to bypass cache. Returns statistics and duration. | | get_overview | Project summary: Rails/Ruby versions, database, auth strategy, key models and controllers, frontend stack, file counts. Call this first. | | get_full_index | Complete index JSON trimmed to fit a specified token budget (default: 12,000 tokens). | | get_model | Deep extraction for a specific model: associations, validations, scopes with queries, enums with values, callbacks, public methods, database columns. Requires name. | | get_controller | Deep extraction for a specific controller: actions with routes, filters, rate limiting, strong params, rescue handlers. Requires name. | | get_routes | Complete route map with namespaces, nested resources, member/collection routes. | | get_schema | Database schema with tables, columns, indexes, foreign keys, and model-to-table mapping. | | get_subgraph | Skill-scoped relationship subgraph with ranked files. Skills: authentication, database, frontend, api, jobs, email. | | search_patterns | Search across all extractions for a specific Rails pattern type (e.g. has_many_through, before_action, turbo_broadcast). | | get_deep_analysis | Deep analysis for a specific category. Categories: authentication, authorization, jobs, email, storage, caching, realtime, api_patterns, dependencies, cela |

Test Intelligence Tools

| Tool | Description | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | get_coverage_gaps | Prioritised list of files needing test coverage, with structural context and per-method coverage data from SimpleCov. Accepts optional category, min_gap, and l... | | get_test_conventions | Detected test patterns and conventions: spec style (request vs controller), let style, auth helper, factories, shared examples, custom matchers, and pattern referen... | |get_domain_clusters | Domain-clustered file groups for parallel test generation. Files in the same cluster share associations and factories; different clusters can be worked on simultane... | |get_factory_registry | Parsed FactoryBot factory definitions including attributes, traits, sequences, and associations. Accepts optionalmodelto filter by factory name. | |get_well_tested_examples| High-quality existing spec files suitable as pattern references for test generation agents. Selected by structural complexity per spec category. Acceptscategory` ... |

Blast Radius Tools

| Tool | Description | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | get_blast_radius | Analyse the impact of code changes. Accepts explicit file paths or auto-detects from git diff. Returns impacted entities classified by risk level (CRITICAL/HIGH/MEDIUM/LO... | | get_review_context | Build a token-budget-aware review summary for changed files. Combines blast radius analysis with relevant code context for AI-assisted code review. Accepts files, `base... |

What It Detects

RailsInsight classifies files across 56 categories using pure path-based analysis:

| # | Category | # | Category | # | Category | | --- | -------------- | --- | ---------------- | --- | ------------------ | | 1 | Models | 20 | Code Quality | 39 | Rich Text | | 2 | Controllers | 21 | Deployment | 40 | Notifications | | 3 | Routes | 22 | Search | 41 | Feature Flags | | 4 | Schema | 23 | Payments | 42 | Audit | | 5 | Components | 24 | Multi-tenancy | 43 | Soft Delete | | 6 | Stimulus | 25 | Admin | 44 | Pagination | | 7 | Views | 26 | Design Patterns | 45 | Friendly URLs | | 8 | Authentication | 27 | State Machines | 46 | Tagging | | 9 | Authorization | 28 | i18n | 47 | SEO | | 10 | Jobs | 29 | PDF | 48 | Geolocation | | 11 | Email | 30 | CSV | 49 | SMS / Push | | 12 | Storage | 31 | Webhooks | 50 | Activity Tracking | | 13 | Caching | 32 | Scheduled Tasks | 51 | Data Import/Export | | 14 | Realtime | 33 | Middleware | 52 | Event Sourcing | | 15 | API | 34 | Engines | 53 | dry-rb | | 16 | Gemfile | 35 | Credentials | 54 | Markdown | | 17 | Config | 36 | HTTP Client | 55 | Rate Limiting | | 18 | Security | 37 | Performance | 56 | GraphQL | | 19 | Testing | 38 | Database Tooling | | |

Beyond classification, deep extractors analyze file content to extract:

• Models: Associations, validations, scopes, enums, callbacks, concerns, Devise modules, broadcasts
• Controllers: Actions, before/after/around filters, strong params, rescue handlers, caching
• Routes: Resources, namespaces, nesting, member/collection routes, constraints, mounts
• Schema: Tables, columns with types, indexes (unique/composite), foreign keys
• Components: ViewComponent params, slots, Stimulus connections, sidecar files, previews
• Auth: Devise strategy, modules per model, custom controllers, OAuth providers
• Authorization: Pundit/CanCanCan policies, roles, permission structures
• Jobs: Queue names, retry strategies, callbacks, scheduling, Sidekiq/GoodJob config
• Email: Mailer actions, layouts, delivery config, Action Mailbox routing
• Storage: Active Storage services, model attachments, variants, direct upload config
• Caching: Cache store, fragment caching, Russian doll patterns, counter caches
• Realtime: ActionCable channels, Turbo Stream broadcasts, CableReady operations
• API: Versioning strategy, serializers, pagination, rate limiting, authentication

Rails Version Support

| Rails Version | Support Level | | ------------- | --------------------------------------------------------- | | 8.0 – 8.1+ | Full support (Solid Queue, Solid Cache, Kamal, Propshaft) | | 7.0 – 7.2 | Full support (Hotwire, import maps, Turbo) | | 6.0 – 6.1 | Full support (Webpacker, Sprockets, legacy enum syntax) | | < 6.0 | Basic structural scanning only |

How It Works

RailsInsight processes your Rails project through a 7-layer pipeline:

1. Context Loader — Parses claude.md / CLAUDE.md for declared conventions and project context
2. Version Detector — Identifies Rails/Ruby versions, database adapter, asset pipeline, frontend stack, and all gems from Gemfile.lock
3. Structural Scanner — Classifies every file into 1 of 56 categories using path patterns (zero file reads)
4. Deep Extractors — 19 specialized extractors parse file content for models, controllers, routes, schema, components, Stimulus controllers, auth, authorization, jobs, email, storage, caching, realtime, API patterns, views, config, and tier 2/3 patterns
5. Runtime Introspection (optional) — Executes src/introspection/introspect.rb via bundle exec ruby to collect live Rails metadata: resolved associations (including metaprogrammed ones), callbacks inherited from base controllers, columns, enums, and engine routes. Runtime data is merged on top of regex results — runtime wins on facts (associations, columns, enums, callbacks), regex wins on structure (scopes, line ranges, strong params). Pass --no-introspection to skip this step.
6. Relationship Graph — Builds a directed weighted graph with 22 edge types (model→association, controller→model, route→controller, etc.) using runtime-resolved class names where available, and computes Personalized PageRank to rank entities by importance
7. Convention Drift Detector — Compares declared conventions (from claude.md) against actual extracted patterns, reporting mismatches with severity levels

The entire index is built in a single pass, typically under 2 seconds for large projects, and the result is served through MCP tools with token-budget-aware formatting.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Running Tests

npm test                   # Run all tests
npm run test:watch         # Watch mode
npm run test:core          # Core layer tests only
npm run test:extractors    # Extractor tests
npm run test:patterns      # Rails pattern tests
npm run test:coverage      # Run with coverage

Limitations

RailsInsight uses regex-based extraction rather than a full Ruby AST parser. This handles the vast majority of real-world Rails code, but may miss unconventional patterns such as:

• Multi-line method calls split across 3+ lines
• Dynamic class definitions generated at boot time

Metaprogrammed associations and inherited callbacks are addressed by the optional runtime introspection step (v1.0.18+), which runs bundle exec ruby to load and interrogate the app's live object model. Pass --no-introspection to use regex-only mode.

If you encounter a pattern that isn't detected, please open an issue.

License

ISC — see LICENSE for details.