rails-ai-context 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f762c8f111cca6b60293f4d3eb26ef68aeb9e1d0c97048b46dcf221ebf7d6069
-  data.tar.gz: 01b9e656715c47aa0a3e67cfb75fb6ac1a5fd7d6444b4ac96837c6202a093487
+  metadata.gz: 6f3efeed4bfe44c20ff766c0398b1d8a526a13c053b47d2a93d8faa320abfdda
+  data.tar.gz: 2cfe5512db995e2b08a2f9516793f1e68e787e8b76092780370ea6b04e280f69
 SHA512:
-  metadata.gz: a5daa689b56aeee3225f0bfa983580adeabbc195c2184b669f5a3689d1cd2760d115afefcc2c925e14eefafea2b28729893b260f141acd00f5e89a6bcb4fc665
-  data.tar.gz: 7fba10086525e15044867dc4c1b5c5a44fd8eaf5f66c08ffbbd6468dfb1f2831d5b03231ec3e0ca02e2fec2a30a4558cd5567262642edf92c750a4bd8286fdc4
+  metadata.gz: 4ccbff85f3a231a4c207522834387662af03240511c2bbbf491023e2b6361b68ea1e109cc3d8b383f02c9989db5542e555b6579b01037c25757acb3d84cc4525
+  data.tar.gz: 62a53606b4e98f331e716a44a8e424479e2cd61649de82814778feb1f4b3de23607f6a1f35fb6664c465fc130c9f2a140d928c6ce8864c4d4038f7ed27ddbcbc

data/.rubocop.yml

@@ -1,5 +1,5 @@
-require:
-  - rubocop-rails-omakase
+inherit_gem:
+  rubocop-rails-omakase: rubocop.yml
 
 AllCops:
   TargetRubyVersion: 3.2

data/CHANGELOG.md

