rails-ai-context 0.15.10 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f813e725bf1bab273e3d3df71726c49dcd9a71a0e81786a2ec18553c77c668e8
-  data.tar.gz: 2c9e3adb0799f2d2e1dd4c0fbc6c9df938b2cf131914d53e2ccb72f7c689ed99
+  metadata.gz: 436104e565f41ae5d82ff35810543c142c82174f277eef8a7f6b046de6437bc4
+  data.tar.gz: d3951676a8aef432734bda1d6fb97004e89c009d11bc1fe5c3b35d6a6b85a7e3
 SHA512:
-  metadata.gz: 34f13e96f64c92298ba8c2491ecf1f43375cf0885a9673b8df29bbb4eff7017100fe81eefc8788ecff1ce07e844504b938d43715be0711558eb0faa2203bde76
-  data.tar.gz: ad1fce5a33276f64cfc68b1cb236b3bc19e733127bd29d587faba52537c5df0784a17700a640fe35cedb3429736976737c0c3d3f4c5284b44278e226b0fb33cf
+  metadata.gz: 58982aca74fc74ebbb5cfd410a3b680396fad54f9552931258644ee8d98f27f64fa53e0246692ffb4a4aeaa98b6f8e055195fa3d94d009cc0b48834f81eaee5c
+  data.tar.gz: 0d9220605f100fb14c045cb294071009116ad018ca4221a599e4805d93ab6e6b0817181e2138253349e57da02257da7566e1843d79b6460757bad238ad030caf

data/CHANGELOG.md

@@ -5,6 +5,19 @@ 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).
 
+## [1.0.0] - 2026-03-23
+
+### Added
+
+- **New composite tool: `rails_analyze_feature`** — one call returns schema + models + controllers + routes for a feature area (e.g., `rails_analyze_feature(feature:"authentication")`). Total MCP tools: 14.
+- **Custom tool registration API** — `config.custom_tools << MyCompany::PolicyCheckTool` lets teams extend the MCP server with their own tools.
+- **Structured error responses with fuzzy suggestions** — `not_found_response` helper in BaseTool with "Did you mean?" fuzzy matching (substring + prefix) and `recovery_action` hints. Applied to schema, models, controllers, and stimulus lookups. AI agents self-correct on first retry.
+- **Cache keys on paginated responses** — every paginated response includes `cache_key` from fingerprint so agents detect stale data between page fetches. Applied to schema, models, controllers, and stimulus pagination.
+
+### Changed
+
+- **LLM-optimized tool descriptions (all 14 tools)** — every description now follows "what it does / Use when: / key params" format so AI agents pick the right tool on first try.
+
 ## [0.15.10] - 2026-03-23
 
 ### Changed

data/CLAUDE.md

@@ -9,7 +9,7 @@ structure to AI assistants via the Model Context Protocol (MCP).
 - `lib/rails_ai_context/configuration.rb` — User-facing config with presets (:standard, :full)
 - `lib/rails_ai_context/introspector.rb` — Orchestrates sub-introspectors
 - `lib/rails_ai_context/introspectors/` — 29 introspectors (schema, models, routes, jobs, gems, conventions, stimulus, database_stats, controllers, views, view_templates, design_tokens, turbo, i18n, config, active_storage, action_text, auth, api, tests, rake_tasks, assets, devops, action_mailbox, migrations, seeds, middleware, engines, multi_database)
-- `lib/rails_ai_context/tools/` — 13 MCP tools using the official mcp SDK
+- `lib/rails_ai_context/tools/` — 14 MCP tools using the official mcp SDK
 - `lib/rails_ai_context/serializers/` — Output formatters (claude, claude_rules, opencode, opencode_rules, cursor_rules, windsurf, windsurf_rules, copilot, copilot_instructions, rules, markdown, JSON, context_file_serializer, test_command_detection)
 - `lib/rails_ai_context/resources.rb` — MCP resources (static data AI clients read directly)
 - `lib/rails_ai_context/server.rb` — MCP server configuration (stdio + HTTP transports)
@@ -39,11 +39,12 @@ structure to AI assistants via the Model Context Protocol (MCP).
 13. **Per-tool split rules** — `.claude/rules/`, `.cursor/rules/`, `.windsurf/rules/`, `.github/instructions/`
 14. **Section markers** — root file content wrapped in `<!-- BEGIN/END rails-ai-context -->` to preserve user content
 15. **generate_root_files toggle** — when false, skip root files (CLAUDE.md, etc.), only generate split rules
