rails-ai-context 2.0.4 → 3.0.0

data/lib/rails_ai_context/cli/tool_runner.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  module CLI
+    # Runs MCP tools from the command line without requiring an MCP client.
+    # Reads tool schemas at runtime — no hardcoded parameter lists.
+    #
+    # Usage:
+    #   runner = ToolRunner.new("schema", ["--table", "users", "--detail", "full"])
+    #   puts runner.run
+    #
+    #   runner = ToolRunner.new("schema", { table: "users", detail: "full" })
+    #   puts runner.run
+    class ToolRunner
+      class ToolNotFoundError < StandardError; end
+      class InvalidArgumentError < StandardError; end
+
+      attr_reader :tool_class, :raw_args, :json_mode
+
+      def initialize(tool_name, raw_args, json_mode: false)
+        @tool_class = resolve_tool(tool_name)
+        @raw_args = raw_args
+        @json_mode = json_mode
+      end
+
+      def run
+        kwargs = build_kwargs
+        schema = tool_schema
+        validate_kwargs!(kwargs, schema)
+        response = tool_class.call(**kwargs)
+        extract_output(response)
+      end
+
+      # List all available tools with short names and descriptions.
+      def self.tool_list
+        lines = [ "Available tools:", "" ]
+        available_tools.each do |tool|
+          short = short_name(tool.tool_name)
+          desc = tool.description_value.to_s[0..79]
+          lines << "  #{short.ljust(24)} #{desc}"
+        end
+        lines << ""
+        lines << "Usage: rails 'ai:tool[NAME]' param=value"
+        lines << "       rails-ai-context tool NAME --param value"
+        lines.join("\n")
+      end
+
+      # Filtered tool list respecting skip_tools config.
+      def self.available_tools
+        skip = RailsAiContext.configuration.skip_tools
+        tools = Server::TOOLS
+        tools += RailsAiContext.configuration.custom_tools
+        return tools if skip.empty?
+        tools.reject { |t| skip.include?(t.tool_name) }
+      end
+
+      # Generate help for a specific tool from its input_schema.
+      def self.tool_help(tool_class)
+        schema = tool_class.input_schema_value&.schema || {}
+        properties = schema[:properties] || {}
+        required = schema[:required] || []
+
+        lines = [
+          "#{tool_class.tool_name} — #{tool_class.description_value}",
+          "",
+          "Usage:",
+          "  rails 'ai:tool[#{short_name(tool_class.tool_name)}]' #{properties.keys.map { |k| "#{k}=VALUE" }.join(' ')}",
+          "  rails-ai-context tool #{short_name(tool_class.tool_name)} #{properties.keys.map { |k| "--#{k.to_s.tr('_', '-')} VALUE" }.join(' ')}",
+          ""
+        ]
+
+        if properties.any?
+          lines << "Options:"
+          properties.each do |name, prop|
+            flag = "--#{name.to_s.tr('_', '-')}"
+            type_hint = prop[:type] || "string"
+            type_hint = "#{type_hint} (#{prop[:enum].join('/')})" if prop[:enum]
+            req = required.include?(name.to_s) ? " [required]" : ""
+            desc = prop[:description] || ""
+            lines << "  #{flag.ljust(24)} #{desc} (#{type_hint})#{req}"
+          end
+        else
+          lines << "  No parameters."
+        end
+
+        lines.join("\n")
+      end
+
+      # Derive short name: rails_get_schema → schema, rails_analyze_feature → analyze_feature
+      def self.short_name(tool_name)
+        tool_name.sub(/\Arails_get_/, "").sub(/\Arails_/, "")
+      end
+
+      private
+
+      def tool_schema
+        tool_class.input_schema_value&.schema || {}
+      end
+
+      # Resolve tool name: tries short → medium → full form.
+      # "schema" → "rails_get_schema", "search_code" → "rails_search_code"
+      def resolve_tool(name)
+        tools = self.class.available_tools
+        tool_names = tools.map(&:tool_name)
+
+        # Try exact match
+        found = tools.find { |t| t.tool_name == name }
+        return found if found
+
+        # Try rails_ prefix
+        found = tools.find { |t| t.tool_name == "rails_#{name}" }
+        return found if found
+
+        # Try rails_get_ prefix
+        found = tools.find { |t| t.tool_name == "rails_get_#{name}" }
+        return found if found
+
+        # Try case-insensitive short name match
+        found = tools.find { |t| self.class.short_name(t.tool_name) == name }
+        return found if found
+
+        # Fuzzy suggestion
+        short_names = tools.map { |t| self.class.short_name(t.tool_name) }
+        suggestion = Tools::BaseTool.find_closest_match(name, short_names)
+        msg = "Unknown tool '#{name}'."
+        msg += " Did you mean '#{suggestion}'?" if suggestion
+        msg += "\n\nRun with --list to see all available tools."
+        raise ToolNotFoundError, msg
+      end
+
+      # Parse raw_args into keyword arguments hash.
+      # Supports both hash input (rake) and array input (CLI).
+      def build_kwargs
+        kwargs = case raw_args
+        when Hash
+                   raw_args.transform_keys(&:to_sym).except(:server_context)
+        when Array
+                   return parse_cli_args(raw_args).except(:server_context)
+        else
+                   {}
+        end
+
+        properties = (tool_schema[:properties] || {})
+        kwargs.each do |key, value|
+          prop = properties[key]
+          next unless prop
+          kwargs[key] = coerce_value(value, prop)
+        end
+
+        kwargs
+      end
+
+      # Parse ["--table", "users", "--detail", "full", "--app-only"] into { table: "users", ... }
+      def parse_cli_args(args)
+        result = {}
+        i = 0
+        properties = (tool_schema[:properties] || {})
+
+        while i < args.size
+          arg = args[i]
+
+          if arg.start_with?("--no-")
+            key = arg.sub("--no-", "").tr("-", "_").to_sym
+            result[key] = false
+            i += 1
+          elsif arg.start_with?("--")
+            if arg.include?("=")
+              key, value = arg.sub("--", "").split("=", 2)
+              key = key.tr("-", "_").to_sym
+              result[key] = coerce_value(value, properties[key] || {})
+            else
+              key = arg.sub("--", "").tr("-", "_").to_sym
+              prop = properties[key] || {}
+
+              if prop[:type] == "boolean"
+                result[key] = true
+                i += 1
+                next
+              end
+
+              value = args[i + 1]
+              if value && !value.start_with?("--")
+                result[key] = coerce_value(value, prop)
+                i += 2
+                next
+              else
+                result[key] = true
+                i += 1
+                next
+              end
+            end
+            i += 1
+          elsif arg.include?("=")
+            # key=value style (rake)
+            key, value = arg.split("=", 2)
+            key = key.tr("-", "_").to_sym
+            result[key] = coerce_value(value, properties[key] || {})
+            i += 1
+          else
+            i += 1
+          end
+        end
+
+        result
+      end
+
+      # Coerce a string value to the type specified in the JSON Schema property.
+      def coerce_value(raw, property_schema)
+        case property_schema[:type]
+        when "integer"
+          raw.to_i
+        when "boolean"
+          %w[true 1 yes].include?(raw.to_s.downcase)
+        when "array"
+          raw.is_a?(Array) ? raw : raw.to_s.split(",").map(&:strip)
+        else
+          raw.to_s
+        end
+      end
+
+      # Validate kwargs against the tool's input_schema.
+      def validate_kwargs!(kwargs, schema)
+        properties = schema[:properties] || {}
+        required = (schema[:required] || []).map(&:to_s)
+
+        # Check required params
+        required.each do |param|
+          unless kwargs.key?(param.to_sym) && !kwargs[param.to_sym].nil? && kwargs[param.to_sym].to_s != ""
+            raise InvalidArgumentError,
+              "Missing required parameter '#{param}' for #{tool_class.tool_name}.\n" \
+              "Run: rails-ai-context tool #{self.class.short_name(tool_class.tool_name)} --help"
+          end
+        end
+
+        # Check enum constraints
+        kwargs.each do |key, value|
+          prop = properties[key]
+          next unless prop&.dig(:enum)
+          unless prop[:enum].include?(value.to_s)
+            raise InvalidArgumentError,
+              "Invalid value '#{value}' for --#{key.to_s.tr('_', '-')}. " \
+              "Must be one of: #{prop[:enum].join(', ')}"
+          end
+        end
+      end
+
+      # Extract text from MCP::Tool::Response.
+      def extract_output(response)
+        text = response.content.first&.dig(:text) || ""
+        if json_mode
+          require "json"
+          JSON.pretty_generate(tool: tool_class.tool_name, output: text)
+        else
+          text
+        end
+      end
+    end
+  end
+end

