rails-ai-context 2.0.4 → 3.0.0

data/lib/rails_ai_context/serializers/copilot_serializer.rb

@@ -9,6 +9,7 @@ module RailsAiContext
       include TestCommandDetection
       include StackOverviewHelper
       include DesignSystemHelper
+      include ToolGuideHelper
 
       attr_reader :context
 
@@ -91,50 +92,13 @@ module RailsAiContext
         # Design System
         lines.concat(render_design_system(context, max_lines: 35))
 
-        # MCP tools
-        lines << "## MCP Tool Reference"
-        lines << ""
-        lines << "This project has MCP tools for live introspection."
-        lines << "**Always start with `detail:\"summary\"`, then drill into specifics.**"
-        lines << ""
-        lines << "### Detail levels (schema, routes, models, controllers)"
-        lines << "- `summary` — names + counts (default limit: 50)"
-        lines << "- `standard` — names + key details (default limit: 15, this is the default)"
-        lines << "- `full` — everything including indexes, FKs (default limit: 5)"
-        lines << ""
-        lines << "### rails_get_schema"
-        lines << "Params: `table`, `detail`, `limit`, `offset`, `format`"
-        lines << "- `rails_get_schema(detail:\"summary\")` — all tables with column counts"
-        lines << "- `rails_get_schema(table:\"users\")` — full detail for one table"
-        lines << "- `rails_get_schema(detail:\"summary\", limit:20, offset:40)` — paginate"
-        lines << ""
-        lines << "### rails_get_model_details"
-        lines << "Params: `model`, `detail`"
-        lines << "- `rails_get_model_details(detail:\"summary\")` — list all model names"
-        lines << "- `rails_get_model_details(model:\"User\")` — associations, validations, scopes, enums"
-        lines << ""
-        lines << "### rails_get_routes"
-        lines << "Params: `controller`, `detail`, `limit`, `offset`"
-        lines << "- `rails_get_routes(detail:\"summary\")` — route counts per controller"
-        lines << "- `rails_get_routes(controller:\"users\")` — routes for one controller"
-        lines << ""
-        lines << "### rails_get_controllers"
-        lines << "Params: `controller`, `detail`"
-        lines << "- `rails_get_controllers(detail:\"summary\")` — names + action counts"
-        lines << "- `rails_get_controllers(controller:\"UsersController\")` — actions, filters, params"
-        lines << ""
-        lines << "### Other tools"
-        lines << "- `rails_get_config` — cache store, session, timezone, middleware"
-        lines << "- `rails_get_test_info` — test framework, factories/fixtures, CI config"
-        lines << "- `rails_get_gems` — notable gems categorized by function"
-        lines << "- `rails_get_conventions` — architecture patterns, directory structure"
-        lines << "- `rails_search_code(pattern:\"regex\", file_type:\"rb\", max_results:20)` — codebase search"
-        lines << ""
+        # Tools reference (respects tool_mode)
+        lines.concat(render_tools_guide)
 
         # Conventions
         lines << "## Conventions"
         lines << "- Follow existing patterns and naming conventions"
-        lines << "- Use MCP tools to check schema before writing migrations"
+        lines << "- Use the introspection tools to check schema before writing migrations"
         lines << "- Run `#{detect_test_command}` after changes"
         lines << ""
 

data/lib/rails_ai_context/serializers/cursor_rules_serializer.rb

@@ -8,6 +8,7 @@ module RailsAiContext
     class CursorRulesSerializer
       include StackOverviewHelper
       include DesignSystemHelper
+      include ToolGuideHelper
 
       attr_reader :context
 