@@ -5,6 +5,68 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-03-18
+
+### Added
+
+- **14 new introspectors** — Controllers, Views, Turbo/Hotwire, I18n, Config, Active Storage, Action Text, Auth, API, Tests, Rake Tasks, Asset Pipeline, DevOps, Action Mailbox
+- **3 new MCP tools** — `rails_get_controllers`, `rails_get_config`, `rails_get_test_info`
+- **3 new MCP resources** — `rails://controllers`, `rails://config`, `rails://tests`
+- **Model introspector enhancements** — Extracts `has_secure_password`, `encrypts`, `normalizes`, `delegate`, `serialize`, `store`, `generates_token_for`, `has_one_attached`, `has_many_attached`, `has_rich_text`, `broadcasts_to` via source parsing
+- **Stimulus introspector enhancements** — Extracts `outlets` and `classes` from controllers
+- **Gem introspector enhancements** — 30+ new notable gems: monitoring (Sentry, Datadog, New Relic, Skylight), admin (ActiveAdmin, Administrate, Avo), pagination (Pagy, Kaminari), search (Ransack, pg_search, Searchkick), forms (SimpleForm), utilities (Faraday, Flipper, Bullet, Rack::Attack), and more
+- **Convention detector enhancements** — Detects concerns, validators, policies, serializers, notifiers, Phlex, PWA, encrypted attributes, normalizations
+- **Markdown serializer sections** — All 14 new introspector sections rendered in generated context files
+- **Doctor enhancements** — 4 new checks: controllers, views, i18n, tests (11 total)
+- **Fingerprinter expansion** — Watches `app/controllers`, `app/views`, `app/jobs`, `app/mailers`, `app/channels`, `app/javascript/controllers`, `config/initializers`, `lib/tasks`; glob now covers `.rb`, `.rake`, `.js`, `.ts`, `.erb`, `.haml`, `.slim`, `.yml`
+
+### Fixed
+
+- **YAML parsing** — `YAML.load_file` calls now pass `permitted_classes: [Symbol], aliases: true` for Psych 4 (Ruby 3.1+) compatibility
+- **Rake task parser** — Fixed `@last_desc` instance variable leaking between files; fixed namespace tracking with indent-based stack
+- **Vite detection** — Changed `File.exist?("vite.config")` to `Dir.glob("vite.config.*")` to match `.js`/`.ts`/`.mjs` extensions
+- **Health check regex** — Added word boundaries to avoid false positives on substrings (e.g. "groups" matching "up")
+- **Multi-attribute macros** — `normalizes :email, :name` now captures all attributes, not just the first
+- **Stimulus action regex** — Requires `method(args) {` pattern to avoid matching control flow keywords
+- **Controller respond_to** — Simplified format extraction to avoid nested `end` keyword issues
+- **GetRoutes nil guard** — Added `|| {}` fallback for `by_controller` to prevent crash on partial introspection data
+- **GetSchema nil guard** — Added `|| {}` fallback for `schema[:tables]` to prevent crash on partial schema data
+- **View layout discovery** — Added `File.file?` filter to exclude directories from layout listing
+- **Fingerprinter glob** — Changed from `**/*.rb` to multi-extension glob to detect changes in `.rake`, `.js`, `.ts`, `.erb` files
+
+### Changed
+
+- Default introspectors expanded from 7 to 21
+- MCP tools expanded from 6 to 9
+- Static MCP resources expanded from 4 to 7
+- Doctor checks expanded from 7 to 11
+- Test suite expanded from 149 to 247 examples with exact value assertions
+
+## [0.3.0] - 2026-03-18
+
+### Added
+
+- **Cache invalidation** — TTL + file fingerprinting for MCP tool cache (replaces permanent `||=` cache)
+- **MCP Resources** — Static resources (`rails://schema`, `rails://routes`, `rails://conventions`, `rails://gems`) and resource template (`rails://models/{name}`)
+- **Per-assistant serializers** — Claude gets behavioral rules, Cursor/Windsurf get compact rules, Copilot gets task-oriented GFM
+- **Stimulus introspector** — Extracts Stimulus controller targets, values, and actions from JS/TS files
+- **Database stats introspector** — Opt-in PostgreSQL approximate row counts via `pg_stat_user_tables`
+- **Auto-mount HTTP middleware** — Rack middleware for MCP endpoint when `config.auto_mount = true`
+- **Diff-aware regeneration** — Context file generation skips unchanged files
+- **`rails ai:doctor`** — Diagnostic command with AI readiness score (0-100)
+- **`rails ai:watch`** — File watcher that auto-regenerates context files on change (requires `listen` gem)
+
+### Fixed
+
+- **Shell injection in SearchCode** — Replaced backtick execution with `Open3.capture2` array form; added file_type validation, max_results cap, and path traversal protection
+- **Scope extraction** — Fixed broken `model.methods.grep(/^_scope_/)` by parsing source files for `scope :name` declarations
+- **Route introspector** — Fixed `route.internal?` compatibility with Rails 8.1
+
+### Changed
+
+- `generate_context` now returns `{ written: [], skipped: [] }` instead of flat array
+- Default introspectors now include `:stimulus`
+
 ## [0.2.0] - 2026-03-18
 
 ### Added

data/CLAUDE.md