data/lib/rails_ai_context/configuration.rb

@@ -56,7 +56,7 @@ module RailsAiContext
     # Debounce interval in seconds for live reload file watching
     attr_accessor :live_reload_debounce
 
-    # Whether to generate root-level context files (CLAUDE.md, AGENTS.md, .windsurfrules, etc.)
+    # Whether to generate root-level context files (CLAUDE.md, AGENTS.md, etc.)
     # When false, only generates split rule files (.claude/rules/, .cursor/rules/, etc.)
     attr_accessor :generate_root_files
 
@@ -76,9 +76,12 @@ module RailsAiContext
     attr_accessor :skip_tools
 
     # Which AI tools to generate context for (selected during install)
-    # nil = all formats, or %i[claude cursor copilot windsurf opencode]
+    # nil = all formats, or %i[claude cursor copilot opencode]
     attr_accessor :ai_tools
 
+    # Tool invocation mode: :mcp (MCP primary + CLI fallback) or :cli (CLI only)
+    attr_accessor :tool_mode
+
     # Filtering — customize what's hidden from AI output
     attr_accessor :excluded_controllers   # Controller classes hidden from listings (e.g. DeviseController)
     attr_accessor :excluded_route_prefixes # Route controller prefixes hidden with app_only (e.g. action_mailbox/)
