rails-mcp-insight 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5bef39c81f49c39312a2a53416779eaf9051ccd35aae59154fd48eda61fa9ac6
+  data.tar.gz: 3c47c8d03e72b32e035b3ec5c834ef3003baac65241988ad8dca4fde1a688798
+SHA512:
+  metadata.gz: fc2fab417e9a718ab06a0b755b8e39ddf310944e11571c4ad3461877689a54f2fc99fb87d138499005180ee0ff2810aefcbbd2e867069d0e6fefe99620145b8e
+  data.tar.gz: 735a7950a20ab12dff1daf86e3c00f5c76b3eda133fd129c883bf66ce61697f888addf64952c1dcb3d5604396f51887da6b1a3127a6db135afb1aca7d9bcacdf

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2026-07-31
+
+### Added
+- Initial release with 15 MCP tools for Rails introspection
+- `stats_overview` — Project health dashboard
+- `search_routes` — Smart route search with filtering
+- `analyze_model` — Deep model analysis (columns, associations, validations, callbacks)
+- `analyze_controller` — Controller analysis (actions, filters, strong params)
+- `search_code` — Regex code search with context
+- `find_definition` — Symbol definition lookup
+- `list_models` — List all models with metadata
+- `trace_request` — Full HTTP request lifecycle tracing
+- `analyze_migration_history` — Schema evolution timeline
+- `audit_gems` — Dependency analysis
+- `check_security` — Static security scanning
+- `find_tests` — Test file mapping
+- `analyze_job` — ActiveJob analysis
+- `explain_association_chain` — Association pathfinding between models
+- `generate_erd` — Mermaid ERD generation
+- CLI with setup instructions for Claude Desktop, Cursor, and VS Code
+- Built on official MCP Ruby SDK

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aditya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,308 @@
+<p align="center">
+  <h1 align="center">🔍 rails-mcp-insight</h1>
+  <p align="center">
+    <strong>Deep Rails introspection MCP server for AI assistants</strong>
+  </p>
+  <p align="center">
+    <a href="https://rubygems.org/gems/rails-mcp-insight"><img src="https://img.shields.io/gem/v/rails-mcp-insight?color=%23e9573f" alt="Gem Version"></a>
+    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
+    <a href="https://rubygems.org/gems/rails-mcp-insight"><img src="https://img.shields.io/gem/dt/rails-mcp-insight?color=green" alt="Downloads"></a>
+  </p>
+</p>
+
+---
+
+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)](https://modelcontextprotocol.io/).
+
+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:
+
+```json
+{
+  "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)
+
+```bash
+gem install rails-mcp-insight
+```
+
+Verify installation:
+```bash
+rails-mcp-insight --version
+```
+
+### Option 2: Add to Gemfile
+
+Add to your Rails application's `Gemfile`:
+
+```ruby
+group :development do
+  gem "rails-mcp-insight", require: false
+end
+```
+
+Then run:
+```bash
+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
+```json
+{
+  "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:
+
+```json
+{
+  "mcpServers": {
+    "rails-insight": {
+      "command": "rails-mcp-insight",
+      "args": ["--project", "/absolute/path/to/your/rails/app"]
+    }
+  }
+}
+```
+
+#### Option B: Cursor Global Settings
+1. Open Cursor Settings (`Ctrl+,` or `Cmd+,`).
+2. Navigate to **Features** → **MCP Servers**.
+3. Click **Add New MCP Server**.
+4. Name: `rails-insight`
+5. Type: `stdio`
+6. 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`:
+
+```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
+```bash
+git clone https://github.com/aditya/rails-mcp-insight.git
+cd rails-mcp-insight
+```
+
+### 2. Install dependencies
+```bash
+bundle install
+```
+
+### 3. Run the test suite (26 RSpec tests)
+```bash
+bundle exec rspec
+```
+
+### 4. Run RuboCop (Code style check)
+```bash
+bundle exec rubocop
+```
+
+### 5. Test against the included sample Rails fixture
+```bash
+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](LICENSE).
+
+---
+
+<p align="center">
+  <strong>⭐ Star this repo if it helps your Rails development!</strong>
+</p>

data/bin/rails-mcp-insight

