rails-ai-context 5.4.0 → 5.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43e8a71c793404bd950627b8f3319b4e909a0ba7a2cfe937a8d1027e2ede4af0
-  data.tar.gz: f296960edc1f3f336e90b9549618fd4b48d51d31330d95a65de9304ba47aa0af
+  metadata.gz: b89e4a41169c9ddd8a649833f96c6792b6c75ec24101ac220d9c3f431c6126e2
+  data.tar.gz: b2e4c8d0fa16d62b8fd2b67e0dddcd6f9754eb085a1b0cbae59d7b6e0d6898d0
 SHA512:
-  metadata.gz: bc10e825ef820ad955e89ded454469104160f954b967958866876794b1c114d9b708564e99781f1252cf4faa683d468bf5143823ee3418080de43ef745508ab2
-  data.tar.gz: 127d4159c5d88da79ae7fcb7389ffb84cca28621e0181da7b7e495e6af6fe0f8c0073b37dff3087a67be78c236e6f09e36aaef82e070461406e8a2027d88d2a8
+  metadata.gz: 670a61dd4524c7cae544b3277947191fe4e8ab6f0de54eca4e14eb27c8255e1b1b36c6ad10c99e76e9eac46bc4954676fae9f4680d7108dbc3134422ab9e5d13
+  data.tar.gz: f6ca688b6ae4e2c1c41cde1fdba672596cc25815f72d32cd85f039e64596c8c61f30cd24ff2d0996cd7acacb8217abace18eee32ae5ea1d0569d2376d217fad8

data/CHANGELOG.md

@@ -5,6 +5,56 @@ 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)

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>
 
 
@@ -20,7 +21,7 @@
 <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-1813%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>
@@ -131,7 +132,7 @@ Compare what AI outputs with and without these tools wired in. The difference is
 
 ### 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
@@ -438,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>
 
@@ -518,7 +519,7 @@ Events: `rails_ai_context.tools.call`, `rails_ai_context.resources.read`, and mo
 ## About
 
 Built by a Rails developer with 10+ years of production experience.<br>
-1813 tests. 38 tools. 5 resource templates. 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

@@ -18,7 +18,7 @@ module RailsAiContext
       # Class-level memoization — transport persists across requests.
       # Thread-safe: MCP::Server and transport are stateless for reads.
       def mcp_transport
-        @mcp_transport || @transport_mutex.synchronize do
+        @transport_mutex.synchronize do
           @mcp_transport ||= begin
             server = RailsAiContext::Server.new(Rails.application, transport: :http).build
             MCP::Server::Transports::StreamableHTTPTransport.new(server)

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
@@ -1036,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:
 