@@ -153,6 +156,7 @@ module RailsAiContext
       @custom_tools             = []
       @skip_tools               = []
       @ai_tools                 = nil
+      @tool_mode                = :mcp
       @search_extensions        = %w[rb js erb yml yaml json ts tsx vue svelte haml slim]
       @concern_paths            = %w[app/models/concerns app/controllers/concerns]
     end

data/lib/rails_ai_context/serializers/claude_rules_serializer.rb

@@ -7,6 +7,7 @@ module RailsAiContext
     class ClaudeRulesSerializer
       include StackOverviewHelper
       include DesignSystemHelper
+      include ToolGuideHelper
 
       attr_reader :context
 
@@ -293,141 +294,8 @@ module RailsAiContext
         lines.join("\n")
       end
 
-      def render_mcp_tools_reference # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
-        lines = [
-          "# Rails MCP Tools — MANDATORY, Use Before Read/Grep",
-          "",
-          "CRITICAL: This project has live MCP tools. You MUST use them for gathering context.",
-          "MCP tools return parsed, up-to-date, token-efficient data with line numbers.",
-          "Read files ONLY when you are about to Edit them. Never read reference files directly.",
-          "",
-          "## Mandatory Workflow — Follow This Order",
-          "",
-          "### 1. Gathering context (BEFORE writing any code)",
-          "- Exploring a feature area → `rails_analyze_feature(feature:\"...\")` — NOT Explore agents, NOT Grep",
-          "- Understanding a model → `rails_get_model_details(model:\"...\")` — NOT reading the model file",
-          "- Checking database columns → `rails_get_schema(table:\"...\")` — NOT reading db/schema.rb",
-          "- Checking routes → `rails_get_routes(controller:\"...\")` — NOT reading config/routes.rb",
-          "- Understanding a controller → `rails_get_controllers(controller:\"...\", action:\"...\")` — NOT reading the file",
-          "- Finding code patterns → `rails_search_code(pattern:\"...\")` — NOT using Grep tool",
-          "- UI patterns → `rails_get_design_system` — NOT reading view files for patterns",
-          "- Full cross-layer context → `rails_get_context(model:\"...\")` — replaces multiple Read calls",
-          "",
-          "### 2. Reading files (ONLY files you will edit)",
-          "- Read a file ONLY when you are about to Edit it (Read is required before Edit)",
-          "- For everything else — schema, routes, models, tests, patterns — use MCP tools above",
-          "",
-          "### 3. After editing (EVERY time, no exceptions)",
-          "- `rails_validate(files:[\"path/to/file.rb\", \"path/to/view.erb\"])` — one call checks all",
-          "- Do NOT run `ruby -c`, `erb` checks, or `node -c` separately — use rails_validate instead",
-          "- Do NOT re-read files to verify edits. Trust your Edit and validate syntax only.",
-          "",
-          "## Do NOT Bypass — Anti-Patterns",
-          "| Instead of... | Use this MCP tool |",
-          "|---------------|-------------------|",
-          "| Reading db/schema.rb | `rails_get_schema(table:\"name\")` |",
-          "| Reading config/routes.rb for reference | `rails_get_routes(controller:\"name\")` |",
-          "| Reading model files for associations | `rails_get_model_details(model:\"Name\")` |",
-          "| Grep/Explore agent for code search | `rails_search_code(pattern:\"regex\")` |",
-          "| Reading test files for patterns | `rails_get_test_info(model:\"Name\")` |",
-          "| Reading controller files for context | `rails_get_controllers(controller:\"Name\")` |",
-          "| Reading JS files for Stimulus API | `rails_get_stimulus(controller:\"name\")` |",
-          "| Multiple reads to understand a feature | `rails_analyze_feature(feature:\"keyword\")` |",
-          "| ruby -c / erb / node -c after edits | `rails_validate(files:[...])` |",
-          "",
-          "## Reference-only files — NEVER read these, use MCP",
-          "- db/schema.rb → `rails_get_schema` (column types in rails-schema.md rules for quick checks)",
-          "- config/routes.rb → `rails_get_routes` (Read ONLY when adding routes)",
-          "- Model files → `rails_get_model_details` (Read ONLY when editing business logic)",
-          "- app/javascript/controllers/index.js → Stimulus auto-registers. Never read this.",
-          "- Test files → `rails_get_test_info`",
-          "",
-          "## Tools (25)",
-          "",
-          "**rails_get_schema** — database tables, columns, indexes, foreign keys, orphaned table detection",
-          "- `rails_get_schema(detail:\"summary\")` — all tables with column counts + orphaned tables (tables with no ActiveRecord model)",
-          "- `rails_get_schema(table:\"users\")` — full detail for one table",
-          "",
-          "**rails_get_model_details** — associations, validations, scopes, enums, callbacks",
-          "- `rails_get_model_details(detail:\"summary\")` — list all model names",
-          "- `rails_get_model_details(model:\"User\")` — full detail for one model",
-          "",
-          "**rails_get_routes** — HTTP verbs, paths, controller actions",
-          "- `rails_get_routes(detail:\"summary\")` — route counts per controller",
-          "- `rails_get_routes(controller:\"users\")` — routes for one controller",
-          "",
-          "**rails_get_controllers** — actions, filters, strong params, action source code",
-          "- `rails_get_controllers(detail:\"summary\")` — names + action counts",
-          "- `rails_get_controllers(controller:\"CooksController\", action:\"index\")` — action source code + filters",
-          "",
-          "**rails_get_view** — view templates, partials, Stimulus references",
-          "- `rails_get_view(controller:\"cooks\")` — list all views for a controller",
-          "- `rails_get_view(path:\"cooks/index.html.erb\")` — full template content",
-          "",
-          "**rails_get_stimulus** — Stimulus controllers with targets, values, actions",
-          "- `rails_get_stimulus(detail:\"summary\")` — all controllers with counts",
-          "- `rails_get_stimulus(controller:\"filter-form\")` — full detail for one controller",
-          "",
-          "**rails_get_test_info** — test framework, fixtures, factories, helpers",
-          "- `rails_get_test_info(detail:\"full\")` — fixture names, factory names, helper setup",
-          "- `rails_get_test_info(model:\"Cook\")` — full test source for a model",
-          "- `rails_get_test_info(model:\"Cook\", detail:\"summary\")` — test names only (saves tokens)",
-          "- `rails_get_test_info(controller:\"Cooks\")` — existing controller tests",
-          "",
-          "**rails_get_edit_context** — surgical edit helper with line numbers",
-          "- `rails_get_edit_context(file:\"app/models/cook.rb\", near:\"scope\")` — returns code around match with line numbers",
-          "",
-          "**rails_validate** — syntax checker for edited files",
-          "- `rails_validate(files:[\"app/models/cook.rb\"])` — checks Ruby, ERB, JS syntax in one call",
-          "",
-          "**rails_analyze_feature** — combined schema + models + controllers + routes for a feature area",
-          "- `rails_analyze_feature(feature:\"authentication\")` — one call gets everything related to a feature, including inherited filters from parent controllers and code-ready route helpers",
-          "",
-          "**rails_get_design_system** — color palette, component patterns, canonical page examples",
-          "- `rails_get_design_system(detail:\"standard\")` — colors + components + real HTML examples + design rules",
-          "- `rails_get_design_system(detail:\"full\")` — + typography, responsive, dark mode, layout, spacing",
-          "",
-          "**rails_get_config** — cache store, session, timezone, middleware, initializers",
-          "**rails_get_gems** — notable gems categorized by function",
-          "**rails_get_conventions** — architecture patterns, directory structure",
-          "**rails_search_code** — regex search with trace mode for deep call-chain analysis",
-          "- `rails_search_code(pattern:\"regex\", file_type:\"rb\")` — basic regex search across files",
-          "- `rails_search_code(pattern:\"can_cook?\", match_type:\"trace\")` — trace mode: definition + class context + source + siblings + callers with route chain + test coverage",
-          "- `rails_search_code(pattern:\"cook\", exclude_tests: true)` — search app code only, skip test files",
-          "",
-          "**rails_security_scan** — Brakeman security analysis",
-          "- `rails_security_scan` — run security scan, returns warnings by confidence",
-          "",
-          "**rails_get_concern** — concern methods and includers",
-          "- `rails_get_concern(name:\"Searchable\")` — methods, included modules, includers",
-          "- `rails_get_concern(name:\"Searchable\", detail:\"full\")` — + method source code",
-          "",
-          "**rails_get_callbacks** — model callbacks in execution order",
-          "- `rails_get_callbacks(model:\"User\")` — before/after/around callbacks by type",
-          "",
-          "**rails_get_helper_methods** — app + framework helpers",
-          "- `rails_get_helper_methods` — all helper methods across app and framework",
-          "",
-          "**rails_get_service_pattern** — service object patterns and interfaces",
-          "- `rails_get_service_pattern` — service objects with call signatures and dependencies",
-          "",
-          "**rails_get_job_pattern** — background job patterns and schedules",
-          "- `rails_get_job_pattern` — job classes, queues, retry policies, schedules",
-          "",
-          "**rails_get_env** — environment variables and credentials keys",
-          "- `rails_get_env` — ENV vars referenced in code + credentials structure",
-          "",
-          "**rails_get_partial_interface** — partial locals contract",
-          "- `rails_get_partial_interface(path:\"shared/_form\")` — required/optional locals for a partial",
-          "",
-          "**rails_get_turbo_map** — Turbo Streams/Frames wiring",
-          "- `rails_get_turbo_map` — Turbo Frame IDs, Stream channels, broadcast sources",
-          "",
-          "**rails_get_context** — composite cross-layer context",
-          "- `rails_get_context(model:\"User\")` — schema + model + controllers + views in one call"
-        ]
-
-        lines.join("\n")
+      def render_mcp_tools_reference
+        render_tools_guide.join("\n")
       end
     end
   end

