rails-ai-context 5.3.0 → 5.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9d802d024a373d0552ee2b70cf3d5d755fd79f951b8335da948563a7f488af4
-  data.tar.gz: fabf3246fb0df9a97294bca58dac86d4bccc7ffd881fb1da69dc262d03e43fba
+  metadata.gz: b89e4a41169c9ddd8a649833f96c6792b6c75ec24101ac220d9c3f431c6126e2
+  data.tar.gz: b2e4c8d0fa16d62b8fd2b67e0dddcd6f9754eb085a1b0cbae59d7b6e0d6898d0
 SHA512:
-  metadata.gz: 40fbc9d7455f857de366de800f91ddfa19b9b752cfced2905c2bedc0576a3d54ee4a4c89eccb701904b0eb6cb8babd106cb699182a5eab98981a02d60ff14d6f
-  data.tar.gz: e640c259017a222d43a32d15a8c7e70f9888eb3a8df3ad172159efa17371003196ade1f2bf561683a319fa4cebc6b16262f72aee56dea636d2be5fa0a5c7dba7
+  metadata.gz: 670a61dd4524c7cae544b3277947191fe4e8ab6f0de54eca4e14eb27c8255e1b1b36c6ad10c99e76e9eac46bc4954676fae9f4680d7108dbc3134422ab9e5d13
+  data.tar.gz: f6ca688b6ae4e2c1c41cde1fdba672596cc25815f72d32cd85f039e64596c8c61f30cd24ff2d0996cd7acacb8217abace18eee32ae5ea1d0569d2376d217fad8

data/CHANGELOG.md

@@ -5,6 +5,82 @@ 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).
 