-**In-Gemfile:**
+| 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 |
+
+Each file is merge-safe — only the `rails-ai-context` entry is managed, other servers are preserved.
+
+**Example: `.mcp.json` (Claude Code)**
 ```json
 {
   "mcpServers": {
@@ -1050,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
 
@@ -1096,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
 {
@@ -1282,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 |
@@ -1408,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
@@ -1422,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
 {
@@ -1462,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 |
@@ -1477,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
@@ -1628,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
 

data/exe/rails-ai-context

@@ -167,8 +167,8 @@ class RailsAiContextCLI < Thor
       # --- Write .rails-ai-context.yml ---
       write_yaml_config(ai_tools, tool_mode)
 
-      # --- Write .mcp.json (MCP mode only) ---
-      write_standalone_mcp_json if tool_mode == :mcp
+      # --- Write per-tool MCP config files (MCP mode only) ---
+      write_mcp_configs(ai_tools, tool_mode)
 
       # --- Add .ai-context.json to .gitignore ---
       add_to_gitignore
@@ -200,7 +200,8 @@ class RailsAiContextCLI < Thor
       "1" => { key: :claude,   name: "Claude Code",    files: "CLAUDE.md + .claude/rules/" },
       "2" => { key: :cursor,   name: "Cursor",         files: ".cursor/rules/" },
       "3" => { key: :copilot,  name: "GitHub Copilot", files: ".github/copilot-instructions.md + .github/instructions/" },
-      "4" => { key: :opencode, name: "OpenCode",       files: "AGENTS.md" }
+      "4" => { key: :opencode, name: "OpenCode",       files: "AGENTS.md" },
+      "5" => { key: :codex,   name: "Codex CLI",      files: "AGENTS.md + .codex/config.toml" }
     }.freeze
 
     def prompt_ai_tools
@@ -233,7 +234,7 @@ class RailsAiContextCLI < Thor
       $stderr.puts ""
       $stderr.puts "Do you also want MCP server support?"
       $stderr.puts ""
-      $stderr.puts "  1. Yes — MCP server (generates .mcp.json)"
+      $stderr.puts "  1. Yes — MCP server (generates per-tool MCP config files)"
       $stderr.puts "  2. No  — CLI only (no server needed)"
       $stderr.puts ""
       $stderr.print "Enter number (default: 1): "
@@ -245,12 +246,15 @@ class RailsAiContextCLI < Thor
       mode
     end
 
-    # Files/dirs generated per AI tool format — used for cleanup on tool removal
+    # Files/dirs generated per AI tool format — used for cleanup on tool removal.
+    # MCP config files are NOT listed here — they use merge-safe removal via
+    # McpConfigGenerator.remove to preserve other servers' entries.
     FORMAT_PATHS = {
       claude:   %w[CLAUDE.md .claude/rules],
       cursor:   %w[.cursor/rules],
       copilot:  %w[.github/copilot-instructions.md .github/instructions],
-      opencode: %w[AGENTS.md app/models/AGENTS.md app/controllers/AGENTS.md]
+      opencode: %w[AGENTS.md app/models/AGENTS.md app/controllers/AGENTS.md],
+      codex:    %w[AGENTS.md app/models/AGENTS.md app/controllers/AGENTS.md]
     }.freeze
 
     def read_previous_ai_tools
@@ -297,10 +301,17 @@ class RailsAiContextCLI < Thor
       return if to_remove.empty?
 
       require "fileutils"
+      # Collect paths still needed by remaining tools to avoid deleting shared files
+      kept_paths = current.map(&:to_sym).flat_map { |f| FORMAT_PATHS[f] || [] }.to_set
+
       to_remove.each do |fmt|
         tool = AI_TOOL_OPTIONS.values.find { |t| t[:key] == fmt }
+
+        # Remove context files (skip if another selected tool still needs them)
         paths = FORMAT_PATHS[fmt] || []
         paths.each do |rel_path|
+          next if kept_paths.include?(rel_path)
+
           full = File.join(Dir.pwd, rel_path)
           if File.directory?(full)
             FileUtils.rm_rf(full)
@@ -310,6 +321,11 @@ class RailsAiContextCLI < Thor
             $stderr.puts "  Removed #{rel_path}"
           end
         end
+
+        # Merge-safe MCP config cleanup — removes only the rails-ai-context entry
+        cleaned = RailsAiContext::McpConfigGenerator.remove(tools: [ fmt ], output_dir: Dir.pwd)
+        cleaned.each { |f| $stderr.puts "  Removed MCP entry from #{File.basename(f)}" }
+
         $stderr.puts "  #{tool[:name]} files removed" if tool
       end
     end
@@ -339,26 +355,17 @@ class RailsAiContextCLI < Thor
       $stderr.puts "Created .rails-ai-context.yml"
     end
 
-    def write_standalone_mcp_json
-      require "json"
-      mcp_path = File.join(Dir.pwd, ".mcp.json")
-      server_entry = { "command" => "rails-ai-context", "args" => [ "serve" ] }
-
-      if File.exist?(mcp_path)
-        existing = JSON.parse(File.read(mcp_path)) rescue {}
-        existing["mcpServers"] ||= {}
-        if existing["mcpServers"]["rails-ai-context"] == server_entry
-          $stderr.puts ".mcp.json already up to date — skipped"
-        else
-          existing["mcpServers"]["rails-ai-context"] = server_entry
-          File.write(mcp_path, JSON.pretty_generate(existing) + "\n")
-          $stderr.puts "Updated rails-ai-context in .mcp.json"
-        end
-      else
-        content = JSON.pretty_generate({ mcpServers: { "rails-ai-context" => server_entry } }) + "\n"
-        File.write(mcp_path, content)
-        $stderr.puts "Created .mcp.json (auto-discovered by Claude Code, Cursor, etc.)"
-      end
+    def write_mcp_configs(ai_tools, tool_mode)
+      require_relative "../lib/rails_ai_context/mcp_config_generator"
+      generator = ::RailsAiContext::McpConfigGenerator.new(
+        tools: ai_tools,
+        output_dir: Dir.pwd,
+        standalone: true,
+        tool_mode: tool_mode
+      )
+      result = generator.call
+      result[:written].each { |f| $stderr.puts "  Created/Updated #{f}" }
+      result[:skipped].each { |f| $stderr.puts "  #{f} unchanged — skipped" }
     end
 
     def show_standalone_instructions(ai_tools, tool_mode)
@@ -375,7 +382,7 @@ class RailsAiContextCLI < Thor
       $stderr.puts ""
       $stderr.puts "Commands:"
       $stderr.puts "  rails-ai-context context    # Regenerate context files"
-      $stderr.puts "  rails-ai-context tool NAME  # Run any of the 38 tools"
+      $stderr.puts "  rails-ai-context tool NAME  # Run any of the #{tool_count_str} tools"
       if tool_mode == :mcp
         $stderr.puts "  rails-ai-context serve      # Start MCP server"
       end
@@ -383,8 +390,8 @@ class RailsAiContextCLI < Thor
       $stderr.puts ""
       if tool_mode == :mcp
         $stderr.puts "MCP auto-discovery:"
-        $stderr.puts "  .mcp.json is auto-detected by Claude Code and Cursor."
-        $stderr.puts "  No manual config needed — just open your project."
+        $stderr.puts "  Each AI tool gets its own config file — auto-detected on project open."
+        $stderr.puts "  No manual config needed."
       else
         $stderr.puts "CLI tools:"
         $stderr.puts "  AI agents can run `rails-ai-context tool schema table=users` directly."
@@ -394,6 +401,14 @@ class RailsAiContextCLI < Thor
       $stderr.puts ""
     end
 
+    def tool_count_str
+      if defined?(::RailsAiContext::Server)
+        ::RailsAiContext::Server.builtin_tools.size.to_s
+      else
+        "38"
+      end
+    end
+
     def print_context_result(result)
       (result[:written] || []).each { |f| $stderr.puts "  Written: #{f}" }
       (result[:skipped] || []).each { |f| $stderr.puts "  Skipped: #{f} (unchanged)" }