data/lib/rails_ai_context/serializers/claude_serializer.rb

@@ -9,6 +9,7 @@ module RailsAiContext
       include TestCommandDetection
       include StackOverviewHelper
       include DesignSystemHelper
+      include ToolGuideHelper
 
       attr_reader :context
 
@@ -196,45 +197,8 @@ module RailsAiContext
         render_design_system(context, max_lines: 30)
       end
 
-      def render_mcp_guide # rubocop:disable Metrics/MethodLength
-        [
-          "## MCP Tools (25) — ALWAYS Use These First",
-          "",
-          "This project has live MCP tools. You MUST use them instead of reading reference files.",
-          "Start with `detail:\"summary\"`, then drill into specifics.",
-          "",
-          "### Mandatory Workflow",
-          "1. **Before exploring a feature**: `rails_analyze_feature(feature:\"...\")` — NOT Explore agents or Grep",
-          "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 routes.rb only when you will edit it",
-          "5. **Before creating views**: `rails_get_design_system` — match existing patterns",
-          "6. **After editing ANY file**: `rails_validate(files:[...])` — no exceptions, no ruby -c / erb / node -c",
-          "",
-          "### Quick Reference",
-          "| Need | Use this MCP tool | Do NOT use |",
-          "|------|-------------------|------------|",
-          "| Column types | `rails_get_schema(table:\"x\")` — includes orphaned table warnings | Read db/schema.rb |",
-          "| Model associations | `rails_get_model_details(model:\"X\")` | Read app/models/x.rb |",
-          "| Route paths | `rails_get_routes(controller:\"x\")` | Read config/routes.rb |",
-          "| Feature overview | `rails_analyze_feature(feature:\"x\")` — models + controllers (inherited filters) + routes (code-ready helpers) + services + jobs + views + tests + gaps | Explore agent / Grep |",
-          "| Find code | `rails_search_code(pattern:\"x\", match_type:\"trace\")` | Grep tool |",
-          "| Validate edits | `rails_validate(files:[...])` | ruby -c / erb / node |",
-          "| Controller logic | `rails_get_controllers(controller:\"X\", action:\"y\")` | Read controller file |",
-          "| UI patterns | `rails_get_design_system` | Read view files |",
-          "| Stimulus API | `rails_get_stimulus(controller:\"x\")` | Read JS files |",
-          "| Test patterns | `rails_get_test_info(model:\"X\")` | Read test files |",
-          "| Full context | `rails_get_context(model:\"X\")` | Multiple Read calls |",
-          "",
-          "### More Tools",
-          "- `rails_get_view(controller:\"x\")` | `rails_get_concern(name:\"X\", detail:\"full\")` — concern methods with source code | `rails_get_callbacks(model:\"X\")`",
-          "- `rails_get_helper_methods` | `rails_get_service_pattern` | `rails_get_job_pattern`",
-          "- `rails_get_env` | `rails_get_partial_interface(path:\"shared/_form\")` | `rails_get_turbo_map`",
-          "- `rails_get_config` | `rails_get_gems` | `rails_get_conventions` | `rails_security_scan`",
-          "- `rails_search_code(pattern:\"method\", match_type:\"trace\")` — **trace mode**: definition + class context + source + siblings + callers + test coverage in one call",
-          "- `rails_get_edit_context(file:\"path\", near:\"keyword\")` — surgical edit helper with line numbers",
-          ""
-        ]
+      def render_mcp_guide
+        render_tools_guide
       end
 
       def render_conventions