@@ -141,7 +142,6 @@ module RailsAiContext
 
         lines = [
           "---",
-          "description: \"ActiveRecord models reference\"",
           "globs:",
           "  - \"app/models/**/*.rb\"",
           "alwaysApply: false",
@@ -184,7 +184,6 @@ module RailsAiContext
 
         lines = [
           "---",
-          "description: \"Controller reference\"",
           "globs:",
           "  - \"app/controllers/**/*.rb\"",
           "alwaysApply: false",
@@ -215,7 +214,6 @@ module RailsAiContext
 
         lines = [
           "---",
-          "description: \"Design system and UI patterns for this Rails app\"",
           "globs:",
           "  - \"app/views/**/*.erb\"",
           "alwaysApply: false",
@@ -253,52 +251,17 @@ module RailsAiContext
       end
 
       # Always-on MCP tool reference — strongest enforcement point for Cursor
-      def render_mcp_tools_rule # rubocop:disable Metrics/MethodLength
+      def render_mcp_tools_rule
         lines = [
           "---",
-          "description: \"Rails MCP tools (25) — MANDATORY, use before reading any reference files\"",
+          "description: \"Rails tools (25) — MANDATORY, use before reading any reference files\"",
           "alwaysApply: true",
           "---",
-          "",
-          "# Rails MCP Tools (25) — MANDATORY, Use Before Read",
-          "",
-          "CRITICAL: This project has live MCP tools. You MUST use them for gathering context.",
-          "Read files ONLY when you are about to edit them. Never read reference files directly.",
-          "",
-          "## Mandatory Workflow",
-          "1. Gathering context → use MCP tools (NOT file reads, NOT grep)",
-          "2. Reading files → ONLY files you will edit (Read is required before Edit)",
-          "3. After editing → `rails_validate(files:[...])` every time, no exceptions",
-          "",
-          "## Do NOT Bypass — Anti-Patterns",
-          "| Instead of... | Use this MCP tool |",
-          "|---------------|-------------------|",
-          "| Reading db/schema.rb | `rails_get_schema(table:\"name\")` |",
-          "| Reading config/routes.rb | `rails_get_routes(controller:\"name\")` |",
-          "| Reading model files for context | `rails_get_model_details(model:\"Name\")` |",
-          "| Grep for code patterns | `rails_search_code(pattern:\"regex\")` |",
-          "| Reading test files for patterns | `rails_get_test_info(model:\"Name\")` |",
-          "| Reading controller for context | `rails_get_controllers(controller:\"Name\", action:\"x\")` |",
-          "| Reading JS for Stimulus API | `rails_get_stimulus(controller:\"name\")` |",
-          "| Multiple reads for a feature | `rails_analyze_feature(feature:\"keyword\")` |",
-          "| ruby -c / erb / node -c | `rails_validate(files:[...])` |",
-          "",
-          "## All 25 Tools",
-          "- `rails_get_schema` | `rails_get_model_details` | `rails_get_routes` | `rails_get_controllers`",
-          "- `rails_get_view` | `rails_get_stimulus` | `rails_get_test_info` | `rails_analyze_feature`",
-          "- `rails_get_design_system` | `rails_get_edit_context` | `rails_validate` | `rails_search_code`",
-          "- `rails_get_config` | `rails_get_gems` | `rails_get_conventions` | `rails_security_scan`",
-          "- `rails_get_concern` | `rails_get_callbacks` | `rails_get_helper_methods` | `rails_get_service_pattern`",
-          "- `rails_get_job_pattern` | `rails_get_env` | `rails_get_partial_interface` | `rails_get_turbo_map`",
-          "- `rails_get_context(model:\"X\")` — composite cross-layer context in one call",
-          "",
-          "## Power Features",
-          "- `rails_search_code(pattern:\"method\", match_type:\"trace\")` — trace: definition + source + siblings + callers + tests",
-          "- `rails_get_concern(name:\"X\", detail:\"full\")` — concern methods with source code",
-          "- `rails_analyze_feature` — full-stack with inherited filters, route helpers, test gaps",
-          "- `rails_get_schema` — columns, indexes, defaults, encrypted hints, orphaned table warnings"
+          ""
         ]
 
+        lines.concat(render_tools_guide)
+
         lines.join("\n")
       end
     end

data/lib/rails_ai_context/serializers/markdown_serializer.rb

@@ -3,7 +3,7 @@
 module RailsAiContext
   module Serializers
     # Generates AI-friendly markdown context files from introspection data.
-    # Outputs: CLAUDE.md (for Claude Code), .windsurfrules, etc.
+    # Outputs: CLAUDE.md (for Claude Code), copilot-instructions.md, etc.
     class MarkdownSerializer # rubocop:disable Metrics/ClassLength
       include TestCommandDetection
 

data/lib/rails_ai_context/serializers/opencode_serializer.rb

@@ -9,6 +9,7 @@ module RailsAiContext
       include TestCommandDetection
       include StackOverviewHelper
       include DesignSystemHelper
+      include ToolGuideHelper
 
       attr_reader :context
 
@@ -163,44 +164,8 @@ module RailsAiContext
         render_design_system(context, max_lines: 30)
       end
 
-      def render_mcp_guide # rubocop:disable Metrics/MethodLength
-        [
-          "## MCP Tools (25) — MANDATORY, Use Before Read",
-          "",
-          "CRITICAL: This project has live MCP tools. You MUST use them for gathering context.",
-          "Read files ONLY when you are about to edit them. Never read reference files directly.",
-          "Start with `detail:\"summary\"`, then drill into specifics.",
-          "",
-          "### Mandatory Workflow",
-          "1. **Before exploring a feature**: `rails_analyze_feature(feature:\"...\")` — models + controllers (inherited filters) + routes (code-ready helpers) + services + jobs + views + tests + gaps",
-          "2. **Before writing migrations**: `rails_get_schema(table:\"...\")` — NOT reading db/schema.rb",
-          "3. **Before modifying a model**: `rails_get_model_details(model:\"...\")` — NOT reading the model file",
-          "4. **Before adding routes**: `rails_get_routes(controller:\"...\")` — Read only when you will edit",
-          "5. **Before creating views**: `rails_get_design_system` — match existing patterns",
-          "6. **After editing ANY file**: `rails_validate(files:[...])` — no exceptions",
-          "",
-          "### Do NOT Bypass",
-          "| Instead of... | Use this MCP tool |",
-          "|---------------|-------------------|",
-          "| Reading db/schema.rb | `rails_get_schema(table:\"x\")` — includes orphaned table warnings |",
-          "| Reading model files | `rails_get_model_details(model:\"X\")` |",
-          "| Reading routes.rb | `rails_get_routes(controller:\"x\")` |",
-          "| Grep for code | `rails_search_code(pattern:\"x\", match_type:\"trace\")` |",
-          "| Reading test files | `rails_get_test_info(model:\"X\")` |",
-          "| Reading controller | `rails_get_controllers(controller:\"X\", action:\"y\")` |",
-          "| ruby -c / erb / node | `rails_validate(files:[...])` |",
-          "",
-          "### All 25 Tools",
-          "- `rails_get_schema` | `rails_get_model_details` | `rails_get_routes` | `rails_get_controllers`",
-          "- `rails_get_view` | `rails_get_stimulus` | `rails_get_test_info` | `rails_analyze_feature`",
-          "- `rails_get_design_system` | `rails_get_edit_context` | `rails_validate` | `rails_search_code`",
-          "- `rails_get_config` | `rails_get_gems` | `rails_get_conventions` | `rails_security_scan`",
-          "- `rails_get_concern(name:\"X\", detail:\"full\")` — concern methods with source code | `rails_get_callbacks` | `rails_get_helper_methods` | `rails_get_service_pattern`",
-          "- `rails_get_job_pattern` | `rails_get_env` | `rails_get_partial_interface` | `rails_get_turbo_map`",
-          "- `rails_search_code(pattern:\"method\", match_type:\"trace\")` — **trace mode**: definition + class context + source + siblings + callers + test coverage in one call",
-          "- `rails_get_context(model:\"X\")` — composite cross-layer context in one call",
-          ""
-        ]
+      def render_mcp_guide
+        render_tools_guide
       end
 
       def render_conventions

data/lib/rails_ai_context/serializers/tool_guide_helper.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  module Serializers
+    # Shared helper for rendering the tool reference section in context files.
+    # Reads config.tool_mode to generate MCP syntax, CLI syntax, or both.
+    module ToolGuideHelper
+      # Returns the tool invocation example for a given tool call.
+      # MCP: rails_analyze_feature(feature:"cook")
+      # CLI: rails 'ai:tool[analyze_feature]' feature=cook
+      def tool_call(mcp_call, cli_call)
+        case tool_mode
+        when :cli
+          "→ `#{cli_call}`"
+        when :mcp
+          "→ MCP: `#{mcp_call}`\n→ CLI: `#{cli_call}`"
+        else
+          "→ `#{mcp_call}`"
+        end
+      end
+
+      def tool_mode
+        RailsAiContext.configuration.tool_mode
+      end
+
+      def tools_header
+        "## Tools (25) — MANDATORY, Use Before Read"
+      end
+
+      def tools_intro
+        case tool_mode
+        when :cli
+          [
+            "This project has 25 introspection tools. **MANDATORY — use these instead of reading files.**",
+            "They return only relevant, structured data and save tokens. Read files ONLY when you are about to Edit them.",
+            ""
+          ]
+        else
+          [
+            "This project has 25 MCP tools via `rails ai:serve` (configured in `.mcp.json`).",
+            "**MANDATORY — use these instead of reading files.** They return structured data and save tokens.",
+            "Read files ONLY when you are about to Edit them.",
+            "If MCP tools are not connected, use CLI fallback: `#{cli_cmd("TOOL_NAME", "param=value")}`",
+            ""
+          ]
+        end
+      end
+
+      def tools_task_section # rubocop:disable Metrics/MethodLength
+        [
+          "### What Are You Trying to Do?",
+          "",
+          "**Understand a feature or area:**",
+          tool_call("rails_analyze_feature(feature:\"cook\")", cli_cmd("analyze_feature", "feature=cook")),
+          tool_call("rails_get_context(model:\"Cook\")", cli_cmd("context", "model=Cook")),
+          "",
+          "**Understand a method (who calls it, what it calls):**",
+          tool_call("rails_search_code(pattern:\"can_cook?\", match_type:\"trace\")", cli_cmd("search_code", "pattern=\"can_cook?\" match_type=trace")),
+          "",
+          "**Add a field or modify a model:**",
+          tool_call("rails_get_schema(table:\"cooks\")", cli_cmd("schema", "table=cooks")),
+          tool_call("rails_get_model_details(model:\"Cook\")", cli_cmd("model_details", "model=Cook")),
+          "",
+          "**Fix a controller bug:**",
+          tool_call("rails_get_controllers(controller:\"CooksController\", action:\"create\")", cli_cmd("controllers", "controller=CooksController action=create")),
+          "",
+          "**Build or modify a view:**",
+          tool_call("rails_get_design_system(detail:\"standard\")", cli_cmd("design_system", "detail=standard")),
+          tool_call("rails_get_view(controller:\"cooks\")", cli_cmd("view", "controller=cooks")),
+          tool_call("rails_get_partial_interface(partial:\"shared/status_badge\")", cli_cmd("partial_interface", "partial=shared/status_badge")),
+          "",
+          "**Write tests:**",
+          tool_call("rails_get_test_info(detail:\"standard\")", cli_cmd("test_info", "detail=standard")),
+          tool_call("rails_get_test_info(model:\"Cook\")", cli_cmd("test_info", "model=Cook")),
+          "",
+          "**Find code:**",
+          tool_call("rails_search_code(pattern:\"has_many\")", cli_cmd("search_code", "pattern=\"has_many\"")),
+          tool_call("rails_search_code(pattern:\"create\", match_type:\"definition\")", cli_cmd("search_code", "pattern=create match_type=definition")),
+          "",
+          "**After editing (EVERY time):**",
+          tool_call("rails_validate(files:[\"app/models/cook.rb\"], level:\"rails\")", cli_cmd("validate", "files=app/models/cook.rb level=rails")),
+          ""
+        ]
+      end
+
+      def tools_rules_section
+        case tool_mode
+        when :cli
+          [
+            "### Rules",
+            "",
+            "1. NEVER read db/schema.rb, config/routes.rb, model files, or test files for reference — use the CLI tools above",
+            "2. NEVER use Grep or search agents for code search — use `#{cli_cmd("search_code")}`",
+            "3. NEVER run `ruby -c`, `erb`, or `node -c` — use `#{cli_cmd("validate")}`",
+            "4. Read files ONLY when you are about to Edit them",
+            "5. Start with `detail=summary` to orient, then drill into specifics",
+            ""
+          ]
+        else
+          [
+            "### Rules",
+            "",
+            "1. NEVER read db/schema.rb, config/routes.rb, model files, or test files for reference — use the MCP tools above",
+            "2. NEVER use Grep or search agents for code search — use `rails_search_code`",
+            "3. NEVER run `ruby -c`, `erb`, or `node -c` — use `rails_validate`",
+            "4. Read files ONLY when you are about to Edit them",
+            "5. Start with `detail:\"summary\"` to orient, then drill into specifics",
+            "6. If MCP tools are not connected, use CLI: `#{cli_cmd("TOOL_NAME", "param=value")}`",
+            ""
+          ]
+        end
+      end
+
+      def tools_table # rubocop:disable Metrics/MethodLength
+        lines = [ "### All 25 Tools", "" ]
+
+        if tool_mode == :cli
+          lines.concat(tools_table_cli)
+        else
+          lines.concat(tools_table_mcp_and_cli)
+        end
+
+        lines
+      end
+
+      def tools_table_mcp_and_cli # rubocop:disable Metrics/MethodLength
+        [
+          "| MCP | CLI | What it does |",
+          "|-----|-----|-------------|",
+          "| `rails_analyze_feature(feature:\"X\")` | `#{cli_cmd("analyze_feature", "feature=X")}` | Full-stack: models + controllers + routes + services + jobs + views + tests |",
+          "| `rails_get_context(model:\"X\")` | `#{cli_cmd("context", "model=X")}` | Composite: schema + model + controller + routes + views in one call |",
+          "| `rails_search_code(pattern:\"X\", match_type:\"trace\")` | `#{cli_cmd("search_code", "pattern=X match_type=trace")}` | Trace: definition + source + siblings + callers + test coverage |",
+          "| `rails_get_controllers(controller:\"X\", action:\"Y\")` | `#{cli_cmd("controllers", "controller=X action=Y")}` | Action source + inherited filters + render map + private methods |",
+          "| `rails_validate(files:[...], level:\"rails\")` | `#{cli_cmd("validate", "files=a.rb,b.rb level=rails")}` | Syntax + semantic validation + Brakeman security |",
+          "| `rails_get_schema(table:\"X\")` | `#{cli_cmd("schema", "table=X")}` | Columns with [indexed]/[unique]/[encrypted]/[default] hints |",
+          "| `rails_get_model_details(model:\"X\")` | `#{cli_cmd("model_details", "model=X")}` | Associations, validations, scopes, enums, macros, delegations |",
+          "| `rails_get_routes(controller:\"X\")` | `#{cli_cmd("routes", "controller=X")}` | Routes with code-ready helpers and controller filters inline |",
+          "| `rails_get_view(controller:\"X\")` | `#{cli_cmd("view", "controller=X")}` | Templates with ivars, Turbo wiring, Stimulus refs, partial locals |",
+          "| `rails_get_design_system` | `#{cli_cmd("design_system")}` | Canonical HTML/ERB copy-paste patterns for buttons, inputs, cards |",
+          "| `rails_get_stimulus(controller:\"X\")` | `#{cli_cmd("stimulus", "controller=X")}` | Targets, values, actions + HTML data-attributes + view lookup |",
+          "| `rails_get_test_info(model:\"X\")` | `#{cli_cmd("test_info", "model=X")}` | Tests + fixture contents + test template |",
+          "| `rails_get_concern(name:\"X\", detail:\"full\")` | `#{cli_cmd("concern", "name=X detail=full")}` | Concern methods with source + which models include it |",
+          "| `rails_get_callbacks(model:\"X\")` | `#{cli_cmd("callbacks", "model=X")}` | Callbacks in Rails execution order with source |",
+          "| `rails_get_edit_context(file:\"X\", near:\"Y\")` | `#{cli_cmd("edit_context", "file=X near=Y")}` | Code around a match with class/method context |",
+          "| `rails_search_code(pattern:\"X\")` | `#{cli_cmd("search_code", "pattern=X")}` | Regex search + `exclude_tests` + `group_by_file` + pagination |",
+          "| `rails_get_service_pattern` | `#{cli_cmd("service_pattern")}` | Service objects: interface, dependencies, side effects, callers |",
+          "| `rails_get_job_pattern` | `#{cli_cmd("job_pattern")}` | Jobs: queue, retries, guard clauses, broadcasts, schedules |",
+          "| `rails_get_env` | `#{cli_cmd("env")}` | Environment variables + credentials keys (not values) |",
+          "| `rails_get_partial_interface(partial:\"X\")` | `#{cli_cmd("partial_interface", "partial=X")}` | Partial locals contract: what to pass + usage examples |",
+          "| `rails_get_turbo_map` | `#{cli_cmd("turbo_map")}` | Turbo Stream/Frame wiring + mismatch warnings |",
+          "| `rails_get_helper_methods` | `#{cli_cmd("helper_methods")}` | App + framework helpers with view cross-references |",
+          "| `rails_get_config` | `#{cli_cmd("config")}` | Database adapter, auth, assets, cache, queue, Action Cable |",
+          "| `rails_get_gems` | `#{cli_cmd("gems")}` | Notable gems with versions, categories, config file locations |",
+          "| `rails_get_conventions` | `#{cli_cmd("conventions")}` | App patterns: auth checks, flash messages, test patterns |",
+          "| `rails_security_scan` | `#{cli_cmd("security_scan")}` | Brakeman static analysis: SQL injection, XSS, mass assignment |"
+        ]
+      end
+
+      def tools_table_cli # rubocop:disable Metrics/MethodLength
+        [
+          "| CLI | What it does |",
+          "|-----|-------------|",
+          "| `#{cli_cmd("analyze_feature", "feature=X")}` | Full-stack: models + controllers + routes + services + jobs + views + tests |",
+          "| `#{cli_cmd("context", "model=X")}` | Composite: schema + model + controller + routes + views in one call |",
+          "| `#{cli_cmd("search_code", "pattern=X match_type=trace")}` | Trace: definition + source + siblings + callers + test coverage |",
+          "| `#{cli_cmd("controllers", "controller=X action=Y")}` | Action source + inherited filters + render map + private methods |",
+          "| `#{cli_cmd("validate", "files=a.rb,b.rb level=rails")}` | Syntax + semantic validation + Brakeman security |",
+          "| `#{cli_cmd("schema", "table=X")}` | Columns with [indexed]/[unique]/[encrypted]/[default] hints |",
+          "| `#{cli_cmd("model_details", "model=X")}` | Associations, validations, scopes, enums, macros, delegations |",
+          "| `#{cli_cmd("routes", "controller=X")}` | Routes with code-ready helpers and controller filters inline |",
+          "| `#{cli_cmd("view", "controller=X")}` | Templates with ivars, Turbo wiring, Stimulus refs, partial locals |",
+          "| `#{cli_cmd("design_system")}` | Canonical HTML/ERB copy-paste patterns for buttons, inputs, cards |",
+          "| `#{cli_cmd("stimulus", "controller=X")}` | Targets, values, actions + HTML data-attributes + view lookup |",
+          "| `#{cli_cmd("test_info", "model=X")}` | Tests + fixture contents + test template |",
+          "| `#{cli_cmd("concern", "name=X detail=full")}` | Concern methods with source + which models include it |",
+          "| `#{cli_cmd("callbacks", "model=X")}` | Callbacks in Rails execution order with source |",
+          "| `#{cli_cmd("edit_context", "file=X near=Y")}` | Code around a match with class/method context |",
+          "| `#{cli_cmd("search_code", "pattern=X")}` | Regex search + `exclude_tests` + `group_by_file` + pagination |",
+          "| `#{cli_cmd("service_pattern")}` | Service objects: interface, dependencies, side effects, callers |",
+          "| `#{cli_cmd("job_pattern")}` | Jobs: queue, retries, guard clauses, broadcasts, schedules |",
+          "| `#{cli_cmd("env")}` | Environment variables + credentials keys (not values) |",
+          "| `#{cli_cmd("partial_interface", "partial=X")}` | Partial locals contract: what to pass + usage examples |",
+          "| `#{cli_cmd("turbo_map")}` | Turbo Stream/Frame wiring + mismatch warnings |",
+          "| `#{cli_cmd("helper_methods")}` | App + framework helpers with view cross-references |",
+          "| `#{cli_cmd("config")}` | Database adapter, auth, assets, cache, queue, Action Cable |",
+          "| `#{cli_cmd("gems")}` | Notable gems with versions, categories, config file locations |",
+          "| `#{cli_cmd("conventions")}` | App patterns: auth checks, flash messages, test patterns |",
+          "| `#{cli_cmd("security_scan")}` | Brakeman static analysis: SQL injection, XSS, mass assignment |"
+        ]
+      end
+
+      # Full tool guide section — used by all serializers.
+      def render_tools_guide
+        lines = []
+        lines << tools_header
+        lines << ""
+        lines.concat(tools_intro)
+        lines.concat(tools_task_section)
+        lines.concat(tools_rules_section)
+        lines.concat(tools_table)
+        lines
+      end
+
+      private
+
+      # Generate zsh-safe CLI command: rails 'ai:tool[name]' params
+      def cli_cmd(tool_name, params = nil)
+        cmd = "rails 'ai:tool[#{tool_name}]'"
+        cmd += " #{params}" if params
+        cmd
+      end
+    end
+  end
+end

data/lib/rails_ai_context/tasks/rails_ai_context.rake

@@ -6,7 +6,6 @@ ASSISTANT_TABLE = <<~TABLE unless defined?(ASSISTANT_TABLE)
   Claude Code        CLAUDE.md + .claude/rules/            rails ai:context:claude
   OpenCode           AGENTS.md                             rails ai:context:opencode
   Cursor             .cursor/rules/                        rails ai:context:cursor
-  Windsurf           .windsurfrules + .windsurf/rules/     rails ai:context:windsurf
   GitHub Copilot     .github/copilot-instructions.md       rails ai:context:copilot
   JSON (generic)     .ai-context.json                      rails ai:context:json
 TABLE
@@ -28,8 +27,7 @@ AI_TOOL_OPTIONS = {
   "1" => { key: :claude,   name: "Claude Code" },
   "2" => { key: :cursor,   name: "Cursor" },
   "3" => { key: :copilot,  name: "GitHub Copilot" },
-  "4" => { key: :windsurf, name: "Windsurf" },
-  "5" => { key: :opencode, name: "OpenCode" }
+  "4" => { key: :opencode, name: "OpenCode" }
 }.freeze unless defined?(AI_TOOL_OPTIONS)
 
 def prompt_ai_tools
@@ -58,6 +56,67 @@ def prompt_ai_tools
   selected
 end unless defined?(prompt_ai_tools)
 
+def prompt_tool_mode
+  puts ""
+  puts "Do you also want MCP server support?"
+  puts ""
+  puts "  1. Yes — MCP primary + CLI fallback (generates .mcp.json)"
+  puts "  2. No  — CLI only (no server needed)"
+  puts ""
+  print "Enter number (default: 1): "
+  input = $stdin.gets&.strip || "1"
+
+  mode = input == "2" ? :cli : :mcp
+  label = mode == :mcp ? "MCP + CLI fallback" : "CLI only"
+  puts "Selected: #{label}"
+  mode
+end unless defined?(prompt_tool_mode)
+
+def save_tool_mode_to_initializer(mode)
+  init_path = Rails.root.join("config/initializers/rails_ai_context.rb")
+  return unless File.exist?(init_path)
+
+  content = File.read(init_path)
+  mode_line = "  config.tool_mode = :#{mode}"
+
+  if content.include?("config.tool_mode")
+    content.sub!(/^.*config\.tool_mode.*$/, mode_line)
+  elsif content.include?("config.ai_tools")
+    # Insert after ai_tools line
+    content.sub!(/^(.*config\.ai_tools.*)$/, "\\1\n#{mode_line}")
+  elsif content.include?("RailsAiContext.configure")
+    content.sub!(/RailsAiContext\.configure do \|config\|\n/, "RailsAiContext.configure do |config|\n#{mode_line}\n")
+  else
+    return
+  end
+
+  File.write(init_path, content)
+rescue
+  nil
+end unless defined?(save_tool_mode_to_initializer)
+
+def ensure_mcp_json
+  mcp_path = Rails.root.join(".mcp.json")
+  return if File.exist?(mcp_path)
+
+  server_entry = { "command" => "bundle", "args" => [ "exec", "rails", "ai:serve" ] }
+  content = JSON.pretty_generate({ mcpServers: { "rails-ai-context" => server_entry } }) + "\n"
+  File.write(mcp_path, content)
+  puts "✅ Created .mcp.json (MCP auto-discovery for Claude Code, Cursor, etc.)"
+rescue => e
+  puts "⚠️  Could not create .mcp.json: #{e.message}"
+end unless defined?(ensure_mcp_json)
+
+def tool_mode_configured?
+  init_path = Rails.root.join("config/initializers/rails_ai_context.rb")
+  return false unless File.exist?(init_path)
+  content = File.read(init_path)
+  # Check for uncommented tool_mode line (not just a comment)
+  content.match?(/^\s*config\.tool_mode\s*=/)
+rescue
+  false
+end unless defined?(tool_mode_configured?)
+
 def save_ai_tools_to_initializer(tools)
   init_path = Rails.root.join("config/initializers/rails_ai_context.rb")
   return unless File.exist?(init_path)
@@ -82,6 +141,48 @@ rescue
 end unless defined?(save_ai_tools_to_initializer)
 
 namespace :ai do
+  desc "Run an MCP tool from the CLI: rails 'ai:tool[schema]' table=users detail=full"
+  task :tool, [ :name ] => :environment do |_t, args|
+    require "rails_ai_context"
+
+    name = args[:name]
+
+    unless name
+      puts RailsAiContext::CLI::ToolRunner.tool_list
+      next
+    end
+
+    # Parse key=value pairs from ARGV (skip rake-internal args)
+    params = {}
+    ARGV.each do |arg|
+      next if arg.start_with?("-") || arg.include?("[") || arg == "ai:tool"
+      if arg.include?("=")
+        key, value = arg.split("=", 2)
+        params[key.to_sym] = value
+      end
+    end
+
+    json_mode = ENV["JSON"] == "1"
+
+    if params.delete(:help) || ARGV.include?("--help")
+      runner = RailsAiContext::CLI::ToolRunner.new(name, {})
+      puts RailsAiContext::CLI::ToolRunner.tool_help(runner.tool_class)
+      next
+    end
+
+    runner = RailsAiContext::CLI::ToolRunner.new(name, params, json_mode: json_mode)
+    puts runner.run
+  rescue RailsAiContext::CLI::ToolRunner::ToolNotFoundError => e
+    $stderr.puts "Error: #{e.message}"
+    exit 1
+  rescue RailsAiContext::CLI::ToolRunner::InvalidArgumentError => e
+    $stderr.puts "Error: #{e.message}"
+    exit 3
+  rescue => e
+    $stderr.puts "Error: #{e.message}"
+    exit 2
+  end
+
   desc "Generate AI context files for configured AI tools (prompts on first run)"
   task context: :environment do
     require "rails_ai_context"
@@ -96,6 +197,16 @@ namespace :ai do
       save_ai_tools_to_initializer(ai_tools) if ai_tools
     end
 
+    # Prompt for tool_mode if not yet configured in initializer
+    unless tool_mode_configured?
+      tool_mode = prompt_tool_mode
+      RailsAiContext.configuration.tool_mode = tool_mode
+      save_tool_mode_to_initializer(tool_mode)
+    end
+
+    # Auto-create .mcp.json when tool_mode is :mcp and it doesn't exist
+    ensure_mcp_json if RailsAiContext.configuration.tool_mode == :mcp
+
     puts "🔍 Introspecting #{Rails.application.class.module_parent_name}..."
 
     if ai_tools.nil? || ai_tools.empty?
@@ -115,7 +226,7 @@ namespace :ai do
     puts "Change AI tools: config/initializers/rails_ai_context.rb (config.ai_tools)"
   end
 
-  desc "Generate AI context in a specific format (claude, cursor, windsurf, copilot, json)"
+  desc "Generate AI context in a specific format (claude, cursor, copilot, json)"
   task :context_for, [ :format ] => :environment do |_t, args|
     require "rails_ai_context"
 
@@ -131,7 +242,7 @@ namespace :ai do
   end
 
   namespace :context do
-    { claude: "CLAUDE.md", opencode: "AGENTS.md", cursor: ".cursor/rules/", windsurf: ".windsurfrules",
+    { claude: "CLAUDE.md", opencode: "AGENTS.md", cursor: ".cursor/rules/",
       copilot: ".github/copilot-instructions.md", json: ".ai-context.json" }.each do |fmt, file|
       desc "Generate #{file} context file"
       task fmt => :environment do

data/lib/rails_ai_context/tools/get_concern.rb

@@ -386,7 +386,14 @@ module RailsAiContext
       # Extract method source from raw source string using indentation-based matching
       private_class_method def self.extract_method_source(source, method_name)
         source_lines = source.lines
-        start_idx = source_lines.index { |l| l.match?(/\A\s*def\s+#{Regexp.escape(method_name.to_s)}\b/) }
+        escaped = Regexp.escape(method_name.to_s)
+        # Don't use \b after ? or ! — they ARE word boundaries
+        pattern = if method_name.to_s.end_with?("?") || method_name.to_s.end_with?("!")
+          /\A\s*def\s+#{escaped}/
+        else
+          /\A\s*def\s+#{escaped}\b/
+        end
+        start_idx = source_lines.index { |l| l.match?(pattern) }
         return nil unless start_idx
 
         def_indent = source_lines[start_idx][/\A\s*/].length

data/lib/rails_ai_context/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsAiContext
-  VERSION = "2.0.4"
+  VERSION = "3.0.0"
 end

data/lib/rails_ai_context.rb

@@ -3,7 +3,7 @@
 require "zeitwerk"
 
 loader = Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
-loader.inflector.inflect("devops_introspector" => "DevOpsIntrospector")
+loader.inflector.inflect("devops_introspector" => "DevOpsIntrospector", "cli" => "CLI")
 loader.ignore("#{__dir__}/generators")
 loader.ignore("#{__dir__}/rails-ai-context.rb")
 loader.setup

data/server.json

@@ -7,11 +7,11 @@
     "url": "https://github.com/crisnahine/rails-ai-context",
     "source": "github"
   },
-  "version": "2.0.4",
+  "version": "3.0.0",
   "packages": [
     {
       "registryType": "mcpb",
-      "identifier": "https://github.com/crisnahine/rails-ai-context/releases/download/v2.0.4/rails-ai-context-mcp.mcpb",
+      "identifier": "https://github.com/crisnahine/rails-ai-context/releases/download/v3.0.0/rails-ai-context-mcp.mcpb",
       "fileSha256": "dd711a0ad6c4de943ae4da94eaf59a6dc9494b9d57f726e24649ed4e2f156990",
       "transport": {
         "type": "stdio"