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

Test Intelligence Tools

Blast Radius Tools

What It Detects

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

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

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.