@@ -267,18 +231,8 @@ module RailsAiContext
           "- Follow existing patterns and conventions",
           "- Match existing code style",
           "- Run tests after changes",
-          "- After editing, ALWAYS use `rails_validate(files:[...])` — do NOT use separate ruby -c / erb / node -c calls",
           "- Do NOT re-read files to verify edits — trust your Edit, validate syntax only",
           "- Stimulus controllers auto-register — no manual import in controllers/index.js needed",
-          "",
-          "## MCP-First Rule — Do NOT Bypass",
-          "- Do NOT read db/schema.rb — use `rails_get_schema`",
-          "- Do NOT read config/routes.rb for reference — use `rails_get_routes`",
-          "- Do NOT read model files for associations/scopes — use `rails_get_model_details`",
-          "- Do NOT use Grep to search code — use `rails_search_code`",
-          "- Do NOT launch Explore agents for context — use `rails_analyze_feature`",
-          "- Do NOT read test files for patterns — use `rails_get_test_info`",
-          "- Read files ONLY when you are about to Edit them",
           ""
         ]
       end

data/lib/rails_ai_context/serializers/context_file_serializer.rb

@@ -3,7 +3,7 @@
 module RailsAiContext
   module Serializers
     # Orchestrates writing context files to disk in various formats.