+## [5.6.0] — 2026-04-09
+
+### Added — Auto-Registration, TestHelper & Bug Fixes
+
+Developer experience improvements inspired by action_mcp patterns, plus 5 security/correctness bug fixes.
+
+- **Auto-registration via `inherited` hook** — Tools are now auto-discovered from `BaseTool` subclasses. No manual list to maintain — drop a file in `tools/` and it's registered. `Server.builtin_tools` is the new public API. Thread-safe via `@registry_mutex` with deadlock-free design (const_get runs outside mutex to avoid recursive locking from inherited). `Server::TOOLS` preserved as deprecated `const_missing` shim for backwards compatibility.
+
+- **`abstract!` pattern** — `BaseTool.abstract!` excludes a class from the registry. `BaseTool` itself is abstract. Subclasses are concrete by default.
+
+- **TestHelper module** (`lib/rails_ai_context/test_helper.rb`) — Reusable test helper for custom_tools users. Methods: `execute_tool` (by name, short name, or class), `execute_tool_with_error`, `assert_tool_findable`, `assert_tool_response_includes`, `assert_tool_response_excludes`, `extract_response_text`. Works with both RSpec and Minitest. Supports fuzzy name resolution (`schema` → `rails_get_schema`).
+
+### Fixed
+
+- **SQL comment stripping validation bypass** (HIGH) — `#` comment stripping now restricted to line-start only, preventing validation bypass via hash characters in string literals. PostgreSQL JSONB operators (`#>>`) preserved.
+
+- **SHARED_CACHE read outside mutex** (MEDIUM) — `redact_results` now uses `cached_context` for thread-safe access to encrypted column data.
+
+- **McpController double-checked locking** (MEDIUM) — Removed unsynchronized read outside mutex, fixing unsafe pattern on non-GVL Rubies (JRuby/TruffleRuby).
+
+- **PG EXPLAIN parser bare rescue** (LOW) — Changed from `rescue` to `rescue JSON::ParserError`, preventing silent swallowing of bugs in `extract_pg_nodes`.
+
+- **GetConcern `class_methods` block closing** (LOW) — Indent-based tracking to detect the closing `end`, so `def self.` methods after the block are no longer lost.
+
+- **Query spec graceful degradation** — Replaced permanently-pending spec (sqlite3 2.x removed `set_progress_handler`) with a spec that verifies queries execute correctly without it.
+
+## [5.5.0] — 2026-04-08
+
+### Added — Universal MCP Auto-Discovery & Per-Tool Context Optimization (#51-#56)
+
+Every AI tool now gets its own MCP config file — auto-detected on project open. No manual setup needed for any supported tool.
+
+- **McpConfigGenerator** (`lib/rails_ai_context/mcp_config_generator.rb`) — Shared infrastructure for per-tool MCP config generation. Writes `.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor), `.vscode/mcp.json` (GitHub Copilot), `opencode.json` (OpenCode), `.codex/config.toml` (Codex CLI). Merge-safe — only manages the `rails-ai-context` entry, preserves other servers. Supports standalone mode and CLI skip.
+
+- **Codex CLI support** (#51) — 5th supported AI tool. Reuses `AGENTS.md` (shared with OpenCode) and `OpencodeRulesSerializer` for directory-level split rules. Config via `.codex/config.toml` (TOML format) with `[mcp_servers.rails-ai-context.env]` subsection that snapshots Ruby environment variables at install time — required because Codex CLI `env_clear()`s the process before spawning MCP servers. Works with all Ruby version managers (rbenv, rvm, asdf, mise, chruby, system). Added to all 3 install paths (generator, CLI, rake), doctor checks, and search exclusions.
+
+- **Cursor improvements** (#52) — `.cursor/mcp.json` auto-generated for MCP auto-discovery. MCP tools rule changed from `alwaysApply: true` to `alwaysApply: false` with descriptive text for agent-requested (Type 3) loading.
+
+- **OpenCode improvements** (#53) — `opencode.json` auto-generated for MCP auto-discovery.
+
+- **Claude Code improvements** (#54) — `paths:` YAML frontmatter added to `.claude/rules/` schema, models, and components rules for conditional loading. Context and mcp-tools rules remain unconditional.
+
+- **Copilot improvements** (#55) — `.vscode/mcp.json` auto-generated for MCP auto-discovery. `name:` and `description:` YAML frontmatter added to all `.github/instructions/` files. Updated `excludeAgent` spec to validate `code-review`, `coding-agent`, and `workspace` per GitHub Copilot docs.
+
+- **All 3 install paths updated** — Install generator, standalone CLI (`rails-ai-context init`), and rake task (`rails ai:setup`) all delegate to McpConfigGenerator. Codex added as option "5" in interactive tool selection.
+
+- **Doctor expanded** — `check_mcp_json` now validates per-tool MCP configs based on configured `ai_tools` (JSON parse validation + TOML existence check).
+
+- **Search exclusions** — `.codex/`, `.vscode/mcp.json`, `opencode.json` added to `search_code` tool exclusions.
+
+## [5.4.0] — 2026-04-08
+
+### Added — Phase 3: Dynamic VFS & Live Resource Architecture (Ground Truth Engine Blueprint #39)
+
+Live Virtual File System replaces static resource handling. Every MCP resource is introspected fresh on every request — zero stale data.
+
+- **VFS URI Dispatcher** (`lib/rails_ai_context/vfs.rb`) — Pattern-matched routing for `rails-ai-context://` URIs. Resolves models, controllers, controller actions, views, and routes. Each call introspects fresh. Path traversal protection for view reads.
+
+- **4 new MCP Resource Templates:**
+  - `rails-ai-context://controllers/{name}` — controller details with actions, filters, strong params
+  - `rails-ai-context://controllers/{name}/{action}` — action source code and applicable filters
+  - `rails-ai-context://views/{path}` — view template content (path traversal protected)
+  - `rails-ai-context://routes/{controller}` — live route map filtered by controller name
+
+- **MCP Controller** (`app/controllers/rails_ai_context/mcp_controller.rb`) — Native Rails controller for Streamable HTTP transport. Alternative to Rack middleware — integrates with Rails routing, authentication, and middleware stack. Mount via `mount RailsAiContext::Engine, at: "/mcp"`.
+
+- **output_schema on all 38 tools** — Default `MCP::Tool::OutputSchema` set via `BaseTool.inherited` hook. Every tool now declares its output format in the MCP protocol. Individual tools can override with custom schemas.
+
+- **Instrumentation** (`lib/rails_ai_context/instrumentation.rb`) — Bridges MCP gem instrumentation to `ActiveSupport::Notifications`. Events: `rails_ai_context.tools.call`, `rails_ai_context.resources.read`, etc. Subscribe with standard Rails notification patterns.
+
+- **Server instructions** — MCP server now includes `instructions:` field describing the ground truth engine capabilities.
+
+- **Enhanced LiveReload** — Full cache sweep on file changes via `reset_all_caches!` (includes AST, tool, and fingerprint caches).
+
+- **82 new specs** covering VFS resolution (models, controllers, actions, views, routes), instrumentation callback, McpController (thread safety, delegation, subclass isolation), resource templates (5 total), output_schema on all 38 tools, and server configuration.
+
 ## [5.3.0] — 2026-04-07
 
 ### Added — Phase 2: Cross-Tool Semantic Hydration (Ground Truth Engine Blueprint #38)