+16. **custom_tools API** — `config.custom_tools` array lets users register additional MCP::Tool subclasses alongside the 14 built-in tools
 
 ## Testing
 
 ```bash
-bundle exec rspec           # Run specs (507 examples)
+bundle exec rspec           # Run specs (520 examples)
 bundle exec rubocop         # Lint
 ```
 

data/CONTRIBUTING.md

@@ -19,7 +19,7 @@ The test suite uses [Combustion](https://github.com/pat/combustion) to boot a mi
 ```
 lib/rails_ai_context/
 ├── introspectors/     # 29 introspectors (schema, models, routes, etc.)
-├── tools/             # 13 MCP tools with detail levels and pagination
+├── tools/             # 14 MCP tools with detail levels and pagination
 ├── serializers/       # Per-assistant formatters (claude, opencode, cursor, windsurf, copilot, JSON)
 ├── server.rb          # MCP server setup (stdio + HTTP)
 ├── live_reload.rb     # MCP live reload (file watcher + cache invalidation)

data/README.md

@@ -7,6 +7,8 @@
 [![CI](https://github.com/crisnahine/rails-ai-context/actions/workflows/ci.yml/badge.svg)](https://github.com/crisnahine/rails-ai-context/actions)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
+> Built by a Rails developer with 10 years of production experience. Yes, AI helped write this gem — the same way AI helps me ship features at work. I designed the architecture, made every decision, reviewed every line, and wrote 520 tests. The gem exists because I understand Rails deeply enough to know what AI agents get wrong and what context they need to get it right.
+
 ---
 
 ## The Problem
@@ -60,7 +62,7 @@ Agent: rails_validate(files:["app/models/cook.rb"], level:"rails") → catches c
 |-------|-----------------|---------------|------------|
 | **Static files** (CLAUDE.md, .cursorrules, etc.) | App overview: stack, models, gems, architecture, UI patterns, MCP tool reference | Automatically at session start | ~150 lines, zero tool calls |
 | **Split rules** (.claude/rules/, .cursor/rules/) | Deep reference: full schema with column types, all model associations/scopes, controller listings | Conditionally — only when editing relevant files | Zero when not needed |
-| **Live MCP tools** (13 tools) | Real-time queries: drill into any table, model, controller action, or view on demand. Semantic validation. | On-demand via agent tool calls | ~25-100 lines per call |
+| **Live MCP tools** (14 tools) | Real-time queries: drill into any table, model, controller action, or view on demand. Semantic validation. | On-demand via agent tool calls | ~25-100 lines per call |
 
 **Progressive disclosure:** the agent gets the map for free, reference guides when relevant, and live GPS when building.
 
@@ -70,7 +72,7 @@ Agent: rails_validate(files:["app/models/cook.rb"], level:"rails") → catches c
 
 | Setup | Tokens | What it knows |
 |-------|--------|---------------|
-| **rails-ai-context (full)** | **28,834** | 13 MCP tools + generated docs + split rules |
+| **rails-ai-context (full)** | **28,834** | 14 MCP tools + generated docs + split rules |
 | rails-ai-context CLAUDE.md only | 33,106 | Generated docs + rules, no MCP tools |
 | Normal Claude `/init` | 40,700 | Generic CLAUDE.md only |
 | No rails-ai-context | 45,477 | Nothing — discovers everything from scratch |
@@ -95,9 +97,9 @@ But token savings is the side effect. The real value:
 
 ---
 
-## 13 Live MCP Tools
+## 14 Live MCP Tools
 
-The gem exposes **13 read-only tools** via MCP that AI clients call on-demand:
+The gem exposes **14 read-only tools** via MCP that AI clients call on-demand:
 
 | Tool | What it returns |
 |------|----------------|
@@ -114,6 +116,7 @@ The gem exposes **13 read-only tools** via MCP that AI clients call on-demand:
 | `rails_get_stimulus` | Stimulus controllers — targets, values, actions, outlets |
 | `rails_get_edit_context` | Surgical edit helper — returns code around a match with line numbers |
 | `rails_validate` | Batch syntax validation for Ruby, ERB, and JavaScript files. `level:"rails"` adds semantic checks (partials, route helpers, columns, strong params, callbacks, FK indexes, Stimulus) |
+| `rails_analyze_feature` | End-to-end feature analysis — finds matching models, controllers, routes, and views in one call |
 
 ### Smart Detail Levels
 
@@ -334,6 +337,8 @@ end
 | **Search & Discovery** | | |
 | `search_extensions` | `rb js erb yml yaml json ts tsx vue svelte haml slim` | File extensions for Ruby fallback search |
 | `concern_paths` | `app/models/concerns app/controllers/concerns` | Where to look for concern source files |
+| **Extensibility** | | |
+| `custom_tools` | `[]` | Additional MCP tool classes to register alongside built-in tools |
 </details>
 
 ---
@@ -422,7 +427,7 @@ The gem parses `db/schema.rb` as text when no database is connected. Works in CI
 ```bash
 git clone https://github.com/crisnahine/rails-ai-context.git
 cd rails-ai-context && bundle install
-bundle exec rspec       # 507 examples
+bundle exec rspec       # 520 examples
 bundle exec rubocop     # Lint
 ```
 

data/SECURITY.md

@@ -4,6 +4,7 @@
 
 | Version | Supported          |
 |---------|--------------------|
+| 1.0.x   | :white_check_mark: |
 | 0.15.x  | :white_check_mark: |
 | < 0.15  | :x:                |
 

data/docs/GUIDE.md

@@ -252,7 +252,7 @@ rails ai:context:claude           # Use this instead (no quoting needed)
 
 ## MCP Tools — Full Reference
 
-All 13 tools are **read-only** and **idempotent** — they never modify your application or database.
+All 14 tools are **read-only** and **idempotent** — they never modify your application or database.
 
 ### rails_get_schema
 
@@ -588,6 +588,36 @@ rails_search_code(pattern: "validates", context_lines: 2)
 
 **Security:** Uses `Open3.capture2` with array arguments (no shell injection). Validates file_type. Blocks path traversal. Respects `excluded_paths` and `sensitive_patterns` config.
 
+### rails_analyze_feature
+
+Analyzes a feature end-to-end: finds matching models, controllers, routes, and views in one call.
+
+**Parameters:**
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `feature` | string | **Required.** Feature keyword to search for (e.g. `authentication`, `User`, `payments`, `orders`). Case-insensitive partial match across models, controllers, and routes. |
+
+**Examples:**
+
+```
+rails_analyze_feature(feature: "authentication")
+  → Models, controllers, and routes matching "authentication"
+
+rails_analyze_feature(feature: "User")
+  → User model with schema columns, associations, validations, scopes;
+    UsersController with actions and filters;
+    all user routes with verbs and paths
+
+rails_analyze_feature(feature: "payments")
+  → Cross-cutting view: Payment model + PaymentsController + payment routes
+
+rails_analyze_feature(feature: "orders")
+  → Everything related to orders across all layers
+```
+
+**Returns:** Markdown with sections for Models (with table, columns, indexes, FKs, associations, validations, scopes), Controllers (with actions and filters), and Routes (with verbs, paths, and route names). Each section shows match counts.
+
 ### Detail Level Summary
 
 All tools that support `detail` use these three levels. Default limits vary by tool — schema defaults shown below:
@@ -716,7 +746,7 @@ RailsAiContext.configure do |config|
 end
 ```
 
-Both transports are **read-only** — they expose the same 13 tools and never modify your app.
+Both transports are **read-only** — they expose the same 14 tools and never modify your app.
 
 ---
 
@@ -752,6 +782,9 @@ RailsAiContext.configure do |config|
   # Cache TTL for introspection results (seconds)
   config.cache_ttl = 30
 
+  # Additional MCP tool classes to register alongside built-in tools
+  # config.custom_tools = [MyApp::Tools::CustomTool]
+
   # --- Exclusions ---
 
   # Models to skip during introspection
@@ -838,6 +871,7 @@ end
 | `claude_max_lines` | Integer | `150` | Max lines for CLAUDE.md in compact mode |
 | `max_tool_response_chars` | Integer | `120_000` | Safety cap for MCP tool responses |
 | `cache_ttl` | Integer | `30` | Cache TTL in seconds for introspection results |
+| `custom_tools` | Array | `[]` | Additional MCP tool classes to register alongside built-in tools |
 | `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 |

data/lib/rails_ai_context/configuration.rb

@@ -69,6 +69,9 @@ module RailsAiContext
     attr_accessor :max_search_results     # Max search results per call (default: 100)
     attr_accessor :max_validate_files     # Max files per validate call (default: 20)
 
+    # Additional MCP tool classes to register alongside built-in tools
+    attr_accessor :custom_tools
+
     # 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/)
@@ -140,6 +143,7 @@ module RailsAiContext
         ActiveRecord::Migration::CheckPending ActionDispatch::HostAuthorization
         Rack::MethodOverride ActionDispatch::Session::AbstractSecureStore
       ]
+      @custom_tools             = []
       @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/server.rb

@@ -21,7 +21,8 @@ module RailsAiContext
       Tools::GetView,
       Tools::GetStimulus,
       Tools::GetEditContext,
-      Tools::Validate
+      Tools::Validate,
+      Tools::AnalyzeFeature
     ].freeze
 
     def initialize(app, transport: :stdio)
@@ -36,7 +37,7 @@ module RailsAiContext
       server = MCP::Server.new(
         name: config.server_name,
         version: config.server_version,
-        tools: TOOLS
+        tools: TOOLS + config.custom_tools
       )
 
       Resources.register(server)

data/lib/rails_ai_context/tools/analyze_feature.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  module Tools
+    class AnalyzeFeature < BaseTool
+      tool_name "rails_analyze_feature"
+      description "Analyze a feature end-to-end: finds matching models, controllers, routes, and views in one call. " \
+        "Use when: exploring an unfamiliar feature, onboarding to a codebase area, or tracing a feature across layers. " \
+        "Pass feature:\"authentication\" or feature:\"User\" for broad cross-cutting discovery."
+
+      input_schema(
+        properties: {
+          feature: {
+            type: "string",
+            description: "Feature keyword to search for (e.g. 'authentication', 'User', 'payments', 'orders'). Case-insensitive partial match across models, controllers, and routes."
+          }
+        },
+        required: [ "feature" ]
+      )
+
+      annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false)
+
+      def self.call(feature:, server_context: nil)
+        ctx = cached_context
+        pattern = feature.downcase
+        lines = [ "# Feature Analysis: #{feature}", "" ]
+
+        # --- Models ---
+        models = ctx[:models] || {}
+        matched_models = models.select { |name, data| !data[:error] && name.downcase.include?(pattern) }
+
+        if matched_models.any?
+          lines << "## Models (#{matched_models.size} matched)"
+          matched_models.sort.each do |name, data|
+            lines << ""
+            lines << "### #{name}"
+            lines << "**Table:** `#{data[:table_name]}`" if data[:table_name]
+
+            # Schema columns from schema introspection
+            table_name = data[:table_name]
+            if table_name && (schema = ctx[:schema]) && (tables = schema[:tables])
+              table_data = tables[table_name]
+              if table_data && table_data[:columns]&.any?
+                cols = table_data[:columns].reject { |c| %w[id created_at updated_at].include?(c[:name]) }
+                lines << "**Columns:** #{cols.map { |c| "#{c[:name]}:#{c[:type]}" }.join(', ')}" if cols.any?
+                if table_data[:indexes]&.any?
+                  lines << "**Indexes:** #{table_data[:indexes].map { |i| "#{i[:columns].join(',')}#{i[:unique] ? ' (unique)' : ''}" }.join('; ')}"
+                end
+                if table_data[:foreign_keys]&.any?
+                  lines << "**FKs:** #{table_data[:foreign_keys].map { |fk| "#{fk[:column]} -> #{fk[:to_table]}" }.join(', ')}"
+                end
+              end
+            end
+
+            if data[:associations]&.any?
+              lines << "**Associations:** #{data[:associations].map { |a| "#{a[:type]} :#{a[:name]}" }.join(', ')}"
+            end
+            if data[:validations]&.any?
+              lines << "**Validations:** #{data[:validations].map { |v| "#{v[:kind]} on #{v[:attributes].join(', ')}" }.uniq.join('; ')}"
+            end
+            if data[:scopes]&.any?
+              lines << "**Scopes:** #{data[:scopes].join(', ')}"
+            end
+          end
+        else
+          lines << "## Models" << "_No models matching '#{feature}'._"
+        end
+
+        # --- Controllers ---
+        controllers = (ctx.dig(:controllers, :controllers) || {})
+        matched_controllers = controllers.select { |name, data| !data[:error] && name.downcase.include?(pattern) }
+
+        lines << ""
+        if matched_controllers.any?
+          lines << "## Controllers (#{matched_controllers.size} matched)"
+          matched_controllers.sort.each do |name, info|
+            actions = info[:actions]&.join(", ") || "none"
+            filters = (info[:filters] || []).map { |f| "#{f[:kind]} #{f[:name]}" }.join(", ")
+            lines << "" << "### #{name}"
+            lines << "- **Actions:** #{actions}"
+            lines << "- **Filters:** #{filters}" unless filters.empty?
+          end
+        else
+          lines << "## Controllers" << "_No controllers matching '#{feature}'._"
+        end
+
+        # --- Routes ---
+        by_controller = (ctx.dig(:routes, :by_controller) || {})
+        matched_routes = by_controller.select { |ctrl, _| ctrl.downcase.include?(pattern) }
+
+        lines << ""
+        if matched_routes.any?
+          route_count = matched_routes.values.sum(&:size)
+          lines << "## Routes (#{route_count} matched)"
+          matched_routes.sort.each do |ctrl, actions|
+            actions.each do |r|
+              name_part = r[:name] ? " `#{r[:name]}`" : ""
+              lines << "- `#{r[:verb]}` `#{r[:path]}` -> #{ctrl}##{r[:action]}#{name_part}"
+            end
+          end
+        else
+          lines << "## Routes" << "_No routes matching '#{feature}'._"
+        end
+
+        text_response(lines.join("\n"))
+      end
+    end
+  end
+end

data/lib/rails_ai_context/tools/base_tool.rb

@@ -54,6 +54,33 @@ module RailsAiContext
           reset_cache!
         end
 
+        # Structured not-found error with fuzzy suggestion and recovery hint.
+        # Helps AI agents self-correct without retrying blind.
+        def not_found_response(type, name, available, recovery_tool: nil)
+          suggestion = find_closest_match(name, available)
+          lines = [ "#{type} '#{name}' not found." ]
+          lines << "Did you mean '#{suggestion}'?" if suggestion
+          lines << "Available: #{available.first(20).join(', ')}#{"..." if available.size > 20}"
+          lines << "_Recovery: #{recovery_tool}_" if recovery_tool
+          text_response(lines.join("\n"))
+        end
+
+        # Simple fuzzy match: find the closest available name by substring or edit distance
+        def find_closest_match(input, available)
+          return nil if available.empty?
+          downcased = input.downcase
+          # Exact substring match first
+          exact = available.find { |a| a.downcase.include?(downcased) || downcased.include?(a.downcase) }
+          return exact if exact
+          # Prefix match
+          available.find { |a| a.downcase.start_with?(downcased[0..2]) }
+        end
+
+        # Cache key for paginated responses — lets agents detect stale data between pages
+        def cache_key
+          SHARED_CACHE[:fingerprint] || "none"
+        end
+
         # Helper: wrap text in an MCP::Tool::Response with safety-net truncation
         def text_response(text)
           max = RailsAiContext.configuration.max_tool_response_chars

data/lib/rails_ai_context/tools/get_config.rb

@@ -4,7 +4,9 @@ module RailsAiContext
   module Tools
     class GetConfig < BaseTool
       tool_name "rails_get_config"
-      description "Get Rails application configuration including cache store, session store, timezone, middleware stack, and initializers."
+      description "Get Rails app configuration: cache store, session store, timezone, queue adapter, custom middleware, initializers. " \
+        "Use when: configuring caching, checking session/queue setup, or seeing what initializers exist. " \
+        "No parameters needed. Returns only non-default middleware and notable initializers."
 
       input_schema(properties: {})
 

data/lib/rails_ai_context/tools/get_controllers.rb

@@ -4,7 +4,9 @@ module RailsAiContext
   module Tools
     class GetControllers < BaseTool
       tool_name "rails_get_controllers"
-      description "Get controller information including actions, filters, strong params, and concerns. Optionally filter by controller name. Supports detail levels."
+      description "Get controller details: actions, before_action filters, strong params, and parent class. " \
+        "Use when: adding/modifying controller actions, checking what filters apply, or reading action source code. " \
+        "Filter with controller:\"PostsController\", drill into action:\"create\" for source code with line numbers."
 
       input_schema(
         properties: {
@@ -60,8 +62,8 @@ module RailsAiContext
           } || controller
           info = controllers[key]
           unless info
-            available = app_controller_names.any? ? "Available: #{app_controller_names.join(', ')}" : "No controllers discovered."
-            return text_response("Controller '#{controller}' not found. #{available}")
+            return not_found_response("Controller", controller, app_controller_names,
+              recovery_tool: "Call rails_get_controllers(detail:\"summary\") to see all controllers")
           end
           return text_response("Error inspecting #{key}: #{info[:error]}") if info[:error]
 
@@ -86,7 +88,7 @@ module RailsAiContext
           return text_response("No controllers at offset #{offset}. Total: #{total}. Use `offset:0` to start over.")
         end
 
-        pagination_hint = offset + limit < total ? "\n_Showing #{paginated_names.size} of #{total}. Use `offset:#{offset + limit}` for more._" : ""
+        pagination_hint = offset + limit < total ? "\n_Showing #{paginated_names.size} of #{total}. Use `offset:#{offset + limit}` for more. cache_key: #{cache_key}_" : ""
 
         # Listing mode
         case detail

data/lib/rails_ai_context/tools/get_conventions.rb

@@ -4,7 +4,9 @@ module RailsAiContext
   module Tools
     class GetConventions < BaseTool
       tool_name "rails_get_conventions"
-      description "Detect architectural patterns and conventions used in this Rails app. Returns info about architecture style (API-only, Hotwire, GraphQL), design patterns (service objects, STI, polymorphism), directory structure, and config files present."
+      description "Detect app architecture and conventions: API-only vs Hotwire, design patterns, directory layout. " \
+        "Use when: starting work on an unfamiliar codebase, choosing implementation patterns, or checking what frameworks are in use. " \
+        "No parameters needed. Returns architecture style, detected patterns (STI, service objects), and notable config files."
 
       input_schema(properties: {})
 

data/lib/rails_ai_context/tools/get_edit_context.rb

@@ -4,7 +4,9 @@ module RailsAiContext
   module Tools
     class GetEditContext < BaseTool
       tool_name "rails_get_edit_context"
-      description "Get just enough context to make a surgical Edit to a file. Returns the target area with line numbers and surrounding code. Purpose-built to replace Read + Edit workflow with a single call."
+      description "Get targeted code context for surgical edits: returns matching lines with surrounding code and line numbers. " \
+        "Use when: you need to edit a specific method or section without reading the entire file. " \
+        "Requires file:\"app/models/user.rb\" and near:\"def activate\" to locate the code region."
 
       def self.max_file_size
         RailsAiContext.configuration.max_file_size

data/lib/rails_ai_context/tools/get_gems.rb

@@ -4,7 +4,9 @@ module RailsAiContext
   module Tools
     class GetGems < BaseTool
       tool_name "rails_get_gems"
-      description "Analyze the app's Gemfile.lock to identify notable gems, their categories (auth, jobs, frontend, API, database, testing, deploy), and what they mean for the app's architecture."
+      description "Get notable gems from Gemfile.lock grouped by category: auth, jobs, frontend, API, database, testing, deploy. " \
+        "Use when: checking what libraries are available before adding a dependency, or understanding the tech stack. " \
+        "Filter with category:\"auth\" or category:\"database\". Omit for all categories."
 
       input_schema(
         properties: {

data/lib/rails_ai_context/tools/get_model_details.rb

@@ -4,7 +4,9 @@ module RailsAiContext
   module Tools
     class GetModelDetails < BaseTool
       tool_name "rails_get_model_details"
-      description "Get detailed information about a specific ActiveRecord model including associations, validations, scopes, enums, callbacks, and concerns. If no model specified, lists all available models with configurable detail level."
+      description "Get ActiveRecord model details: associations, validations, scopes, enums, callbacks, concerns. " \
+        "Use when: understanding model relationships, adding validations, checking existing scopes/callbacks. " \
+        "Specify model:\"User\" for full detail, or omit for a list. detail:\"full\" shows association lists."
 
       input_schema(
         properties: {
@@ -39,7 +41,10 @@ module RailsAiContext
         if model
           key = models.keys.find { |k| k.downcase == model.downcase } || model
           data = models[key]
-          return text_response("Model '#{model}' not found. Available: #{models.keys.sort.join(', ')}") unless data
+          unless data
+            return not_found_response("Model", model, models.keys.sort,
+              recovery_tool: "Call rails_get_model_details(detail:\"summary\") to see all models")
+          end
           return text_response("Error inspecting #{key}: #{data[:error]}") if data[:error]
           return text_response(format_model(key, data))
         end
@@ -55,7 +60,7 @@ module RailsAiContext
           return text_response("No models at offset #{offset}. Total: #{total}. Use `offset:0` to start over.")
         end
 
-        pagination_hint = offset + limit < total ? "\n_Showing #{paginated.size} of #{total}. Use `offset:#{offset + limit}` for more._" : ""
+        pagination_hint = offset + limit < total ? "\n_Showing #{paginated.size} of #{total}. Use `offset:#{offset + limit}` for more. cache_key: #{cache_key}_" : ""
 
         # Listing mode
         case detail

data/lib/rails_ai_context/tools/get_routes.rb

@@ -4,7 +4,9 @@ module RailsAiContext
   module Tools
     class GetRoutes < BaseTool
       tool_name "rails_get_routes"
-      description "Get all routes for the Rails app, optionally filtered by controller. Shows HTTP verb, path, controller#action, and route name. Supports detail levels and pagination."
+      description "Get routing table: HTTP verbs, paths, controller#action, route names. " \
+        "Use when: building links/redirects, checking available endpoints, verifying route helpers exist. " \
+        "Filter with controller:\"users\", use detail:\"summary\" for counts or detail:\"full\" for route names."
 
       input_schema(
         properties: {

data/lib/rails_ai_context/tools/get_schema.rb

@@ -4,7 +4,9 @@ module RailsAiContext
   module Tools
     class GetSchema < BaseTool
       tool_name "rails_get_schema"
-      description "Get the database schema for the Rails app including tables, columns, indexes, and foreign keys. Optionally filter by table name. Supports detail levels and pagination for large schemas."
+      description "Get database schema: tables, columns, types, indexes, foreign keys. " \
+        "Use when: writing migrations, checking column types/constraints, understanding table relationships. " \
+        "Filter to one table with table:\"users\", control detail with detail:\"summary\"|\"standard\"|\"full\"."
 
       input_schema(
         properties: {
@@ -57,7 +59,10 @@ module RailsAiContext
         if table
           table_key = tables.keys.find { |k| k.downcase == table.downcase } || table
           table_data = tables[table_key]
-          return text_response("Table '#{table}' not found. Available: #{tables.keys.sort.join(', ')}") unless table_data
+          unless table_data
+            return not_found_response("Table", table, tables.keys.sort,
+              recovery_tool: "Call rails_get_schema(detail:\"summary\") to see all tables")
+          end
           output = format == "json" ? table_data.to_json : format_table_markdown(table_key, table_data)
           return text_response(output)
         end
@@ -77,7 +82,10 @@ module RailsAiContext
             idx_count = data[:indexes]&.size || 0
             lines << "- **#{name}** — #{col_count} columns, #{idx_count} indexes"
           end
-          lines << "" << "_Showing #{paginated.size} of #{total}. Use `offset:#{offset + limit}` for more, or `table:\"name\"` for full detail._" if offset + limit < total
+          if offset + limit < total
+            lines << "" << "_Showing #{paginated.size} of #{total}. Use `offset:#{offset + limit}` for more, or `table:\"name\"` for full detail._"
+            lines << "_cache_key: #{cache_key}_"
+          end
           text_response(lines.join("\n"))
 
         when "standard"
@@ -113,7 +121,10 @@ module RailsAiContext
             lines << format_table_markdown(name, tables[name])
             lines << ""
           end
-          lines << "_Showing #{paginated.size} of #{total}. Use `offset:#{offset + limit}` for more._" if offset + limit < total
+          if offset + limit < total
+            lines << "_Showing #{paginated.size} of #{total}. Use `offset:#{offset + limit}` for more._"
+            lines << "_cache_key: #{cache_key}_"
+          end
           text_response(lines.join("\n"))
         else
           # Fallback to full dump (backward compat)

data/lib/rails_ai_context/tools/get_stimulus.rb

@@ -4,7 +4,9 @@ module RailsAiContext
   module Tools
     class GetStimulus < BaseTool
       tool_name "rails_get_stimulus"
-      description "Get Stimulus controller information including targets, values, actions, outlets, and classes. Filter by controller name."
+      description "Get Stimulus controllers: targets, values, actions, outlets, classes. " \
+        "Use when: wiring up data-controller attributes in views, adding targets/values, or checking existing Stimulus behavior. " \
+        "Filter with controller:\"filter-form\" for one controller's full API, or list all with detail:\"summary\"."
 
       input_schema(
         properties: {
@@ -43,7 +45,11 @@ module RailsAiContext
         if controller
           normalized = controller.downcase.tr("-", "_")
           ctrl = all_controllers.find { |c| c[:name]&.downcase&.tr("-", "_") == normalized }
-          return text_response("Controller '#{controller}' not found. Available: #{all_controllers.map { |c| c[:name] }.sort.join(', ')}\n\n_Note: use dashes in HTML (`data-controller=\"my-name\"`) but underscores for lookup (`controller:\"my_name\"`)._") unless ctrl
+          unless ctrl
+            names = all_controllers.map { |c| c[:name] }.sort
+            return not_found_response("Stimulus controller", controller, names,
+              recovery_tool: "Call rails_get_stimulus(detail:\"summary\") to see all controllers. Note: use dashes in HTML, underscores for lookup.")
+          end
           return text_response(format_controller_full(ctrl))
         end
 
@@ -58,7 +64,7 @@ module RailsAiContext
           return text_response("No controllers at offset #{offset_val}. Total: #{total}. Use `offset:0` to start over.")
         end
 
-        pagination_hint = offset_val + limit_val < total ? "\n_Showing #{controllers.size} of #{total}. Use `offset:#{offset_val + limit_val}` for more._" : ""
+        pagination_hint = offset_val + limit_val < total ? "\n_Showing #{controllers.size} of #{total}. Use `offset:#{offset_val + limit_val}` for more. cache_key: #{cache_key}_" : ""
 
         case detail
         when "summary"

data/lib/rails_ai_context/tools/get_test_info.rb

@@ -4,7 +4,9 @@ module RailsAiContext
   module Tools
     class GetTestInfo < BaseTool
       tool_name "rails_get_test_info"
-      description "Get test infrastructure: framework, factories/fixtures with names, CI config, coverage, test file counts, and helper setup. Filter by model or controller to see existing tests."
+      description "Get test infrastructure and existing test files: framework, factories, fixtures, CI config, coverage setup. " \
+        "Use when: writing new tests, checking what factories/fixtures exist, or finding the test file for a model/controller. " \
+        "Use model:\"User\" or controller:\"Cooks\" to see existing tests. detail:\"full\" lists factory and fixture names."
 
       input_schema(
         properties: {

data/lib/rails_ai_context/tools/get_view.rb

@@ -4,7 +4,9 @@ module RailsAiContext
   module Tools
     class GetView < BaseTool
       tool_name "rails_get_view"
-      description "Get view template contents, partials, and Stimulus controller references. Filter by controller or specific path. Saves tokens vs reading raw ERB files."
+      description "Get view templates, partials, and their Stimulus/partial references. " \
+        "Use when: editing ERB views, checking which partials a page renders, or finding Stimulus controller usage. " \
+        "Filter with controller:\"cooks\" for all views, or path:\"cooks/index.html.erb\" for one file's content."
 
       input_schema(
         properties: {

data/lib/rails_ai_context/tools/search_code.rb

@@ -6,7 +6,9 @@ module RailsAiContext
   module Tools
     class SearchCode < BaseTool
       tool_name "rails_search_code"
-      description "Search the Rails codebase for a pattern using ripgrep (rg) or Ruby fallback. Returns matching lines with file paths and line numbers. Useful for finding usages, implementations, and patterns."
+      description "Search the Rails codebase by regex pattern, returning matching lines with file paths and line numbers. " \
+        "Use when: finding where a method is called, locating class definitions, or tracing how a feature is implemented. " \
+        "Requires pattern:\"def activate\". Narrow with path:\"app/models\" and file_type:\"rb\"."
 
       def self.max_results_cap
         RailsAiContext.configuration.max_search_results

data/lib/rails_ai_context/tools/validate.rb

@@ -8,11 +8,9 @@ module RailsAiContext
   module Tools
     class Validate < BaseTool
       tool_name "rails_validate"
-      description "Validate syntax of multiple files at once (Ruby, ERB, JavaScript). " \
-        "Replaces separate ruby -c, erb check, and node -c calls. " \
-        "Use level:\"rails\" for semantic checks: partial existence, route helpers, " \
-        "column references, strong params vs schema, callback method existence, " \
-        "route-action consistency, has_many dependent, FK indexes, Stimulus controllers."
+      description "Validate syntax and semantics of Ruby, ERB, and JavaScript files in a single call. " \
+        "Use when: after editing files, before committing, to catch syntax errors and Rails-specific issues. " \
+        "Pass files:[\"app/models/user.rb\"], use level:\"rails\" for semantic checks (missing partials, bad column refs, orphaned routes)."
 
       def self.max_files
         RailsAiContext.configuration.max_validate_files

data/lib/rails_ai_context/version.rb

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

data/server.json

@@ -2,16 +2,16 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.crisnahine/rails-ai-context",
   "title": "Rails AI Context",
-  "description": "Auto-expose Rails app structure to AI via MCP. Zero config, 13 read-only tools.",
+  "description": "Auto-expose Rails app structure to AI via MCP. Zero config, 14 read-only tools.",
   "repository": {
     "url": "https://github.com/crisnahine/rails-ai-context",
     "source": "github"
   },
-  "version": "0.15.8",
+  "version": "1.0.0",
   "packages": [
     {
       "registryType": "mcpb",
-      "identifier": "https://github.com/crisnahine/rails-ai-context/releases/download/v0.15.8/rails-ai-context-mcp.mcpb",
+      "identifier": "https://github.com/crisnahine/rails-ai-context/releases/download/v1.0.0/rails-ai-context-mcp.mcpb",
       "fileSha256": "dd711a0ad6c4de943ae4da94eaf59a6dc9494b9d57f726e24649ed4e2f156990",
       "transport": {
         "type": "stdio"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-ai-context
 version: !ruby/object:Gem::Version
-  version: 0.15.10
+  version: 1.0.0
 platform: ruby
 authors:
 - crisnahine
@@ -245,6 +245,7 @@ files:
 - lib/rails_ai_context/serializers/windsurf_serializer.rb
 - lib/rails_ai_context/server.rb
 - lib/rails_ai_context/tasks/rails_ai_context.rake
+- lib/rails_ai_context/tools/analyze_feature.rb
 - lib/rails_ai_context/tools/base_tool.rb
 - lib/rails_ai_context/tools/get_config.rb
 - lib/rails_ai_context/tools/get_controllers.rb