-    # Supports: CLAUDE.md, AGENTS.md, .windsurfrules, .github/copilot-instructions.md, JSON
+    # Supports: CLAUDE.md, AGENTS.md, .github/copilot-instructions.md, JSON
     # Also generates split rule files for AI tools that support them.
     #
     # Root files (CLAUDE.md, etc.) are wrapped in section markers so user content
@@ -15,7 +15,6 @@ module RailsAiContext
       FORMAT_MAP = {
         claude:    "CLAUDE.md",
         opencode:  "AGENTS.md",
-        windsurf:  ".windsurfrules",
         copilot:   ".github/copilot-instructions.md",
         json:      ".ai-context.json"
       }.freeze
@@ -78,7 +77,6 @@ module RailsAiContext
         when :json     then JsonSerializer.new(context).call
         when :claude   then ClaudeSerializer.new(context).call
         when :opencode then OpencodeSerializer.new(context).call
-        when :windsurf then WindsurfSerializer.new(context).call
         when :copilot  then CopilotSerializer.new(context).call
         else MarkdownSerializer.new(context).call
         end
@@ -136,12 +134,6 @@ module RailsAiContext
           skipped.concat(result[:skipped])
         end
 
-        if formats.include?(:windsurf)
-          result = WindsurfRulesSerializer.new(context).call(output_dir)
-          written.concat(result[:written])
-          skipped.concat(result[:skipped])
-        end
-
         if formats.include?(:opencode)
           result = OpencodeRulesSerializer.new(context).call(output_dir)
           written.concat(result[:written])

data/lib/rails_ai_context/serializers/copilot_instructions_serializer.rb

@@ -7,6 +7,7 @@ module RailsAiContext
     class CopilotInstructionsSerializer
       include StackOverviewHelper
       include DesignSystemHelper
+      include ToolGuideHelper
 
       attr_reader :context
 
@@ -213,52 +214,17 @@ module RailsAiContext
         lines.join("\n")
       end
 
-      def render_mcp_tools_instructions # rubocop:disable Metrics/MethodLength
+      def render_mcp_tools_instructions
         lines = [
           "---",
           "applyTo: \"**/*\"",
+          "excludeAgent: \"code-review\"",
           "---",
-          "",
-          "# 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.",
-          "Start with `detail:\"summary\"`, then drill into specifics.",
-          "",
-          "## Mandatory Workflow",
-          "1. Gathering context → use MCP tools (NOT file reads, NOT grep)",
-          "2. Reading files → ONLY files you will edit",
-          "3. After editing → `rails_validate(files:[...])` every time, no exceptions",
-          "",
-          "## Do NOT Bypass",
-          "| 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 | `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