@@ -0,0 +1,47 @@
+# CLAUDE.md — rails-ai-context development guide
+
+This is a Ruby gem that auto-introspects Rails applications and exposes their
+structure to AI assistants via the Model Context Protocol (MCP).
+
+## Architecture
+
+- `lib/rails_ai_context.rb` — Main entry point, public API
+- `lib/rails_ai_context/introspector.rb` — Orchestrates sub-introspectors
+- `lib/rails_ai_context/introspectors/` — Individual introspectors (schema, models, routes, jobs, gems, conventions, stimulus, database_stats, controllers, views, turbo, i18n, config, active_storage, action_text, auth, api, tests, rake_tasks, assets, devops, action_mailbox)
+- `lib/rails_ai_context/tools/` — MCP tools using the official mcp SDK
+- `lib/rails_ai_context/serializers/` — Output formatters (claude, rules, copilot, markdown, JSON)
+- `lib/rails_ai_context/resources.rb` — MCP resources (static data AI clients read directly)
+- `lib/rails_ai_context/server.rb` — MCP server configuration (stdio + HTTP transports)
+- `lib/rails_ai_context/middleware.rb` — Rack middleware for auto-mounting MCP HTTP endpoint
+- `lib/rails_ai_context/fingerprinter.rb` — SHA256 file fingerprinting for cache invalidation
+- `lib/rails_ai_context/doctor.rb` — Diagnostic checks and AI readiness scoring
+- `lib/rails_ai_context/watcher.rb` — File watcher for auto-regenerating context files
+- `lib/rails_ai_context/engine.rb` — Rails Engine for auto-integration
+
+## Key Design Decisions
+
+1. **Built on official mcp SDK** — not a custom protocol implementation
+2. **Zero-config** — Railtie auto-registers at boot, introspects without setup
+3. **Graceful degradation** — works without DB by parsing schema.rb as text
+4. **Read-only tools only** — all MCP tools are annotated as non-destructive
+5. **Dual output** — static files (CLAUDE.md) + live MCP server (stdio/HTTP)
+6. **Diff-aware** — context regeneration skips unchanged files
+7. **Per-assistant serializers** — each AI tool gets tailored output format
+
+## Testing
+
+```bash
+bundle exec rspec           # Run specs
+bundle exec rubocop         # Lint
+```
+
+Uses combustion gem for testing Rails engine behavior in isolation.
+
+## Conventions
+
+- Ruby 3.2+ features OK (pattern matching, etc.)
+- Follow rubocop-rails-omakase style
+- Every introspector returns a Hash, never raises (wraps errors in `{ error: msg }`)
+- MCP tools return `MCP::Tool::Response` objects per SDK convention
+- All tools prefixed with `rails_` per MCP naming best practices
+- `generate_context` returns `{ written: [], skipped: [] }` hash

data/README.md

