🔍 rails-mcp-insight

Deep Rails introspection MCP server for AI assistants

Give your AI assistant (Claude Desktop, Cursor, VS Code / Roo Code / Cline) deep, intelligent understanding of your Ruby on Rails application through the open Model Context Protocol (MCP).

Unlike basic tools that dump raw files or schema definitions, rails-mcp-insight provides cross-referenced, contextual intelligence — tracing the full request lifecycle from route → controller → model → callbacks → background jobs → mailers.

✨ Available Tools (15)

Tool	Description	Example Prompt
`stats_overview`	Project dashboard: versions, counts, LOC, test coverage	"Give me an overview of this Rails project."
`search_routes`	Smart route search with HTTP method & path filtering	"Find all POST routes in config/routes.rb"
`analyze_model`	Deep dive: columns, associations, validations, callbacks, scopes	"Analyze the Order model."
`analyze_controller`	Actions, filters, strong params, rescue handlers	"Show details for OrdersController."
`search_code`	Regex code search with surrounding context lines	"Search for stripe_customer_id across the codebase."
`find_definition`	Locate where any class, module, method, or constant is defined	"Where is OrderService defined?"
`list_models`	List all models with table names & metadata at a glance	"List all models in this application."
`trace_request`	🔥 Full request lifecycle tracing (killer feature!)	"Trace what happens when POST /orders is called."
`analyze_migration_history`	Chronological schema evolution & migration timeline	"Show migration history for the users table."
`audit_gems`	Dependency health check from Gemfile / Gemfile.lock	"Audit our installed gems."
`check_security`	Static analysis for SQL injection, mass assignment, XSS, etc.	"Scan this project for security vulnerabilities."
`find_tests`	Map source files → test/spec files + factories	"Find test files for app/models/user.rb"
`analyze_job`	ActiveJob queue, retry/discard config, callbacks, triggers	"Analyze OrderConfirmationJob."
`explain_association_chain`	Find all association paths between two models	"How does User relate to Product?"
`generate_erd`	Mermaid Entity Relationship Diagrams	"Generate an ERD for User, Order, Product."

🎯 The Killer Feature: `trace_request`

Ask your AI: "What happens when a user submits POST /orders?"

rails-mcp-insight traces the full request path statically:

{
  "route": { "method": "POST", "path": "/orders", "controller_action": "orders#create" },
  "controller": {
    "name": "OrdersController",
    "action": "create",
    "before_actions": ["authenticate_user!", "set_cart"],
    "strong_params": [{ "resource": "order", "permitted_attributes": ["product_id", "quantity", "notes"] }]
  },
  "model_operations": {
    "Order": {
      "callbacks": [
        { "type": "before_create", "target": "calculate_total" },
        { "type": "after_create", "target": "notify_warehouse" },
        { "type": "after_commit", "target": "update_inventory" }
      ],
      "validations": ["validates :quantity, presence: true"]
    }
  },
  "side_effects": {
    "jobs": ["OrderConfirmationJob"],
    "mailers": ["OrderMailer"],
    "broadcasts": false
  }
}

📦 Installation

Option 1: Global Gem Installation (Recommended)

gem install rails-mcp-insight

Verify installation:

rails-mcp-insight --version

Option 2: Add to Gemfile

Add to your Rails application's Gemfile:

group :development do
  gem "rails-mcp-insight", require: false
end

Then run:

bundle install

📖 Step-by-Step Setup Guide

1. Claude Desktop Setup

Step 1: Open the configuration file

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Step 2: Add the server entry

{
  "mcpServers": {
    "rails-insight": {
      "command": "rails-mcp-insight",
      "args": ["--project", "/absolute/path/to/your/rails/app"]
    }
  }
}

Step 3: Restart Claude Desktop

Restart Claude Desktop. You will see a hammer icon 🔨 indicating that rails-mcp-insight tools are active.

2. Cursor IDE Setup

Option A: Project-specific config (Recommended)

Create a file at .cursor/mcp.json in your Rails root directory:

