rails-ai-context 4.1.0 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af24e6340b8328b0526c9f030d60b495f4cb1e7130b7f16cadd039e2b9912aab
-  data.tar.gz: e74d337f614f853fec1bacaff748bea4b212ed96034c22b5fd3d75326da6fc13
+  metadata.gz: f82bdd4a192f2776214a228f36e54c62cc6e5e19ac5351d997ade9e5bbdd1667
+  data.tar.gz: 303476c0cf9c43ed4eb4f10df5cdf89c7dba0e5b8858d86a90b984c7cd5ffd0e
 SHA512:
-  metadata.gz: 9e8d9261310e038cce1cc20ba21d81d203eec2d813dcf318aa3f2071da646a67dc11fd812671a0d982d6d0d234ed84c2079144be3b62863b311e09d0b12181f9
-  data.tar.gz: 3f6001ba2d788b76e4a6e7b576a9447e7eed91df1a0b689dba679a3c6fbd876db1278e7ebd70637b35bedb01e2e77b1546cf3b96d8c5d37536f1f053fd35f9d3
+  metadata.gz: aacc3fad8dbbced828ff47eece6d37db6baefaf92b5e2ad1fa4a55d18fa720857d284aba325742985dde0e8e83420f3bb45b8cccf6be6e37d8a9b4973f96365a
+  data.tar.gz: 8c860fedacf47a88253f732a74298f6e7a0a878631d09d090aff3f017703b930bc4add8909bf33407c4165121e942d15c3abce6befc88ccc9e08b0cb09a9e0bb

data/CHANGELOG.md

@@ -5,6 +5,18 @@ 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).
 
+## [4.2.0] — 2026-03-26
+
+### Added
+- New `rails_search_docs` tool: bundled topic index with weighted keyword search, on-demand GitHub fetch for Rails documentation
+- New `rails_query` tool: safe read-only SQL queries with defense-in-depth (regex pre-filter + SET TRANSACTION READ ONLY + configurable timeout + row limit + column redaction)
+- New `rails_read_logs` tool: reverse file tail with level filtering (debug/info/warn/error/fatal) and sensitive data redaction
+- New config options: `query_timeout` (default timeout for SQL queries), `query_row_limit` (max rows returned), `query_redacted_columns` (columns to mask in query results), `allow_query_in_production` (safety gate, default false), `log_lines` (default number of log lines to read)
+
+### Changed
+- Tool count: 30 → 33
+- Test count: 893 → 983
+
 ## [4.1.0] — 2026-03-29
 
 ### Added

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/` — 33 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, components, accessibility, performance, frontend_frameworks)
-- `lib/rails_ai_context/tools/` — 30 MCP tools using the official mcp SDK
+- `lib/rails_ai_context/tools/` — 33 MCP tools using the official mcp SDK
 - `lib/rails_ai_context/cli/` — CLI tool runner (`tool_runner.rb`) — executes MCP tools from rake/Thor
 - `lib/rails_ai_context/serializers/` — Output formatters (claude, claude_rules, opencode, opencode_rules, cursor_rules, copilot, copilot_instructions, rules, markdown, JSON, context_file_serializer, test_command_detection, tool_guide_helper, design_system_helper, stack_overview_helper)
 - `lib/rails_ai_context/resources.rb` — MCP resources (static data AI clients read directly)
@@ -40,12 +40,12 @@ structure to AI assistants via the Model Context Protocol (MCP).
 13. **Per-tool split rules** — `.claude/rules/`, `.cursor/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 30 built-in tools
+16. **custom_tools API** — `config.custom_tools` array lets users register additional MCP::Tool subclasses alongside the 33 built-in tools
 17. **Design system extraction** — view templates analyzed for canonical examples, color palette, typography, responsive patterns, interactive states, dark mode
 18. **skip_tools API** — `config.skip_tools` array lets users exclude specific built-in tools (e.g. `%w[rails_security_scan]`)
 19. **Security scanning** — optional Brakeman integration via `rails_security_scan` tool (graceful degradation if not installed)
 20. **tool_mode config** — `:mcp` (default, MCP primary + CLI fallback) or `:cli` (CLI only, no MCP server needed). Selected during install.
-21. **CLI tool access** — all 30 MCP tools callable from terminal: `rails ai:tool[schema]`, `rails-ai-context tool schema`. Tool name resolution: `schema` → `get_schema` → `rails_get_schema`.
+21. **CLI tool access** — all 33 MCP tools callable from terminal: `rails ai:tool[schema]`, `rails-ai-context tool schema`. Tool name resolution: `schema` → `get_schema` → `rails_get_schema`.
 22. **Shared ToolGuideHelper** — serializers use a shared module for tool reference sections, rendering MCP or CLI syntax based on `tool_mode`
 23. **Component catalog** — ViewComponent/Phlex introspection: props, slots, previews, sidecar assets, usage examples via `rails_get_component_catalog`
 24. **Accessibility scanning** — ARIA attributes, semantic HTML, screen reader text, alt text, landmark roles, accessibility score via AccessibilityIntrospector