@@ -6,7 +6,7 @@
 [![CI](https://github.com/crisnahine/rails-ai-context/actions/workflows/ci.yml/badge.svg)](https://github.com/crisnahine/rails-ai-context/actions)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-`rails-ai-context` automatically introspects your Rails application and exposes your models, routes, schema, jobs, gems, and conventions to AI assistants through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io).
+`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)](https://modelcontextprotocol.io).
 
 **Your AI assistant instantly understands your entire Rails app. No configuration. No manual tool definitions. Just `bundle add` and go.**
 
@@ -26,12 +26,22 @@ 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 its associations, validations, scopes, enums, and callbacks
-- 🛤️ **Every route** with HTTP verbs, paths, and controller actions
-- ⚡ **Every background job**, mailer, and Action Cable channel
-- 💎 **Every notable gem** and what it means (Devise → auth, Sidekiq → jobs, Turbo → Hotwire)
-- 🏛️ **Your architecture patterns**: service objects, STI, polymorphism, state machines, multi-tenancy
+- **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
 
 ---
 
@@ -51,12 +61,12 @@ rails ai:context
 ```
 
 This creates:
-- `CLAUDE.md` — for Claude Code
-- `.cursorrules` — for Cursor
-- `.windsurfrules` — for Windsurf
-- `.github/copilot-instructions.md` — for GitHub Copilot
+- `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)
 
-**Commit these files.** Your entire team gets smarter AI assistance.
+Each file is tailored to the AI assistant's preferred format. **Commit these files.** Your entire team gets smarter AI assistance.
 
 ### 3. Start the MCP Server
 
@@ -84,7 +94,7 @@ Or add to your Claude Code config (`~/.claude/claude_desktop_config.json`):
 
 ## MCP Tools
 
-The gem exposes 6 tools via MCP that AI clients can call:
+The gem exposes 9 tools via MCP that AI clients can call:
 
 | Tool | Description | Annotations |
 |------|-------------|-------------|
@@ -94,9 +104,27 @@ The gem exposes 6 tools via MCP that AI clients can call:
 | `rails_get_gems` | Notable gems categorized by function with explanations | read-only, idempotent |
 | `rails_search_code` | Ripgrep-powered code search across the codebase | read-only, idempotent |
 | `rails_get_conventions` | Architecture patterns, directory structure, config files | read-only, idempotent |
+| `rails_get_controllers` | Controller actions, filters, strong params, concerns | read-only, idempotent |
+| `rails_get_config` | App configuration: cache, sessions, middleware, initializers | read-only, idempotent |
+| `rails_get_test_info` | Test framework, factories, CI config, coverage | read-only, idempotent |
 
 All tools are **read-only** — they never modify your application or database.
 
+## MCP Resources
+
+In addition to tools, the gem registers MCP resources that AI clients can read directly:
+
+| Resource | Description |
+|----------|-------------|
+| `rails://schema` | Full database schema (JSON) |
+| `rails://routes` | All routes (JSON) |
+| `rails://conventions` | Detected patterns and architecture (JSON) |
+| `rails://gems` | Notable gems with categories (JSON) |
+| `rails://controllers` | All controllers with actions and filters (JSON) |
+| `rails://config` | Application configuration (JSON) |
+| `rails://tests` | Test infrastructure details (JSON) |
+| `rails://models/{name}` | Per-model details (resource template) |
+
 ---
 
 ## How It Works
@@ -124,9 +152,10 @@ All tools are **read-only** — they never modify your application or database.
     (reads file)   any MCP client
 ```
 
-**Two modes:**
+**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.
 
 ---
 
@@ -145,20 +174,49 @@ RailsAiContext.configure do |config|
   config.auto_mount = true
   config.http_path  = "/mcp"
   config.http_port  = 6029
+
+  # Cache TTL for MCP tool responses (seconds)
+  config.cache_ttl = 30
+
+  # Enable Postgres row count stats (opt-in)
+  # config.introspectors += [:database_stats]
 end
 ```
 
 ---
 
+## Diagnostics
+
+Check your app's AI readiness:
+
+```bash
+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).
+
+---
+
+## Stimulus Support
+
+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.
+
+---
+
 ## Supported AI Assistants
 
-| AI Assistant | Context File | Command |
-|--------------|-------------|---------|
-| Claude Code | `CLAUDE.md` | `rails ai:context:claude` |
-| Cursor | `.cursorrules` | `rails ai:context:cursor` |
-| Windsurf | `.windsurfrules` | `rails ai:context:windsurf` |
-| GitHub Copilot | `.github/copilot-instructions.md` | `rails ai:context:copilot` |
-| JSON (generic) | `.ai-context.json` | `rails ai:context:json` |
+| AI Assistant | Context File | Format | Command |
+|--------------|-------------|--------|---------|
+| Claude Code | `CLAUDE.md` | Verbose + behavioral rules | `rails ai:context:claude` |
+| Cursor | `.cursorrules` | Compact imperative rules | `rails ai:context:cursor` |
+| Windsurf | `.windsurfrules` | Compact imperative rules | `rails ai:context:windsurf` |
+| GitHub Copilot | `.github/copilot-instructions.md` | Task-oriented GFM | `rails ai:context:copilot` |
+| JSON (generic) | `.ai-context.json` | Structured JSON | `rails ai:context:json` |
 
 ---
 
@@ -166,7 +224,7 @@ end
 
 | Command | Description |
 |---------|-------------|
-| `rails ai:context` | Generate all context files (CLAUDE.md, .cursorrules, etc.) |
+| `rails ai:context` | Generate all context files (skips unchanged) |
 | `rails ai:context:claude` | Generate CLAUDE.md only |
 | `rails ai:context:cursor` | Generate .cursorrules only |
 | `rails ai:context:windsurf` | Generate .windsurfrules only |
@@ -175,6 +233,8 @@ end
 | `rails ai:serve` | Start MCP server (stdio, for Claude Code) |
 | `rails ai:serve_http` | Start MCP server (HTTP, for remote clients) |
 | `rails ai:inspect` | Print introspection summary to stdout |
+| `rails ai:doctor` | Run diagnostics and report AI readiness score |
+| `rails ai:watch` | Watch for changes and auto-regenerate context files |
 
 > **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.
 
@@ -196,6 +256,8 @@ The gem gracefully degrades when no database is connected — it parses `db/sche
 - Ruby >= 3.2
 - Rails >= 7.1
 - [mcp](https://github.com/modelcontextprotocol/ruby-sdk) (official MCP SDK, installed automatically)
+- Optional: `listen` gem for watch mode
+- Optional: `ripgrep` for fast code search (falls back to Ruby)
 
 ---
 
@@ -225,6 +287,10 @@ bundle exec rspec
 
 Bug reports and pull requests welcome at https://github.com/crisnahine/rails-ai-context.
 
+## Sponsorship
+
+If rails-ai-context helps your workflow, consider supporting the project — [become a monthly sponsor or buy me a coffee](https://github.com/sponsors/crisnahine).
+
 ## License
 
 [MIT License](LICENSE)

data/exe/rails-ai-context

@@ -28,8 +28,9 @@ module RailsAiContext
 
       format = options[:format].to_sym
       $stderr.puts "Introspecting Rails app..."
-      files = RailsAiContext.generate_context(format: format)
-      files.each { |f| $stderr.puts "  Written: #{f}" }
+      result = RailsAiContext.generate_context(format: format)
+      result[:written].each { |f| $stderr.puts "  Written: #{f}" }
+      result[:skipped].each { |f| $stderr.puts "  Skipped: #{f} (unchanged)" }
     end
 
     desc "inspect", "Print introspection summary"
@@ -42,6 +43,33 @@ module RailsAiContext
       puts JSON.pretty_generate(context)
     end
 
+    desc "watch", "Watch for changes and auto-regenerate context files"
+    def watch
+      boot_rails!
+      require "rails_ai_context"
+
+      RailsAiContext::Watcher.new.start
+    end
+
+    desc "doctor", "Run diagnostic checks and report AI readiness score"
+    def doctor
+      boot_rails!
+      require "rails_ai_context"
+
+      result = RailsAiContext::Doctor.new.run
+      result[:checks].each do |check|
+        icon = case check.status
+        when :pass then "PASS"
+        when :warn then "WARN"
+        when :fail then "FAIL"
+        end
+        $stderr.puts "  [#{icon}] #{check.name}: #{check.message}"
+        $stderr.puts "         Fix: #{check.fix}" if check.fix
+      end
+      $stderr.puts ""
+      $stderr.puts "AI Readiness Score: #{result[:score]}/100"
+    end
+
     desc "version", "Print version"
     def version
       require_relative "../rails_ai_context/version"

data/lib/rails_ai_context/configuration.rb

@@ -26,10 +26,13 @@ module RailsAiContext
     # Maximum depth for association traversal
     attr_accessor :max_association_depth
 
+    # TTL in seconds for cached introspection (default: 30)
+    attr_accessor :cache_ttl
+
     def initialize
       @server_name         = "rails-ai-context"
       @server_version      = RailsAiContext::VERSION
-      @introspectors       = %i[schema models routes jobs gems conventions]
+      @introspectors       = %i[schema models routes jobs gems conventions stimulus controllers views turbo i18n config active_storage action_text auth api tests rake_tasks assets devops action_mailbox]
       @excluded_paths      = %w[node_modules tmp log vendor .git]
       @auto_mount          = false
       @http_path           = "/mcp"
@@ -43,6 +46,7 @@ module RailsAiContext
         ActionMailbox::InboundEmail ActionMailbox::Record
       ]
       @max_association_depth = 2
+      @cache_ttl            = 30
     end
 
     def output_dir_for(app)

data/lib/rails_ai_context/doctor.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  # Diagnostic checker that validates the environment and reports
+  # AI readiness with pass/warn/fail checks and a readiness score.
+  class Doctor
+    Check = Data.define(:name, :status, :message, :fix)
+
+    CHECKS = %i[
+      check_schema
+      check_models
+      check_routes
+      check_gems
+      check_controllers
+      check_views
+      check_i18n
+      check_tests
+      check_context_files
+      check_mcp_buildable
+      check_ripgrep
+    ].freeze
+
+    attr_reader :app
+
+    def initialize(app = nil)
+      @app = app || Rails.application
+    end
+
+    def run
+      results = CHECKS.map { |check| send(check) }
+      score = compute_score(results)
+      { checks: results, score: score }
+    end
+
+    private
+
+    def check_schema
+      schema_path = File.join(app.root, "db/schema.rb")
+      if File.exist?(schema_path)
+        Check.new(name: "Schema", status: :pass, message: "db/schema.rb found", fix: nil)
+      else
+        Check.new(name: "Schema", status: :warn, message: "db/schema.rb not found", fix: "Run `rails db:schema:dump` to generate it")
+      end
+    end
+
+    def check_models
+      models_dir = File.join(app.root, "app/models")
+      if Dir.exist?(models_dir) && Dir.glob(File.join(models_dir, "**/*.rb")).any?
+        count = Dir.glob(File.join(models_dir, "**/*.rb")).size
+        Check.new(name: "Models", status: :pass, message: "#{count} model files found", fix: nil)
+      else
+        Check.new(name: "Models", status: :warn, message: "No model files found in app/models/", fix: "Generate models with `rails generate model`")
+      end
+    end
+
+    def check_routes
+      routes_path = File.join(app.root, "config/routes.rb")
+      if File.exist?(routes_path)
+        Check.new(name: "Routes", status: :pass, message: "config/routes.rb found", fix: nil)
+      else
+        Check.new(name: "Routes", status: :fail, message: "config/routes.rb not found", fix: "Ensure you're in a Rails app root directory")
+      end
+    end
+
+    def check_gems
+      lock_path = File.join(app.root, "Gemfile.lock")
+      if File.exist?(lock_path)
+        Check.new(name: "Gems", status: :pass, message: "Gemfile.lock found", fix: nil)
+      else
+        Check.new(name: "Gems", status: :warn, message: "Gemfile.lock not found", fix: "Run `bundle install` to generate it")
+      end
+    end
+
+    def check_controllers
+      dir = File.join(app.root, "app/controllers")
+      if Dir.exist?(dir) && Dir.glob(File.join(dir, "**/*.rb")).any?
+        count = Dir.glob(File.join(dir, "**/*.rb")).size
+        Check.new(name: "Controllers", status: :pass, message: "#{count} controller files found", fix: nil)
+      else
+        Check.new(name: "Controllers", status: :warn, message: "No controller files found in app/controllers/", fix: "Generate controllers with `rails generate controller`")
+      end
+    end
+
+    def check_views
+      dir = File.join(app.root, "app/views")
+      if Dir.exist?(dir) && Dir.glob(File.join(dir, "**/*")).reject { |f| File.directory?(f) }.any?
+        count = Dir.glob(File.join(dir, "**/*")).reject { |f| File.directory?(f) }.size
+        Check.new(name: "Views", status: :pass, message: "#{count} view files found", fix: nil)
+      else
+        Check.new(name: "Views", status: :warn, message: "No view files found in app/views/", fix: "Views are generated alongside controllers")
+      end
+    end
+
+    def check_i18n
+      dir = File.join(app.root, "config/locales")
+      if Dir.exist?(dir) && Dir.glob(File.join(dir, "**/*.{yml,yaml}")).any?
+        count = Dir.glob(File.join(dir, "**/*.{yml,yaml}")).size
+        Check.new(name: "I18n", status: :pass, message: "#{count} locale files found", fix: nil)
+      else
+        Check.new(name: "I18n", status: :warn, message: "No locale files found in config/locales/", fix: "Add locale files for internationalization support")
+      end
+    end
+
+    def check_tests
+      if Dir.exist?(File.join(app.root, "spec")) || Dir.exist?(File.join(app.root, "test"))
+        framework = Dir.exist?(File.join(app.root, "spec")) ? "RSpec" : "Minitest"
+        Check.new(name: "Tests", status: :pass, message: "#{framework} test directory found", fix: nil)
+      else
+        Check.new(name: "Tests", status: :warn, message: "No test directory found", fix: "Set up tests with `rails generate rspec:install` or use default Minitest")
+      end
+    end
+
+    def check_context_files
+      claude_path = File.join(app.root, "CLAUDE.md")
+      if File.exist?(claude_path)
+        Check.new(name: "Context files", status: :pass, message: "CLAUDE.md exists", fix: nil)
+      else
+        Check.new(name: "Context files", status: :warn, message: "No context files generated yet", fix: "Run `rails ai:context` to generate them")
+      end
+    end
+
+    def check_mcp_buildable
+      Server.new(app).build
+      Check.new(name: "MCP server", status: :pass, message: "MCP server builds successfully", fix: nil)
+    rescue => e
+      Check.new(name: "MCP server", status: :fail, message: "MCP server failed to build: #{e.message}", fix: "Check mcp gem installation: `bundle info mcp`")
+    end
+
+    def check_ripgrep
+      if system("which rg > /dev/null 2>&1")
+        Check.new(name: "ripgrep", status: :pass, message: "rg available for code search", fix: nil)
+      else
+        Check.new(name: "ripgrep", status: :warn, message: "ripgrep not installed (code search will use slower Ruby fallback)", fix: "Install with `brew install ripgrep` or `apt install ripgrep`")
+      end
+    end
+
+    def compute_score(results)
+      total = results.size * 10
+      earned = results.sum do |check|
+        case check.status
+        when :pass then 10
+        when :warn then 5
+        else 0
+        end
+      end
+      ((earned.to_f / total) * 100).round
+    end
+  end
+end

data/lib/rails_ai_context/engine.rb

@@ -8,6 +8,14 @@ module RailsAiContext
       Rails.application.config.rails_ai_context = RailsAiContext.configuration
     end
 
+    # Auto-mount MCP HTTP middleware when configured
+    initializer "rails_ai_context.middleware" do |app|
+      if RailsAiContext.configuration.auto_mount
+        require_relative "middleware"
+        app.middleware.use RailsAiContext::Middleware
+      end
+    end
+
     # Register Rake tasks
     rake_tasks do
       load File.expand_path("tasks/rails_ai_context.rake", __dir__)

data/lib/rails_ai_context/fingerprinter.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module RailsAiContext
+  # Computes a SHA256 fingerprint of key application files to detect changes.
+  # Used by BaseTool to invalidate cached introspection when files change.
+  class Fingerprinter
+    WATCHED_FILES = %w[
+      db/schema.rb
+      config/routes.rb
+      Gemfile.lock
+    ].freeze
+
+    WATCHED_DIRS = %w[
+      app/models
+      app/controllers
+      app/views
+      app/jobs
+      app/mailers
+      app/channels
+      app/javascript/controllers
+      config/initializers
+      lib/tasks
+    ].freeze
+
+    class << self
+      def compute(app)
+        root = app.root.to_s
+        digest = Digest::SHA256.new
+
+        WATCHED_FILES.each do |file|
+          path = File.join(root, file)
+          digest.update(File.mtime(path).to_f.to_s) if File.exist?(path)
+        end
+
+        WATCHED_DIRS.each do |dir|
+          full_dir = File.join(root, dir)
+          next unless Dir.exist?(full_dir)
+
+          Dir.glob(File.join(full_dir, "**/*.{rb,rake,js,ts,erb,haml,slim,yml}")).sort.each do |path|
+            digest.update(File.mtime(path).to_f.to_s)
+          end
+        end
+
+        digest.hexdigest
+      end
+
+      def changed?(app, previous)
+        compute(app) != previous
+      end
+    end
+  end
+end

data/lib/rails_ai_context/introspector.rb

@@ -53,6 +53,22 @@ module RailsAiContext
       when :jobs        then Introspectors::JobIntrospector.new(app)
       when :gems        then Introspectors::GemIntrospector.new(app)
       when :conventions then Introspectors::ConventionDetector.new(app)
+      when :stimulus       then Introspectors::StimulusIntrospector.new(app)
+      when :database_stats then Introspectors::DatabaseStatsIntrospector.new(app)
+      when :controllers    then Introspectors::ControllerIntrospector.new(app)
+      when :views          then Introspectors::ViewIntrospector.new(app)
+      when :turbo          then Introspectors::TurboIntrospector.new(app)
+      when :i18n           then Introspectors::I18nIntrospector.new(app)
+      when :config         then Introspectors::ConfigIntrospector.new(app)
+      when :active_storage then Introspectors::ActiveStorageIntrospector.new(app)
+      when :action_text    then Introspectors::ActionTextIntrospector.new(app)
+      when :auth           then Introspectors::AuthIntrospector.new(app)
+      when :api            then Introspectors::ApiIntrospector.new(app)
+      when :tests          then Introspectors::TestIntrospector.new(app)
+      when :rake_tasks     then Introspectors::RakeTaskIntrospector.new(app)
+      when :assets         then Introspectors::AssetPipelineIntrospector.new(app)
+      when :devops         then Introspectors::DevOpsIntrospector.new(app)
+      when :action_mailbox then Introspectors::ActionMailboxIntrospector.new(app)
       else
         raise ConfigurationError, "Unknown introspector: #{name}"
       end