{
  "mcpServers": {
    "rails-insight": {
      "command": "rails-mcp-insight",
      "args": ["--project", "/absolute/path/to/your/rails/app"]
    }
  }
}

Option B: Cursor Global Settings

Open Cursor Settings (Ctrl+, or Cmd+,).
Navigate to Features → MCP Servers.
Click Add New MCP Server.
Name: rails-insight
Type: stdio
Command: rails-mcp-insight --project /absolute/path/to/your/rails/app

3. VS Code / Roo Code / Cline Setup

Add to your workspace or global .vscode/mcp.json:

{
  "servers": {
    "rails-insight": {
      "type": "stdio",
      "command": "rails-mcp-insight",
      "args": ["--project", "/absolute/path/to/your/rails/app"]
    }
  }
}

💬 Step-by-Step Usage & Example Prompts

Once configured, simply chat naturally with your AI assistant. Here are concrete examples of how to use each tool:

1. Full Lifecycle Tracing

Prompt: *"Trace what happens when a user calls POST /orders"*
Tool called: trace_request
Result: Traces routes → filters → strong params → model validations/callbacks → background jobs & mailers.

2. Project Health Overview

Prompt: *"Give me a health dashboard for this Rails app."*
Tool called: stats_overview
Result: Displays Ruby/Rails versions, line counts, model/controller totals, and test coverage ratios.

3. Deep Model Inspection

Prompt: *"Analyze the Order model including columns, validations, and callbacks."*
Tool called: analyze_model
Result: Returns schema columns with types, associations (belongs_to :user), scopes, and callback chains.

4. Controller Details

Prompt: *"Show me all before_actions and strong params for OrdersController."*
Tool called: analyze_controller
Result: Extracts filters, allowed params, rescue handlers, and action methods.

5. Relationship Pathfinding

Prompt: *"How does User relate to Product?"*
Tool called: explain_association_chain
Result: Finds all association paths (e.g., User → has_many :orders → Order → belongs_to :product → Product).

6. Visual ERD Generation

Prompt: *"Generate a Mermaid ERD diagram for User, Order, and Product."*
Tool called: generate_erd
Result: Produces a rendered Mermaid erDiagram showing tables, attributes, and relationships.

7. Security Auditing

Prompt: *"Scan this project for potential SQL injection or mass assignment issues."*
Tool called: check_security
Result: Static scan checking 10 security patterns (raw SQL, html_safe, params.permit, eval, system calls).

8. Finding Definitions

Prompt: *"Where is OrderConfirmationJob defined?"*
Tool called: find_definition
Result: Locates exact file and line number across the project.

🛠️ Local Development & Testing Guide

If you want to contribute or test rails-mcp-insight locally:

1. Clone the repository

git clone https://github.com/aditya/rails-mcp-insight.git
cd rails-mcp-insight

2. Install dependencies

bundle install

3. Run the test suite (26 RSpec tests)

bundle exec rspec

4. Run RuboCop (Code style check)

bundle exec rubocop

5. Test against the included sample Rails fixture

bundle exec bin/rails-mcp-insight --project spec/fixtures/sample_rails_app

🏗️ How It Works Under The Hood

rails-mcp-insight performs pure static analysis:

⚡ Fast — No Rails boot time
🔒 Safe — Read-only, never modifies your code or database
🔌 Zero config — Auto-detects Rails project structure
📦 Lightweight — Depends only on the official mcp gem

AI Assistant ←→ MCP (JSON-RPC / stdio) ←→ rails-mcp-insight ←→ Rails App (Filesystem)

🛡️ Security & Privacy

Read-Only: Every tool is declared with read_only_hint: true.
Zero Execution: Does not execute Ruby code inside your Rails application.
Local & Offline: All processing happens locally on your computer. No data is sent to external servers by this gem.

📋 Requirements

Ruby: >= 3.0
Rails App: Rails 5.0+, 6.x, 7.x, 8.x
AI Host: Any MCP-compatible host (Claude Desktop, Cursor, VS Code Roo Code / Cline)

📄 License

Distributed under the MIT License.

⭐ Star this repo if it helps your Rails development!