rails-ai-context 2.0.4 → 3.0.0

data/docs/GUIDE.md

@@ -11,6 +11,7 @@
 - [Context Modes](#context-modes)
 - [Generated Files](#generated-files)
 - [All Commands](#all-commands)
+- [CLI Tools](#cli-tools)
 - [MCP Tools — Full Reference](#mcp-tools--full-reference)
 - [MCP Resources](#mcp-resources)
 - [MCP Server Setup](#mcp-server-setup)
@@ -62,8 +63,10 @@ rails ai:doctor
 
 1. Creates `.mcp.json` in project root (MCP auto-discovery)
 2. Creates `config/initializers/rails_ai_context.rb` with commented defaults
-3. Adds `.ai-context.json` to `.gitignore` (JSON cache — markdown files should be committed)
-4. Generates all context files
+3. Asks which AI tools you use (Claude, Cursor, Copilot, OpenCode)
+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
 
 ---
 
@@ -78,7 +81,6 @@ rails ai:context
 ```
 
 - CLAUDE.md ≤150 lines
-- .windsurfrules ≤5,800 characters
 - copilot-instructions.md ≤500 lines
 - Files contain a project overview + MCP tool reference
 - AI uses MCP tools for detailed data on-demand
@@ -105,9 +107,6 @@ CONTEXT_MODE=full rails ai:context:claude
 # Full dump for Cursor only
 CONTEXT_MODE=full rails ai:context:cursor
 
-# Full dump for Windsurf only (still respects 6K char limit)
-CONTEXT_MODE=full rails ai:context:windsurf
-
 # Full dump for Copilot only
 CONTEXT_MODE=full rails ai:context:copilot
 ```
@@ -156,15 +155,6 @@ end
 | `.cursor/rules/rails-ui-patterns.mdc` | UI patterns and design tokens | `globs: app/views/**/*.erb` — loaded when editing views. |
 | `.cursor/rules/rails-mcp-tools.mdc` | MCP tool reference | `alwaysApply: true` — always available. |
 
-### Windsurf (4 files)
-
-| File | Purpose | Notes |
-|------|---------|-------|
-| `.windsurfrules` | Main context file | Hard-capped at 5,800 chars (Windsurf's 6K limit). Truncated silently if exceeded. |
-| `.windsurf/rules/rails-context.md` | Project overview | New Windsurf rules format. |
-| `.windsurf/rules/rails-ui-patterns.md` | UI patterns and design tokens | Loaded when editing views. |
-| `.windsurf/rules/rails-mcp-tools.md` | MCP tool reference | Compact — respects 6K per-file limit. |
-
 ### GitHub Copilot (6 files)
 
 | File | Purpose | Notes |
@@ -199,14 +189,20 @@ Commit **all files except `.ai-context.json`** (which is gitignored). This gives
 | `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:cursor` | compact | Cursor | .cursor/rules/ |
-| `rails ai:context:windsurf` | compact | Windsurf | .windsurfrules + .windsurf/rules/ |
 | `rails ai:context:copilot` | compact | Copilot | copilot-instructions.md + .github/instructions/ |
 | `rails ai:context:json` | — | JSON | .ai-context.json |
 | `CONTEXT_MODE=full rails ai:context:claude` | full | Claude | Full dump for Claude only |
 | `CONTEXT_MODE=full rails ai:context:cursor` | full | Cursor | Full dump for Cursor only |
-| `CONTEXT_MODE=full rails ai:context:windsurf` | full | Windsurf | Full dump for Windsurf only |
 | `CONTEXT_MODE=full rails ai:context:copilot` | full | Copilot | Full dump for Copilot only |
 
+### CLI tools
+
+| Command | Description |
+|---------|-------------|
+| `rails 'ai:tool[NAME]'` | Run any MCP tool from the CLI (e.g. `rails 'ai:tool[schema]' table=users detail=full`) |
+| `rails ai:tool` | List all available tools with descriptions |
+| `rails 'ai:tool[NAME]' JSON=1` | Run tool with JSON envelope output |
+
 ### MCP server
 
 | Command | Transport | Description |
@@ -232,6 +228,10 @@ rails-ai-context serve --transport http    # Start MCP server (HTTP, port 6029)
 rails-ai-context serve --transport http --port 8080  # Custom port
 rails-ai-context context                   # Generate all context files
 rails-ai-context context --format claude   # Generate Claude files only
+rails-ai-context tool                      # List all available tools
+rails-ai-context tool schema --table users --detail full  # Run a tool
+rails-ai-context tool schema --help        # Per-tool help
+rails-ai-context tool schema --json        # JSON envelope output
 rails-ai-context doctor                    # Run diagnostics
 rails-ai-context watch                     # Watch for changes
 rails-ai-context inspect                   # Print introspection JSON
@@ -250,6 +250,70 @@ rails ai:context:claude           # Use this instead (no quoting needed)
 
 ---
 
+## CLI Tools
+
+All 25 MCP tools can be run directly from the terminal — no MCP server or AI client needed.
+
+### Rake
+
+```bash
+# Run a tool with arguments
+rails 'ai:tool[schema]' table=users detail=full
+
+# List all available tools
+rails ai:tool
+
+# JSON envelope output
+rails 'ai:tool[schema]' table=users JSON=1
+```
+
+### Thor CLI
+
+```bash
+# Run a tool with arguments
+rails-ai-context tool schema --table users --detail full
+
+# List all tools
+rails-ai-context tool
+
+# Per-tool help (auto-generated from input_schema)
+rails-ai-context tool schema --help
+
+# JSON output
+rails-ai-context tool schema --table users --json
+```
+
+### Tool name resolution
+
+Short names are resolved automatically:
+
+| You type | Resolves to |
+|----------|-------------|
+| `schema` | `rails_get_schema` |
+| `get_schema` | `rails_get_schema` |
+| `rails_get_schema` | `rails_get_schema` |
+| `search_code` | `rails_search_code` |
+| `analyze_feature` | `rails_analyze_feature` |
+
+### tool_mode configuration
+
+The `tool_mode` config controls how tool references appear in generated context files:
+
+```ruby
+RailsAiContext.configure do |config|
+  # :mcp (default) — MCP primary, CLI as fallback
+  # :cli — CLI only, no MCP server needed
+  config.tool_mode = :mcp
+end
+```
+
+- **`:mcp`** — context files show MCP tool syntax (e.g. `rails_get_schema(table: "users")`). CLI tools still available as fallback.
+- **`:cli`** — context files show CLI syntax (e.g. `rails 'ai:tool[schema]' table=users`). No MCP server required.
+
+The `tool_mode` is selected during `rails generate rails_ai_context:install`.
+
+---
+
 ## MCP Tools — Full Reference
 
 All 25 tools are **read-only** and **idempotent** — they never modify your application or database.
@@ -1083,6 +1147,9 @@ RailsAiContext.configure do |config|
 
   # --- MCP tools ---
 
+  # Tool mode: :mcp (MCP primary + CLI fallback) or :cli (CLI only)
+  config.tool_mode = :mcp
+
   # Max response size for tool results (safety net)
   config.max_tool_response_chars = 200_000
 
@@ -1183,7 +1250,8 @@ end
 | `cache_ttl` | Integer | `60` | Cache TTL in seconds for introspection results |
 | `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]`) |
-| `ai_tools` | Array | `nil` (all) | AI tools to generate context for: `%i[claude cursor copilot windsurf opencode]`. Selected during install. |
+| `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. |
 | `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 |
@@ -1196,7 +1264,7 @@ end
 | `live_reload_debounce` | Float | `1.5` | Debounce interval in seconds for live reload |
 | `server_name` | String | `"rails-ai-context"` | MCP server name |
 | `server_version` | String | gem version | MCP server version |
-| `generate_root_files` | Boolean | `true` | Generate root files (CLAUDE.md, .windsurfrules, etc.) — set `false` for split rules only |
+| `generate_root_files` | Boolean | `true` | Generate root files (CLAUDE.md, etc.) — set `false` for split rules only |
 | `max_file_size` | Integer | `5_000_000` | Per-file read limit for tools (5MB) |
 | `max_test_file_size` | Integer | `1_000_000` | Test file read limit (1MB) |
 | `max_schema_file_size` | Integer | `10_000_000` | schema.rb / structure.sql parse limit (10MB) |
@@ -1214,11 +1282,11 @@ end
 
 ### Root file generation
 
-By default, `rails ai:context` generates root files (CLAUDE.md, AGENTS.md, .windsurfrules, etc.) alongside split rules.
+By default, `rails ai:context` generates root files (CLAUDE.md, AGENTS.md, etc.) alongside split rules.
 
 **Section markers:** Generated content is wrapped in `<!-- BEGIN rails-ai-context -->` / `<!-- END rails-ai-context -->` markers. If you add custom notes above or below the markers, they will be preserved when you re-run `rails ai:context`.
 
-**Skip root files:** If you prefer to maintain root files yourself and only want split rules (`.claude/rules/`, `.cursor/rules/`, `.windsurf/rules/`, `.github/instructions/`):
+**Skip root files:** If you prefer to maintain root files yourself and only want split rules (`.claude/rules/`, `.cursor/rules/`, `.github/instructions/`):
 
 ```ruby
 RailsAiContext.configure do |config|
@@ -1345,16 +1413,6 @@ OpenCode uses **per-directory lazy-loading**: when the agent reads a file, it wa
 
 **MCP tools:** Available via `opencode.json` config above.
 
-### Windsurf
-
-**Context files loaded:**
-- `.windsurfrules` — read at conversation start (≤6,000 chars, silently truncated if exceeded)
-- `.windsurf/rules/*.md` — new rules format
-
-**Limits:**
-- 6,000 characters per rule file
-- 12,000 characters total (global + workspace combined)
-
 ### GitHub Copilot
 
 **Context files loaded:**

data/exe/rails-ai-context

@@ -5,6 +5,42 @@ require "thor"
 
 module RailsAiContext
   class CLI < Thor
+    # Let Thor pass unknown options through to ToolRunner for the tool command
+    stop_on_unknown_option! :tool
+
+    desc "tool [NAME]", "Run an MCP tool (25 available). Use --list to see all."
+    option :json, type: :boolean, default: false, desc: "Output as JSON envelope"
+    option :list, type: :boolean, default: false, desc: "List available tools"
+    def tool(name = nil, *args)
+      if options[:list] || name.nil?
+        boot_rails!
+        require "rails_ai_context"
+        puts RailsAiContext::CLI::ToolRunner.tool_list
+        return
+      end
+
+      boot_rails!
+      require "rails_ai_context"
+
+      if args.include?("--help") || args.include?("-h")
+        tool_class = RailsAiContext::CLI::ToolRunner.new(name, []).tool_class
+        puts RailsAiContext::CLI::ToolRunner.tool_help(tool_class)
+        return
+      end
+
+      runner = RailsAiContext::CLI::ToolRunner.new(name, args, json_mode: options[:json])
+      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 "serve", "Start MCP server (stdio transport)"
     option :transport, type: :string, default: "stdio", desc: "Transport: stdio or http"
     option :port, type: :numeric, default: 6029, desc: "HTTP port (only for http transport)"
@@ -21,7 +57,7 @@ module RailsAiContext
     end
 
     desc "context", "Generate AI context files"
-    option :format, type: :string, default: "all", desc: "Format: claude, cursor, windsurf, copilot, json, all"
+    option :format, type: :string, default: "all", desc: "Format: claude, cursor, copilot, json, all"
     def context
       boot_rails!
       require "rails_ai_context"

data/lib/generators/rails_ai_context/install/install_generator.rb

@@ -13,8 +13,7 @@ module RailsAiContext
         "1" => { key: :claude,   name: "Claude Code",     files: "CLAUDE.md + .claude/rules/",                        format: :claude },
         "2" => { key: :cursor,   name: "Cursor",          files: ".cursor/rules/",                                     format: :cursor },
         "3" => { key: :copilot,  name: "GitHub Copilot",  files: ".github/copilot-instructions.md + .github/instructions/", format: :copilot },
-        "4" => { key: :windsurf, name: "Windsurf",        files: ".windsurfrules + .windsurf/rules/",                  format: :windsurf },
-        "5" => { key: :opencode, name: "OpenCode",        files: "AGENTS.md",                                          format: :opencode }
+        "4" => { key: :opencode, name: "OpenCode",        files: "AGENTS.md",                                          format: :opencode }
       }.freeze
 
       def select_ai_tools
@@ -46,7 +45,31 @@ module RailsAiContext
         say "Selected: #{selected_names.join(', ')}", :green
       end
 
+      def select_tool_mode
+        say ""
+        say "Do you also want MCP server support?", :yellow
+        say ""
+        say "  1. Yes — MCP primary + CLI fallback (generates .mcp.json)"
+        say "  2. No  — CLI only (no server needed)"
+        say ""
+
+        input = ask("Enter number (default: 1):").strip
+
+        @tool_mode = case input
+        when "2" then :cli
+        else :mcp
+        end
+
+        mode_label = @tool_mode == :mcp ? "MCP + CLI fallback" : "CLI only"
+        say "Selected: #{mode_label}", :green
+      end
+
       def create_mcp_config
+        # Skip .mcp.json for CLI-only mode
+        if @tool_mode == :cli
+          say "Skipped .mcp.json (CLI-only mode)", :yellow
+          return
+        end
         mcp_path = Rails.root.join(".mcp.json")
         server_entry = {
           "command" => "bundle",
@@ -74,32 +97,107 @@ module RailsAiContext
 
       def create_initializer
         tools_line = if @selected_formats.size == AI_TOOLS.size
-          "  # config.ai_tools = %i[claude cursor copilot windsurf opencode]  # default: all"
+          "  # config.ai_tools = %i[claude cursor copilot opencode]  # default: all"
         else
           "  config.ai_tools = %i[#{@selected_formats.join(' ')}]"
         end
 
+        tool_mode_line = if @tool_mode == :cli
+          "  config.tool_mode = :cli    # CLI only (no MCP server needed)"
+        else
+          "  # config.tool_mode = :mcp  # MCP primary + CLI fallback (default)"
+        end
+
         create_file "config/initializers/rails_ai_context.rb", <<~RUBY
           # frozen_string_literal: true
 
           RailsAiContext.configure do |config|
-            # AI tools to generate context files for (selected during install)
+            # ── AI Tools ──────────────────────────────────────────────────────
+            # Which AI tools to generate context files for (selected during install)
             # Run `rails generate rails_ai_context:install` to change selection
           #{tools_line}
 
+            # Tool invocation mode:
+            #   :mcp — MCP primary + CLI fallback (default, requires `rails ai:serve`)
+            #   :cli — CLI only (no MCP server needed, uses `rails 'ai:tool[NAME]'`)
+          #{tool_mode_line}
+
+            # ── Introspection ─────────────────────────────────────────────────
             # Introspector preset:
             #   :full     — all 28 introspectors (default)
-            #   :standard — 13 core introspectors
+            #   :standard — 13 core introspectors (schema, models, routes, jobs, gems,
+            #               conventions, controllers, tests, migrations, stimulus,
+            #               view_templates, design_tokens, config)
             # config.preset = :full
 
+            # Context mode: :compact (default, ≤150 lines) or :full (dumps everything)
+            # config.context_mode = :compact
+
+            # Max lines for CLAUDE.md in compact mode
+            # config.claude_max_lines = 150
+
+            # Whether to generate root files (CLAUDE.md, AGENTS.md, etc.)
+            # Set false to only generate split rules (.claude/rules/, .cursor/rules/, etc.)
+            # config.generate_root_files = true
+
+            # ── Models & Filtering ────────────────────────────────────────────
             # Models to exclude from introspection
             # config.excluded_models += %w[AdminUser InternalThing]
 
-            # Context mode: :compact (default, ≤150 lines) or :full (dumps everything)
-            # config.context_mode = :compact
+            # Controllers to exclude from listings
+            # config.excluded_controllers += %w[Admin::BaseController]
+
+            # Route prefixes to hide with app_only filter
+            # config.excluded_route_prefixes += %w[sidekiq/]
+
+            # ── MCP Server ────────────────────────────────────────────────────
+            # Cache TTL in seconds for introspection data
+            # config.cache_ttl = 60
+
+            # Max characters for any single tool response (safety net)
+            # config.max_tool_response_chars = 200_000
 
             # Live reload: auto-invalidate MCP tool caches on file changes
+            #   :auto — enable if `listen` gem is available (default)
+            #   true  — enable, raise if `listen` gem is missing
+            #   false — disable entirely
             # config.live_reload = :auto
+
+            # Auto-mount HTTP MCP endpoint (for HTTP transport)
+            # config.auto_mount = false
+            # config.http_path = "/mcp"
+            # config.http_port = 6029
+
+            # ── File Size Limits ──────────────────────────────────────────────
+            # Increase for larger projects
+            # config.max_file_size = 5_000_000         # Per-file read (5MB)
+            # config.max_test_file_size = 1_000_000    # Test file read (1MB)
+            # config.max_schema_file_size = 10_000_000 # schema.rb parse (10MB)
+            # config.max_view_total_size = 10_000_000  # Aggregated view content (10MB)
+            # config.max_view_file_size = 1_000_000    # Per-view file (1MB)
+            # config.max_search_results = 200          # Max search results per call
+            # config.max_validate_files = 50           # Max files per validate call
+
+            # ── Extensibility ─────────────────────────────────────────────────
+            # Register additional MCP tool classes alongside the 25 built-in tools
+            # config.custom_tools = [MyApp::CustomTool]
+
+            # Exclude specific built-in tools by name
+            # config.skip_tools = %w[rails_security_scan]
+
+            # ── Security ──────────────────────────────────────────────────────
+            # Paths excluded from code search
+            # config.excluded_paths += %w[vendor/cache]
+
+            # File patterns blocked from search and read tools
+            # config.sensitive_patterns += %w[config/secrets.yml]
+
+            # ── Search ────────────────────────────────────────────────────────
+            # File extensions for fallback search (when ripgrep unavailable)
+            # config.search_extensions = %w[rb js erb yml yaml json ts tsx vue svelte haml slim]
+
+            # Where to look for concern source files
+            # config.concern_paths = %w[app/models/concerns app/controllers/concerns]
           end
         RUBY
 
@@ -160,13 +258,22 @@ module RailsAiContext
         say ""
         say "Commands:", :yellow
         say "  rails ai:context         # Regenerate context files"
-        say "  rails ai:serve           # Start MCP server (25 live tools)"
+        say "  rails 'ai:tool[schema]'    # Run any of the 25 tools from CLI"
+        if @tool_mode == :mcp
+          say "  rails ai:serve           # Start MCP server (25 live tools)"
+        end
         say "  rails ai:doctor          # Check AI readiness"
         say "  rails ai:inspect         # Print introspection summary"
         say ""
-        say "MCP auto-discovery:", :yellow
-        say "  .mcp.json is auto-detected by Claude Code and Cursor."
-        say "  No manual config needed — just open your project."
+        if @tool_mode == :mcp
+          say "MCP auto-discovery:", :yellow
+          say "  .mcp.json is auto-detected by Claude Code and Cursor."
+          say "  No manual config needed — just open your project."
+        else
+          say "CLI tools:", :yellow
+          say "  AI agents can run `rails 'ai:tool[schema]' table=users` directly."
+          say "  No MCP server needed — tools work from the terminal."
+        end
         say ""
         say "To add more AI tools later:", :yellow
         say "  rails ai:context:cursor   # Generate for Cursor"