@@ -53,11 +53,14 @@ structure to AI assistants via the Model Context Protocol (MCP).
 26. **Migration advisor** — migration code generation with duplicate/nonexistent column warnings, reversibility flags, table name normalization via `rails_migration_advisor`
 27. **Frontend framework detection** — auto-detects React/Vue/Svelte/Angular from package.json, Vite/Shakapacker/Webpacker config, TypeScript setup, monorepo layout, package manager via `rails_get_frontend_stack`
 28. **Install generator idempotency** — re-install preserves existing config, only adds new sections, updates ai_tools/tool_mode selections, prompts per-tool file cleanup for removed tools
+29. **Docs search** — bundled topic index with weighted keyword search, on-demand GitHub fetch
+30. **Safe SQL queries** — defense-in-depth: regex pre-filter + SET TRANSACTION READ ONLY + timeout
+31. **Log reading** — reverse file tail with level filtering and sensitive data redaction
 
 ## Testing
 
 ```bash
-bundle exec rspec           # Run specs (893 examples)
+bundle exec rspec           # Run specs (983 examples)
 bundle exec rubocop         # Lint
 ```
 

data/CONTRIBUTING.md

@@ -20,7 +20,7 @@ The test suite uses [Combustion](https://github.com/pat/combustion) to boot a mi
 lib/rails_ai_context/
 ├── cli/               # CLI tool runner (tool_runner.rb) — executes MCP tools from rake/Thor
 ├── introspectors/     # 33 introspectors (schema, models, routes, etc.)
-├── tools/             # 30 MCP tools with detail levels and pagination
+├── tools/             # 33 MCP tools with detail levels and pagination
 ├── serializers/       # Per-assistant formatters + shared ToolGuideHelper
 ├── server.rb          # MCP server setup (stdio + HTTP)
 ├── live_reload.rb     # MCP live reload (file watcher + cache invalidation)

data/README.md

@@ -3,20 +3,24 @@
 ### Your AI is guessing. This gem makes it know.
 
 [![Gem Version](https://img.shields.io/gem/v/rails-ai-context?color=brightgreen)](https://rubygems.org/gems/rails-ai-context)
-[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-green)](https://registry.modelcontextprotocol.io)
+[![Downloads](https://img.shields.io/gem/dt/rails-ai-context?color=blue)](https://rubygems.org/gems/rails-ai-context)
 [![CI](https://github.com/crisnahine/rails-ai-context/actions/workflows/ci.yml/badge.svg)](https://github.com/crisnahine/rails-ai-context/actions)
+[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-green)](https://registry.modelcontextprotocol.io)
+[![Ruby](https://img.shields.io/badge/Ruby-3.2%20%7C%203.3%20%7C%203.4-red)](https://github.com/crisnahine/rails-ai-context)
+[![Rails](https://img.shields.io/badge/Rails-7.1%20%7C%207.2%20%7C%208.0-red)](https://github.com/crisnahine/rails-ai-context)
+[![Tests](https://img.shields.io/badge/Tests-983%20passing-brightgreen)](https://github.com/crisnahine/rails-ai-context/actions)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 **Works with:** Claude Code • Cursor • GitHub Copilot • OpenCode • Any terminal
 
-> Built by a Rails developer with 10+ years of production experience. AI assisted — the same way it assists me shipping features at work. I designed the architecture, made every decision, reviewed every line, and wrote 893 tests. This gem exists because I understand Rails deeply enough to know exactly what AI agents get wrong and what context they need to get it right.
+> Built by a Rails developer with 10+ years of production experience. AI assisted — the same way it assists me shipping features at work. I designed the architecture, made every decision, reviewed every line, and wrote 983 tests. This gem exists because I understand Rails deeply enough to know exactly what AI agents get wrong and what context they need to get it right.
 
 ```bash
 gem "rails-ai-context", group: :development
 rails generate rails_ai_context:install
 ```
 
-That's it. Your AI now has 30 tools that understand your entire Rails app — via MCP server or CLI. Zero config.
+That's it. Your AI now has 33 tools that understand your entire Rails app — via MCP server or CLI. Zero config.
 
 > **[Full Guide →](docs/GUIDE.md)** — every command, every parameter, every configuration option.
 
@@ -46,7 +50,7 @@ rails 'ai:tool[schema]' table=users
 rails 'ai:tool[analyze_feature]' feature=billing
 ```
 
-Same 30 tools. Same output. AI agents run these as shell commands. **Works in any terminal, any AI tool, any workflow.** No MCP client required.
+Same 33 tools. Same output. AI agents run these as shell commands. **Works in any terminal, any AI tool, any workflow.** No MCP client required.
 
 ---
 
@@ -170,7 +174,7 @@ Tested on a real Rails 8 app (5 models, 19 controllers, 95 routes):
 
 ---
 
-## 30 Tools
+## 33 Tools
 
 Every tool is **read-only** and returns structured, token-efficient data.
 
@@ -216,6 +220,10 @@ Every tool is **read-only** and returns structured, token-efficient data.
 | `migration_advisor` | `rails_migration_advisor` | `rails 'ai:tool[migration_advisor]'` | Migration code generation with reversibility + affected models |
 | **Frontend** | | | |
 | `get_frontend_stack` | `rails_get_frontend_stack` | `rails 'ai:tool[frontend_stack]'` | React/Vue/Svelte/Angular, Inertia, TypeScript, package manager |
+| **Data & Debugging** | | | |
+| `search_docs` | `rails_search_docs(topic:"X")` | `rails 'ai:tool[search_docs]'` | Bundled topic index with weighted keyword search, on-demand GitHub fetch |
+| `query` | `rails_query(sql:"X")` | `rails 'ai:tool[query]'` | Safe read-only SQL queries with timeout, row limit, column redaction |
+| `read_logs` | `rails_read_logs(level:"X")` | `rails 'ai:tool[read_logs]'` | Reverse file tail with level filtering and sensitive data redaction |
 
 > **[Full parameter docs →](docs/GUIDE.md)**
 
@@ -238,7 +246,7 @@ Every tool is **read-only** and returns structured, token-efficient data.
          ▼                  ▼              ▼
 ┌──────────────────┐ ┌────────────┐ ┌────────────────────┐
 │  Static Files     │ │  MCP Server │ │  CLI Tools          │
-│  CLAUDE.md        │ │  30 tools   │ │  Same 30 tools      │
+│  CLAUDE.md        │ │  33 tools   │ │  Same 33 tools      │
 │  .cursor/rules/   │ │  stdio/HTTP │ │  No server needed   │
 │  .github/instr... │ │  .mcp.json  │ │  rails 'ai:tool[X]' │
 └──────────────────┘ └────────────┘ └────────────────────┘
@@ -274,7 +282,7 @@ MCP auto-discovery: `.mcp.json` is detected automatically by Claude Code and Cur
 | Command | What it does |
 |---------|-------------|
 | `rails ai:context` | Generate context files for your AI tools |
-| `rails 'ai:tool[NAME]'` | Run any of the 30 tools from the CLI |
+| `rails 'ai:tool[NAME]'` | Run any of the 33 tools from the CLI |
 | `rails ai:tool` | List all available tools with short names |
 | `rails ai:serve` | Start MCP server (stdio) |
 | `rails ai:doctor` | Diagnostics + AI readiness score |
@@ -347,7 +355,7 @@ end
 ```bash
 git clone https://github.com/crisnahine/rails-ai-context.git
 cd rails-ai-context && bundle install
-bundle exec rspec       # 893 examples
+bundle exec rspec       # 983 examples
 bundle exec rubocop     # Lint
 ```
 

data/SECURITY.md

@@ -4,6 +4,7 @@
 
 | Version | Supported          |
 |---------|--------------------|
+| 4.2.x   | :white_check_mark: |
 | 4.1.x   | :white_check_mark: |
 | 4.0.x   | :white_check_mark: |
 | 3.1.x   | :white_check_mark: |
@@ -25,7 +26,7 @@ If you discover a security vulnerability in rails-ai-context, please report it r
 
 ## Security Design
 
-- All 30 MCP tools are **read-only** and never modify your application or database.
+- All 33 MCP tools are **read-only** and never modify your application or database.
 - **Sensitive file blocking** — configurable `sensitive_patterns` blocks access to `.env`, `*.key`, `*.pem`, `credentials.yml.enc` across all search and read tools. Patterns are checked in `rails_search_code`, `rails_get_edit_context`, and all new tools.
 - **Path traversal protection** — all file-reading tools validate paths with `File.realpath()` against `Rails.root` to prevent directory escape.
 - **Command injection prevention** — code search uses `Open3.capture2` with array arguments (never shell strings). The `--` flag separator prevents pattern injection.

data/docs/GUIDE.md

@@ -252,7 +252,7 @@ rails ai:context:claude           # Use this instead (no quoting needed)
 
 ## CLI Tools
 
-All 30 MCP tools can be run directly from the terminal — no MCP server or AI client needed.
+All 33 MCP tools can be run directly from the terminal — no MCP server or AI client needed.
 
 ### Rake
 
@@ -316,7 +316,7 @@ The `tool_mode` is selected during `rails generate rails_ai_context:install`.
 
 ## MCP Tools — Full Reference
 
-All 30 tools are **read-only** and **idempotent** — they never modify your application or database.
+All 33 tools are **read-only** and **idempotent** — they never modify your application or database.
 
 ### rails_get_schema
 
@@ -1117,7 +1117,7 @@ RailsAiContext.configure do |config|
 end
 ```
 
-Both transports are **read-only** — they expose the same 30 tools and never modify your app.
+Both transports are **read-only** — they expose the same 33 tools and never modify your app.
 
 ---
 

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

@@ -436,9 +436,9 @@ module RailsAiContext
         say ""
         say "Commands:", :yellow
         say "  rails ai:context         # Regenerate context files"
-        say "  rails 'ai:tool[schema]'    # Run any of the 30 tools from CLI"
+        say "  rails 'ai:tool[schema]'    # Run any of the 33 tools from CLI"
         if @tool_mode == :mcp
-          say "  rails ai:serve           # Start MCP server (30 live tools)"
+          say "  rails ai:serve           # Start MCP server (33 live tools)"
         end
         say "  rails ai:doctor          # Check AI readiness"
         say "  rails ai:inspect         # Print introspection summary"

data/lib/rails_ai_context/cli/tool_runner.rb

@@ -222,9 +222,23 @@ module RailsAiContext
       # For missing required params: strip empty values so the tool's own guards
       # can return a friendly response (matching MCP behavior).
       # For invalid enums: strip the bad value and let the tool use its default.
+      # For unknown params: raise InvalidArgumentError with closest-match suggestion.
       def validate_kwargs!(kwargs, schema)
         properties = schema[:properties] || {}
         required = (schema[:required] || []).map(&:to_s)
+        known_keys = properties.keys.map(&:to_s)
+
+        # Check for unknown params and raise a helpful error with suggestions.
+        # server_context is always allowed (internal MCP param).
+        unknown = kwargs.keys.map(&:to_s) - known_keys - [ "server_context" ]
+        if unknown.any?
+          msgs = unknown.map do |k|
+            suggestion = Tools::BaseTool.find_closest_match(k, known_keys)
+            suggestion ? "  '#{k}' — did you mean '#{suggestion}='?" : "  '#{k}'"
+          end
+          valid_str = known_keys.any? ? "Valid params: #{known_keys.join(', ')}" : "This tool takes no params."
+          raise InvalidArgumentError, "Unknown param#{unknown.size > 1 ? 's' : ''}:\n#{msgs.join("\n")}\n#{valid_str}"
+        end
 
         # For required params with empty-string values, keep the key but set to nil
         # so the tool's own guards can return friendly "parameter is required" messages

data/lib/rails_ai_context/configuration.rb

@@ -98,6 +98,15 @@ module RailsAiContext
     attr_accessor :frontend_paths         # User-declared frontend dirs (e.g. ["app/frontend", "../web-client"])
     attr_accessor :mobile_paths           # User-declared mobile dirs (e.g. ["../mobile-app"])
 
+    # Database query tool settings (rails_query)
+    attr_accessor :query_timeout              # Statement timeout in seconds (default: 5)
+    attr_accessor :query_row_limit            # Max rows returned (default: 100, hard cap: 1000)
+    attr_accessor :query_redacted_columns     # Column names whose values are redacted in output
+    attr_accessor :allow_query_in_production  # Allow rails_query in production (default: false)
+
+    # Log reading settings (rails_read_logs)
+    attr_accessor :log_lines                  # Default lines to tail (default: 50)
+
     def initialize
       @server_name         = "rails-ai-context"
       @server_version      = RailsAiContext::VERSION
@@ -166,6 +175,16 @@ module RailsAiContext
       @concern_paths            = %w[app/models/concerns app/controllers/concerns]
       @frontend_paths           = nil
       @mobile_paths             = nil
+      @query_timeout            = 5
+      @query_row_limit          = 100
+      @query_redacted_columns   = %w[
+        password_digest encrypted_password password_hash
+        reset_password_token confirmation_token unlock_token
+        otp_secret session_data secret_key
+        api_key api_secret access_token refresh_token jti
+      ]
+      @allow_query_in_production = false
+      @log_lines                = 50
     end
 
     def preset=(name)