@@ -0,0 +1,100 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+begin
+  require "bundler/setup"
+rescue LoadError
+  # Running from installed gem
+end
+
+require_relative "../lib/rails_mcp_insight"
+
+# Parse command line arguments
+project_path = Dir.pwd
+show_version = false
+
+ARGV.each_with_index do |arg, idx|
+  case arg
+  when "--version", "-v"
+    show_version = true
+  when "--project", "-p"
+    project_path = ARGV[idx + 1] if ARGV[idx + 1]
+  when "--help", "-h"
+    $stderr.puts <<~HELP
+      rails-mcp-insight v#{RailsMcpInsight::VERSION}
+
+      Deep Rails introspection MCP server for AI assistants.
+      Provides 15 tools for analyzing routes, models, controllers,
+      security, testing, and full request lifecycle tracing.
+
+      Usage:
+        rails-mcp-insight                    Start MCP server (stdio transport)
+        rails-mcp-insight --project /path    Specify Rails project directory
+        rails-mcp-insight --version          Show version
+        rails-mcp-insight --help             Show this help
+
+      Configuration for AI clients:
+
+        Claude Desktop (~/.claude/claude_desktop_config.json):
+          {
+            "mcpServers": {
+              "rails-insight": {
+                "command": "rails-mcp-insight",
+                "args": ["--project", "/path/to/your/rails/app"]
+              }
+            }
+          }
+
+        Cursor (.cursor/mcp.json):
+          {
+            "mcpServers": {
+              "rails-insight": {
+                "command": "rails-mcp-insight",
+                "args": ["--project", "/path/to/your/rails/app"]
+              }
+            }
+          }
+
+        VS Code (.vscode/mcp.json):
+          {
+            "servers": {
+              "rails-insight": {
+                "type": "stdio",
+                "command": "rails-mcp-insight",
+                "args": ["--project", "/path/to/your/rails/app"]
+              }
+            }
+          }
+
+    HELP
+    exit 0
+  end
+end
+
+if show_version
+  puts "rails-mcp-insight v#{RailsMcpInsight::VERSION}"
+  exit 0
+end
+
+# Log to stderr (stdout is reserved for MCP JSON-RPC)
+$stderr.puts "rails-mcp-insight v#{RailsMcpInsight::VERSION}"
+$stderr.puts "Project: #{project_path}"
+
+# Validate the project
+config = RailsMcpInsight::Configuration.new(project_path: project_path)
+detector = RailsMcpInsight::ProjectDetector.new(config)
+
+begin
+  detector.validate!
+rescue RailsMcpInsight::Error => e
+  $stderr.puts "Error: #{e.message}"
+  exit 1
+end
+
+info = detector.detect
+$stderr.puts "Detected: Rails #{info[:rails_version] || 'unknown'}, " \
+             "#{info[:model_count]} models, #{info[:controller_count]} controllers"
+$stderr.puts "Starting MCP server on stdio..."
+
+# Start the MCP server
+RailsMcpInsight.start(project_path: project_path)