data/CONTRIBUTING.md

@@ -41,7 +41,7 @@ lib/rails_ai_context/
 1. Create `lib/rails_ai_context/tools/your_tool.rb` inheriting from `BaseTool` (auto-loaded by Zeitwerk)
 2. Define `tool_name`, `description`, `input_schema`, and `annotations`
 3. Implement `def self.call(...)` returning `text_response(string)`
-4. Register in `Server::TOOLS`
+4. Auto-registered — no manual list to update (BaseTool.inherited tracks it)
 5. Write specs in `spec/lib/rails_ai_context/tools/your_tool_spec.rb`
 
 ## Adding a Prism Listener

data/README.md

@@ -9,6 +9,7 @@
 <a href="https://cursor.com"><img src="https://img.shields.io/badge/Cursor-000000?style=for-the-badge&logo=cursor&logoColor=white" alt="Cursor"></a>
 <a href="https://github.com/features/copilot"><img src="https://img.shields.io/badge/GitHub_Copilot-000000?style=for-the-badge&logo=githubcopilot&logoColor=white" alt="GitHub Copilot"></a>
 <a href="https://opencode.ai"><img src="https://img.shields.io/badge/OpenCode-4285F4?style=for-the-badge&logoColor=white" alt="OpenCode"></a>
+<a href="https://codex.openai.com"><img src="https://img.shields.io/badge/Codex_CLI-412991?style=for-the-badge&logo=openai&logoColor=white" alt="Codex CLI"></a>
 <a href="#-cli--works-everywhere"><img src="https://img.shields.io/badge/Any_Terminal-4EAA25?style=for-the-badge&logo=gnubash&logoColor=white" alt="Any Terminal"></a>
 
 