data/lib/rails_mcp_insight/analyzers/ast_parser.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RailsMcpInsight
+  module Analyzers
+    # Lightweight Ruby AST parser using regex-based analysis.
+    # Extracts class definitions, method definitions, module inclusions,
+    # DSL calls (has_many, belongs_to, validates, etc.) from Ruby source files.
+    #
+    # This avoids requiring Prism as a hard dependency while still providing
+    # useful structural information. Can be upgraded to Prism later for
+    # more accurate parsing.
+    class AstParser
+      # Represents a parsed Ruby file's structural information
+      ParseResult = Struct.new(
+        :file_path,
+        :classes,
+        :modules,
+        :methods,
+        :includes,
+        :extends,
+        :dsl_calls,
+        :constants,
+        :comments,
+        keyword_init: true
+      )
+
+      ClassInfo = Struct.new(:name, :parent, :line, :body_lines, keyword_init: true)
+      MethodInfo = Struct.new(:name, :line, :visibility, :args, keyword_init: true)
+      DslCall = Struct.new(:method_name, :args, :line, :options, keyword_init: true)
+
+      def initialize
+        @cache = {}
+      end
+
+      # Parse a Ruby file and return structured information
+      def parse_file(file_path)
+        return nil unless File.exist?(file_path)
+
+        @cache[file_path] ||= begin
+          content = File.read(file_path)
+          parse_content(content, file_path)
+        end
+      end
+
+      # Clear the parse cache
+      def clear_cache!
+        @cache.clear
+      end
+
+      # Parse Ruby source content
+      def parse_content(content, file_path = "(string)")
+        lines = content.lines
+
+        ParseResult.new(
+          file_path: file_path,
+          classes: extract_classes(lines),
+          modules: extract_modules(lines),
+          methods: extract_methods(lines),
+          includes: extract_includes(lines),
+          extends: extract_extends(lines),
+          dsl_calls: extract_dsl_calls(lines),
+          constants: extract_constants(lines),
+          comments: extract_comments(lines)
+        )
+      end
+
+      private
+
+      def extract_classes(lines)
+        classes = []
+        lines.each_with_index do |line, idx|
+          next unless (match = line.match(/^\s*class\s+([A-Z][\w:]*)\s*(?:<\s*([A-Z][\w:]*))?/))
+
+          classes << ClassInfo.new(
+            name: match[1],
+            parent: match[2],
+            line: idx + 1,
+            body_lines: []
+          )
+        end
+        classes
+      end
+
+      def extract_modules(lines)
+        modules = []
+        lines.each_with_index do |line, idx|
+          if (match = line.match(/^\s*module\s+([A-Z][\w:]*)/))
+            modules << { name: match[1], line: idx + 1 }
+          end
+        end
+        modules
+      end
+
+      def extract_methods(lines)
+        methods = []
+        current_visibility = :public
+
+        lines.each_with_index do |line, idx|
+          stripped = line.strip
+
+          # Track visibility changes
+          case stripped
+          when "private" then current_visibility = :private
+          when "protected" then current_visibility = :protected
+          when "public" then current_visibility = :public
+          end
+
+          # Match method definitions
+          next unless (match = stripped.match(/^def\s+(self\.)?(\w+[?!=]?)(?:\((.*?)\))?/))
+
+          is_class_method = !match[1].nil?
+          method_name = match[2]
+          args = match[3]&.strip
+
+          methods << MethodInfo.new(
+            name: is_class_method ? "self.#{method_name}" : method_name,
+            line: idx + 1,
+            visibility: is_class_method ? :public : current_visibility,
+            args: args
+          )
+        end
+        methods
+      end
+
+      def extract_includes(lines)
+        results = []
+        lines.each_with_index do |line, idx|
+          if (match = line.match(/^\s*include\s+(.+)/))
+            results << { module: match[1].strip, line: idx + 1 }
+          end
+        end
+        results
+      end
+
+      def extract_extends(lines)
+        results = []
+        lines.each_with_index do |line, idx|
+          if (match = line.match(/^\s*extend\s+(.+)/))
+            results << { module: match[1].strip, line: idx + 1 }
+          end
+        end
+        results
+      end
+
+      # Extract Rails DSL calls: associations, validations, callbacks, scopes, etc.
+      def extract_dsl_calls(lines)
+        dsl_methods = [
+          "has_many", "has_one", "belongs_to", "has_and_belongs_to_many", "validates", "validates_presence_of", "validates_uniqueness_of", "validates_format_of", "validate", "validates_with", "validates_each", "validates_length_of", "validates_numericality_of", "before_action", "after_action", "around_action", "skip_before_action", "before_create", "after_create", "before_save", "after_save", "before_update", "after_update", "before_destroy", "after_destroy", "before_validation", "after_validation", "after_commit", "after_create_commit", "after_update_commit", "after_destroy_commit", "scope", "enum", "delegate", "has_secure_password", "has_one_attached", "has_many_attached", "rescue_from", "before_enqueue", "before_perform", "after_perform", "around_perform", "queue_as", "retry_on", "discard_on"
+        ]
+
+        pattern = /^\s*(#{dsl_methods.join('|')})\s+(.+)/
+
+        results = []
+        lines.each_with_index do |line, idx|
+          next unless (match = line.match(pattern))
+
+          method_name = match[1]
+          raw_args = match[2].strip.chomp(",")
+
+          results << DslCall.new(
+            method_name: method_name,
+            args: raw_args,
+            line: idx + 1,
+            options: extract_options_from_args(raw_args)
+          )
+        end
+        results
+      end
+
+      def extract_constants(lines)
+        results = []
+        lines.each_with_index do |line, idx|
+          if (match = line.match(/^\s*([A-Z][A-Z_0-9]*)\s*=\s*(.+)/))
+            results << { name: match[1], value: match[2].strip, line: idx + 1 }
+          end
+        end
+        results
+      end
+
+      def extract_comments(lines)
+        results = []
+        lines.each_with_index do |line, idx|
+          results << { text: line.strip.sub(/^#\s*/, ""), line: idx + 1 } if line.strip.start_with?("#")
+        end
+        results
+      end
+
+      def extract_options_from_args(raw_args)
+        # Simple extraction of hash-style options from DSL args
+        options = {}
+        raw_args.scan(/(\w+):\s*(?::(\w+)|"([^"]*)"|(true|false|nil|\d+))/) do |key, sym, str, lit|
+          options[key] = sym || str || lit
+        end
+        options
+      end
+    end
+  end
+end