@@ -17,9 +18,10 @@
 [![Downloads](https://img.shields.io/gem/dt/rails-ai-context?color=blue)](https://rubygems.org/gems/rails-ai-context)
 [![CI](https://github.com/crisnahine/rails-ai-context/actions/workflows/ci.yml/badge.svg)](https://github.com/crisnahine/rails-ai-context/actions)
 [![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-green)](https://registry.modelcontextprotocol.io)
+<br>
 [![Ruby](https://img.shields.io/badge/Ruby-3.2%20%7C%203.3%20%7C%203.4-CC342D)](https://github.com/crisnahine/rails-ai-context)
 [![Rails](https://img.shields.io/badge/Rails-7.1%20%7C%207.2%20%7C%208.0-CC0000)](https://github.com/crisnahine/rails-ai-context)
-[![Tests](https://img.shields.io/badge/Tests-1731%20passing-brightgreen)](https://github.com/crisnahine/rails-ai-context/actions)
+[![Tests](https://img.shields.io/badge/Tests-1889%20passing-brightgreen)](https://github.com/crisnahine/rails-ai-context/actions)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 </div>
@@ -66,7 +68,7 @@ rails-ai-context serve    # start MCP server
 
 </div>
 
-Now your AI doesn't guess — it **asks your app directly.** 38 tools that query your schema, models, routes, controllers, views, and conventions on demand. Model introspection uses Prism AST parsing — every result carries a `[VERIFIED]` or `[INFERRED]` confidence tag so AI knows what's ground truth and what needs runtime checking.
+Now your AI doesn't guess — it **asks your app directly.** 38 tools and 5 resource templates that query your schema, models, routes, controllers, views, and conventions on demand. Model introspection uses Prism AST parsing — every result carries a `[VERIFIED]` or `[INFERRED]` confidence tag so AI knows what's ground truth and what needs runtime checking.
 
 <br>
 
@@ -122,15 +124,15 @@ Compare what AI outputs with and without these tools wired in. The difference is
 
 <br>
 
-## Two ways to use it
+## Three ways to use it
 
 <table>
 <tr>
-<td width="50%">
+<td width="33%">
 
-### MCP Server
+### MCP Server (stdio)
 
-AI calls tools directly via the protocol. Auto-discovered through `.mcp.json`.
+AI calls tools directly via the protocol. Each AI tool gets its own config file — auto-detected on project open.
 
 ```
 rails ai:serve
@@ -143,7 +145,21 @@ rails ai:serve
 ```
 
 </td>
-<td width="50%">
+<td width="33%">
+
+### MCP Server (HTTP)
+
+Mount inside your Rails app — inherits routing, auth, and middleware.
+
+```ruby
+# config/routes.rb
+mount RailsAiContext::Engine, at: "/mcp"
+```
+
+Native Rails controller transport. No separate process needed.
+
+</td>
+<td width="33%">
 
 ### CLI
 
@@ -342,6 +358,22 @@ Every tool is **read-only** and returns data verified against your actual app
 
 <br>
 
+## Live Resources (VFS)
+
+AI clients can also read structured data through **resource templates** — `rails-ai-context://` URIs that introspect fresh on every request. Zero stale data.
+
+| Resource Template | What it returns |
+|:------------------|:---------------|
+| `rails-ai-context://controllers/{name}` | Actions, inherited filters, strong params |
+| `rails-ai-context://controllers/{name}/{action}` | Action source code with applicable filters |
+| `rails-ai-context://views/{path}` | View template content (path traversal protected) |
+| `rails-ai-context://routes/{controller}` | Live route map filtered by controller |
+| `rails://models/{name}` | Per-model details: associations, validations, schema |
+
+Plus 9 static resources (schema, routes, conventions, gems, controllers, config, tests, migrations, engines) that AI clients read directly.
+
+<br>
+
 ## Anti-Hallucination Protocol
 
 Every generated context file ships with **6 rules that force AI verification** before writing code. The protocol targets the exact cognitive failures that produce confident-wrong code: statistical priors overriding observed facts, pattern completion beating verification, stale context lies.
@@ -376,14 +408,15 @@ Enabled by default. Disable with `config.anti_hallucination_rules = false` if yo
 ┌─────────────────────────────────────────────────────────┐
 │  rails-ai-context                                        │
 │  Prism AST parsing. Cached. Confidence-tagged results.    │
+│  VFS: rails-ai-context:// URIs introspected fresh.        │
 └────────┬──────────────────┬──────────────┬──────────────┘
          │                  │              │
          ▼                  ▼              ▼
 ┌──────────────────┐ ┌────────────┐ ┌────────────────────┐
 │  Static Files     │ │  MCP Server │ │  CLI Tools          │
 │  CLAUDE.md        │ │  38 tools   │ │  Same 38 tools      │
-│  .cursor/rules/   │ │  stdio/HTTP │ │  No server needed   │
-│  .github/instr... │ │  .mcp.json  │ │  rails 'ai:tool[X]' │
+│  .cursor/rules/   │ │  5 templates│ │  No server needed   │
+│  .github/instr... │ │  stdio/HTTP │ │  rails 'ai:tool[X]' │
 └──────────────────┘ └────────────┘ └────────────────────┘
 ```
 
@@ -406,7 +439,7 @@ cd your-rails-app
 rails-ai-context init
 ```
 
-Both paths ask which AI tools you use and whether you want MCP or CLI mode. `.mcp.json` is auto-detected by Claude Code and Cursor.
+Both paths ask which AI tools you use (Claude Code, Cursor, GitHub Copilot, OpenCode, Codex CLI) and whether you want MCP or CLI mode. Each tool gets its own MCP config file — auto-detected on project open.
 
 <br>
 
@@ -458,6 +491,20 @@ end
 
 <br>
 
+## Observability
+
+Every MCP tool call and resource read fires an `ActiveSupport::Notifications` event. Subscribe with standard Rails patterns:
+
+```ruby
+ActiveSupport::Notifications.subscribe("rails_ai_context.tools.call") do |event|
+  Rails.logger.info "[MCP] #{event.payload[:method]} — #{event.duration}ms"
+end
+```
+
+Events: `rails_ai_context.tools.call`, `rails_ai_context.resources.read`, and more. All 38 tools declare `output_schema` in the MCP protocol, so clients know the response format before calling.
+
+<br>
+
 ## Requirements
 
 - **Ruby** >= 3.2 &nbsp;&nbsp; **Rails** >= 7.1
@@ -472,7 +519,7 @@ end
 ## About
 
 Built by a Rails developer with 10+ years of production experience.<br>
-1731 tests. 38 tools. 31 introspectors. Standalone or in-Gemfile.<br>
+1889 tests. 38 tools. 5 resource templates. 31 introspectors. Standalone or in-Gemfile.<br>
 MIT licensed. [Contributions welcome.](CONTRIBUTING.md)
 
 <br>

data/SECURITY.md

@@ -4,6 +4,10 @@
 
 | Version | Supported          |
 |---------|--------------------|
+| 5.5.x   | :white_check_mark: |
+| 5.4.x   | :white_check_mark: |
+| 5.3.x   | :white_check_mark: |
+| 5.2.x   | :white_check_mark: |
 | 5.1.x   | :white_check_mark: |
 | 5.0.x   | :white_check_mark: |
 | 4.7.x   | :white_check_mark: |

data/app/controllers/rails_ai_context/mcp_controller.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  # Rails controller for serving MCP over Streamable HTTP.
+  # Alternative to the Rack middleware — integrates with Rails routing,
+  # authentication, and middleware stack.
+  #
+  # Mount in routes: mount RailsAiContext::Engine, at: "/mcp"
+  class McpController < ActionController::API
+    def handle
+      rack_response = self.class.mcp_transport.handle_request(request)
+      self.status = rack_response[0]
+      rack_response[1].each { |k, v| response.headers[k] = v }
+      self.response_body = rack_response[2]
+    end
+
+    class << self
+      # Class-level memoization — transport persists across requests.
+      # Thread-safe: MCP::Server and transport are stateless for reads.
+      def mcp_transport
+        @transport_mutex.synchronize do
+          @mcp_transport ||= begin
+            server = RailsAiContext::Server.new(Rails.application, transport: :http).build
+            MCP::Server::Transports::StreamableHTTPTransport.new(server)
+          end
+        end
+      end
+
+      def reset_transport!
+        @transport_mutex.synchronize { @mcp_transport = nil }
+      end
+
+      private
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@transport_mutex, Mutex.new)
+      end
+    end
+
+    @transport_mutex = Mutex.new
+  end
+end

data/config/routes.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+RailsAiContext::Engine.routes.draw do
+  match "/", to: "mcp#handle", via: :all
+end

data/docs/GUIDE.md

@@ -47,7 +47,7 @@ rails ai:context
 This creates:
 1. `config/initializers/rails_ai_context.rb` — configuration file
 2. `.rails-ai-context.yml` — standalone config (enables switching later)
-3. `.mcp.json` — MCP auto-discovery for Claude Code and Cursor
+3. Per-tool MCP config files — auto-discovery for Claude Code, Cursor, Copilot, OpenCode, and Codex
 4. Context files — tailored for each AI assistant
 
 ### Option B: Standalone (no Gemfile entry needed)
@@ -60,16 +60,16 @@ rails-ai-context init
 
 This creates:
 1. `.rails-ai-context.yml` — configuration file
-2. `.mcp.json` — MCP auto-discovery (if MCP mode selected)
+2. Per-tool MCP config files — auto-discovery (if MCP mode selected)
 3. Context files — tailored for each AI assistant
 
 No Gemfile entry, no initializer, no files in your project besides config and context.
 
 ### What the install generator does
 
-1. Creates `.mcp.json` in project root (MCP auto-discovery)
+1. Creates per-tool MCP config files (`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `opencode.json`, `.codex/config.toml`)
 2. Creates `config/initializers/rails_ai_context.rb` with commented defaults
-3. Asks which AI tools you use (Claude, Cursor, Copilot, OpenCode)
+3. Asks which AI tools you use (Claude, Cursor, Copilot, OpenCode, Codex)
 4. Asks whether to enable MCP server (`tool_mode: :mcp`) or use CLI-only mode (`tool_mode: :cli`)
 5. Adds `.ai-context.json` to `.gitignore` (JSON cache — markdown files should be committed)
 6. Generates all context files
@@ -159,7 +159,7 @@ end
 | `.cursor/rules/rails-project.mdc` | Project overview | `alwaysApply: true` — loaded in every conversation. |
 | `.cursor/rules/rails-models.mdc` | Model reference | `globs: app/models/**/*.rb` — auto-attaches when editing models. |
 | `.cursor/rules/rails-controllers.mdc` | Controller reference | `globs: app/controllers/**/*.rb` — auto-attaches when editing controllers. |
-| `.cursor/rules/rails-mcp-tools.mdc` | MCP tool reference | `alwaysApply: true` — always available. |
+| `.cursor/rules/rails-mcp-tools.mdc` | MCP tool reference | `alwaysApply: false` — agent-requested when relevant. |
 
 ### GitHub Copilot (5 files)
 
@@ -193,6 +193,7 @@ Commit **all files except `.ai-context.json`** (which is gitignored). This gives
 | `rails ai:context:full` | full | all | Generate all files in full mode |
 | `rails ai:context:claude` | compact | Claude | CLAUDE.md + .claude/rules/ |
 | `rails ai:context:opencode` | compact | OpenCode | AGENTS.md + per-directory AGENTS.md |
+| `rails ai:context:codex` | compact | Codex | AGENTS.md + .codex/config.toml |
 | `rails ai:context:cursor` | compact | Cursor | .cursor/rules/ |
 | `rails ai:context:copilot` | compact | Copilot | copilot-instructions.md + .github/instructions/ |
 | `rails ai:context:json` | — | JSON | .ai-context.json |
@@ -212,7 +213,7 @@ Commit **all files except `.ai-context.json`** (which is gitignored). This gives
 
 | Command | Transport | Description |
 |---------|-----------|-------------|
-| `rails ai:serve` | stdio | Start MCP server for Claude Code / Cursor. Auto-discovered via `.mcp.json`. |
+| `rails ai:serve` | stdio | Start MCP server. Auto-discovered by each AI tool via its own config file. |
 | `rails ai:serve_http` | HTTP | Start MCP server at `http://127.0.0.1:6029/mcp`. For remote clients. |
 
 ### Utilities
@@ -228,7 +229,7 @@ Commit **all files except `.ai-context.json`** (which is gitignored). This gives
 The gem ships a `rails-ai-context` executable that works **without adding the gem to your Gemfile**. Install globally with `gem install rails-ai-context`, then run from any Rails app directory.
 
 ```bash
-rails-ai-context init                      # Interactive setup (creates .rails-ai-context.yml + .mcp.json)
+rails-ai-context init                      # Interactive setup (creates .rails-ai-context.yml + MCP configs)
 rails-ai-context serve                     # Start MCP server (stdio)
 rails-ai-context serve --transport http    # Start MCP server (HTTP, port 6029)
 rails-ai-context serve --transport http --port 8080  # Custom port
@@ -1010,6 +1011,17 @@ In addition to tools, the gem registers static MCP resources that AI clients can
 | `rails://engines` | Mounted engines with paths and descriptions (JSON) |
 | `rails://models/{name}` | Per-model details (resource template) |
 
+### Dynamic Resource Templates (VFS)
+
+Live resources introspected fresh on every request — zero stale data:
+
+| Resource Template | Description |
+|-------------------|-------------|
+| `rails-ai-context://controllers/{name}` | Controller details with actions, filters, strong params |
+| `rails-ai-context://controllers/{name}/{action}` | Specific action source code and applicable filters |
+| `rails-ai-context://views/{path}` | View template content (path traversal protected) |
+| `rails-ai-context://routes` | Live route map (optionally filter by controller) |
+
 ---
 
 ## MCP Server Setup
@@ -1025,9 +1037,19 @@ curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=rails-ai-cont
 
 ### Auto-discovery (recommended)
 
-The install generator (or `rails-ai-context init`) creates `.mcp.json` in your project root:
+The install generator (or `rails-ai-context init`) creates per-tool MCP config files based on your selected AI tools:
+
+| AI Tool | Config File | Root Key | Format |
+|---------|------------|----------|--------|
+| Claude Code | `.mcp.json` | `mcpServers` | JSON |
+| Cursor | `.cursor/mcp.json` | `mcpServers` | JSON |
+| GitHub Copilot | `.vscode/mcp.json` | `servers` | JSON |
+| OpenCode | `opencode.json` | `mcp` | JSON |
+| Codex CLI | `.codex/config.toml` | `[mcp_servers]` | TOML |
 
-**In-Gemfile:**
+Each file is merge-safe — only the `rails-ai-context` entry is managed, other servers are preserved.
+
+**Example: `.mcp.json` (Claude Code)**
 ```json
 {
   "mcpServers": {
@@ -1039,19 +1061,20 @@ The install generator (or `rails-ai-context init`) creates `.mcp.json` in your p
 }
 ```
 
-**Standalone:**
-```json
-{
-  "mcpServers": {
-    "rails-ai-context": {
-      "command": "rails-ai-context",
-      "args": ["serve"]
-    }
-  }
-}
+**Example: `.codex/config.toml` (Codex CLI)**
+```toml
+[mcp_servers.rails-ai-context]
+command = "bundle"
+args = ["exec", "rails", "ai:serve"]
+
+[mcp_servers.rails-ai-context.env]
+PATH = "/home/user/.rbenv/shims:/usr/local/bin:/usr/bin"
+GEM_HOME = "/home/user/.rbenv/versions/3.3.0/lib/ruby/gems/3.3.0"
 ```
 
-**Claude Code** and **Cursor** auto-detect this file. No manual config needed — just open your project.
+> **Why the `[env]` section?** Codex CLI `env_clear()`s the process before spawning MCP servers, stripping Ruby version manager paths. The install generator snapshots your current Ruby environment (PATH, GEM\_HOME, GEM\_PATH, GEM\_ROOT, RUBY\_VERSION, BUNDLE\_PATH) so the MCP server can find gems regardless of version manager (rbenv, rvm, asdf, mise, chruby, or system Ruby).
+
+Each AI tool auto-detects its own config file. No manual config needed — just open your project.
 
 ### Claude Code
 
@@ -1085,7 +1108,7 @@ Or for standalone: replace `"command": "bundle"` / `"args": ["exec", "rails", "a
 
 ### Cursor
 
-Auto-discovered via `.mcp.json`. Or add manually in **Cursor Settings > MCP**:
+Auto-discovered via `.cursor/mcp.json`. Or add manually in **Cursor Settings > MCP**:
 
 ```json
 {
@@ -1126,6 +1149,17 @@ end
 
 Both transports are **read-only** — they expose the same 38 tools and never modify your app.
 
+### Controller Transport (Alternative)
+
+For tighter Rails integration (authentication, routing, middleware stack), mount the engine instead of using Rack middleware:
+
+```ruby
+# config/routes.rb
+mount RailsAiContext::Engine, at: "/mcp"
+```
+
+This provides a native Rails controller (`RailsAiContext::McpController`) that delegates to the Streamable HTTP transport.
+
 ---
 
 ## Configuration — All Options
@@ -1260,7 +1294,7 @@ end
 | `custom_tools` | Array | `[]` | Additional MCP tool classes to register alongside built-in tools |
 | `skip_tools` | Array | `[]` | Built-in tool names to exclude (e.g. `%w[rails_security_scan]`) |
 | `tool_mode` | Symbol | `:mcp` | `:mcp` (MCP primary + CLI fallback) or `:cli` (CLI only, no MCP server needed) |
-| `ai_tools` | Array | `nil` (all) | AI tools to generate context for: `%i[claude cursor copilot opencode]`. Selected during install. |
+| `ai_tools` | Array | `nil` (all) | AI tools to generate context for: `%i[claude cursor copilot opencode codex]`. Selected during install. |
 | `excluded_models` | Array | internal Rails models | Models to skip |
 | `excluded_paths` | Array | `node_modules tmp log vendor .git` | Paths excluded from code search |
 | `sensitive_patterns` | Array | `.env`, `.key`, `.pem`, credentials | File patterns blocked from search and read tools |
@@ -1386,13 +1420,13 @@ config.introspectors = %i[schema models routes gems auth api]
 
 **Context files loaded:**
 - `CLAUDE.md` — read at conversation start
-- `.claude/rules/*.md` — auto-loaded alongside CLAUDE.md
+- `.claude/rules/*.md` — auto-loaded alongside CLAUDE.md (schema, models, and components rules use `paths:` frontmatter for conditional loading)
 
 **MCP tools:** Available immediately via `.mcp.json`.
 
 ### Cursor
 
-**Auto-discovery:** Opens `.mcp.json` automatically. No setup needed.
+**Auto-discovery:** Opens `.cursor/mcp.json` automatically. No setup needed.
 
 **Context files loaded:**
 - `.cursor/rules/*.mdc` — loaded based on `alwaysApply` and `globs` settings
@@ -1400,13 +1434,13 @@ config.introspectors = %i[schema models routes gems auth api]
 **MDC rule activation modes:**
 | Mode | When it activates |
 |------|-------------------|
-| `alwaysApply: true` | Every conversation (project overview, MCP tools) |
+| `alwaysApply: true` | Every conversation (project overview) |
 | `globs: ["app/models/**/*.rb"]` | When editing files matching the glob pattern |
-| `alwaysApply: false` + `description` | When the AI decides it's relevant based on description |
+| `alwaysApply: false` + `description` | Agent-requested — loaded when AI decides it's relevant (MCP tools rule) |
 
 ### OpenCode
 
-**MCP config:** Add to `opencode.json`:
+**Auto-discovery:** `opencode.json` is auto-generated by the install generator. Or add manually:
 
 ```json
 {
@@ -1440,13 +1474,15 @@ For standalone: use `"command": ["rails-ai-context", "serve"]` instead.
 
 OpenCode uses **per-directory lazy-loading**: when the agent reads a file, it walks up the directory tree and auto-loads any `AGENTS.md` it finds. This is how split rules work — no globs or frontmatter needed.
 
-**MCP tools:** Available via `opencode.json` config above.
+**MCP tools:** Available via `opencode.json` (auto-generated or manual config above).
 
 ### GitHub Copilot
 
+**Auto-discovery:** `.vscode/mcp.json` is auto-generated by the install generator.
+
 **Context files loaded:**
 - `.github/copilot-instructions.md` — repo-wide instructions
-- `.github/instructions/*.instructions.md` — path-specific, activated by `applyTo` glob
+- `.github/instructions/*.instructions.md` — path-specific, activated by `applyTo` glob (with `name:` and `description:` frontmatter)
 
 **applyTo patterns:**
 | Pattern | When it activates |
@@ -1455,6 +1491,17 @@ OpenCode uses **per-directory lazy-loading**: when the agent reads a file, it wa
 | `app/controllers/**/*.rb` | Editing controller files |
 | `**/*` | All files (MCP tool reference) |
 
+### Codex CLI
+
+**Auto-discovery:** `.codex/config.toml` is auto-generated by the install generator, including an `[env]` subsection that snapshots your Ruby environment for sandbox compatibility.
+
+**Context files loaded:**
+- `AGENTS.md` — project overview + MCP tool guide (shared with OpenCode)
+- `app/models/AGENTS.md` — model listing, auto-loaded when agent reads model files
+- `app/controllers/AGENTS.md` — controller listing, auto-loaded when agent reads controller files
+
+**MCP tools:** Available via `.codex/config.toml`.
+
 ---
 
 ## Stack Compatibility
@@ -1606,11 +1653,12 @@ Works in:
 
 ## Troubleshooting
 
-### MCP server not detected by Claude Code / Cursor
+### MCP server not detected by your AI tool
 
-1. Check `.mcp.json` exists in project root
-2. Verify it contains `"command": "bundle"` and `"args": ["exec", "rails", "ai:serve"]`
-3. Restart Claude Code / Cursor
+1. Run `rails ai:doctor` — it checks per-tool MCP config files
+2. Verify the correct config file exists for your tool (`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `opencode.json`, `.codex/config.toml`)
+3. Re-run install (`rails generate rails_ai_context:install` or `rails-ai-context init`) to regenerate configs
+4. Restart your AI tool
 
 ### Context files are too large