rails_vitals 0.5.1 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76e3b231f12c366dba7fbd5cf3e54959922fd0b8e26d6ad865d924de95523887
-  data.tar.gz: 56e6c2d230f2fd852f6aded8773e627bbcac09b155c34e49d6b34c6453c2116a
+  metadata.gz: ce21f0b9edbbef2e18452c51755bf980c067c92afb651a86ee99b78aac0cbe6d
+  data.tar.gz: 0ee7cddd129757762d01cdce2f049622bb6f449e44de05ff5d592bfd4933136d
 SHA512:
-  metadata.gz: a398946361ad02e3c442c498119c952be21e4a379357f59ff674ae599961b5688cd6c0abdbdfe7b675194e94e3f21c67c2c3c276c709036975cf1ab48c52b429
-  data.tar.gz: 60cf92ad429a1aa1d2e706cb2226b1b3637cf757bd66df3bc77ddad4f8e64a9e415d5f6709b542477f5cd0c78e58d7e49cad443729e42af325a2a8ee519b666d
+  metadata.gz: 201b26e862cafbde3dfe07f1011ceb3d8241f362ff5386cbae8edbe5e0a250aa99ac800fd4c3d57d9984beec6f54348c78bd7a13f5265cae6a390d137494348e
+  data.tar.gz: de6f0ff8c15da14e155850368884cd14830dce374505ad098f8c3a902865d16ad7d42bd17a38ba51561b3e2fb829e73b03abf2530f16873f6249b1782da4ccc5

data/README.md

@@ -168,8 +168,29 @@ RailsVitals includes a built-in [MCP (Model Context Protocol)](https://modelcont
 
 Ask Claude things like:
 
+**Health score** (`railsvitals_get_score`)
 > "What is my Rails app's health score right now?"
+> "How much would my score improve if I fixed all N+1 patterns?"
+
+**N+1 patterns** (`railsvitals_get_n1_queries`)
 > "Show me the top 3 N+1 patterns and how to fix them."
+> "Which endpoint is responsible for the most N+1 occurrences?"
+
+**Slow queries** (`railsvitals_get_slow_queries`)
+> "Show me queries slower than 50ms."
+> "What is the single slowest query across all recent requests and which endpoint fired it?"
+
+**Request log** (`railsvitals_get_request_log`)
+> "Which requests from FeedController had the worst score?"
+> "Is PostsController#index consistently slow or only sometimes?"
+
+**Schema context** (`railsvitals_get_schema_context`)
+> "What models have foreign keys without an index?"
+> "Show me the full schema for Post and Comment including their associations."
+
+**EXPLAIN** (`railsvitals_explain_query`)
+> "Run EXPLAIN on this slow query and tell me what's wrong."
+> "Why is this query doing a sequential scan and how do I fix it?"
 
 ### Enabling the MCP server
 
@@ -218,7 +239,11 @@ Restart Claude Desktop and look for the RailsVitals tools in the tool picker.
 | Tool | Description |
 |------|-------------|
 | `railsvitals_get_score` | Overall health score, grade, score breakdown by dimension, N+1 penalties, and projected score if all N+1 patterns were fixed |
-| `railsvitals_get_n1_queries` | All detected N+1 patterns ranked by occurrences, with affected endpoints and concrete `includes()` fix suggestions. Accepts a `limit` param (default: 10) |
+| `railsvitals_get_n1_queries` | All detected N+1 patterns ranked by occurrences, with affected endpoints and concrete `includes()` fix suggestions. Accepts `limit` |
+| `railsvitals_get_slow_queries` | Individual slow queries across all recent requests, ordered by duration. Accepts `threshold_ms` override and `limit` |
+| `railsvitals_get_request_log` | Recent requests ordered most-recent-first with score, query count, DB time, and N+1 count. Accepts `controller` filter and `limit` |
+| `railsvitals_get_schema_context` | Columns, indexes, associations, and missing FK indexes for ActiveRecord models. Accepts a `models` array to scope results |
+| `railsvitals_explain_query` | Runs `EXPLAIN ANALYZE` on a SELECT query and returns warnings, fix suggestions with migration snippets, and a plain-English interpretation. Requires `sql` param |
 
 ### How it's structured
 
@@ -229,9 +254,13 @@ lib/rails_vitals/mcp/
 ├── response_builder.rb  # MCP response formatting helpers
 ├── tool_registry.rb     # Declarative class-based tool registry
 └── tools/
-    ├── base.rb            # Base class: call + definition interface
-    ├── get_score.rb       # railsvitals_get_score
-    └── get_n1_queries.rb  # railsvitals_get_n1_queries
+    ├── base.rb              # Base class: call + definition interface
+    ├── get_score.rb         # railsvitals_get_score
+    ├── get_n1_queries.rb    # railsvitals_get_n1_queries
+    ├── get_slow_queries.rb  # railsvitals_get_slow_queries
+    ├── get_request_log.rb   # railsvitals_get_request_log
+    ├── get_schema_context.rb # railsvitals_get_schema_context
+    └── explain_query.rb     # railsvitals_explain_query
 ```
 
 Each tool inherits from `Tools::Base`, implements `call(params)` returning a plain hash, and self-registers at load time via `ToolRegistry.register(ToolClass)`.

data/app/controllers/rails_vitals/playgrounds_controller.rb

@@ -13,7 +13,7 @@ module RailsVitals
       access_associations = Array(params[:access_associations]).reject(&:blank?)
 
       result = Playground::Sandbox.run(
-        expression,
+        clean_expr,
         access_associations: access_associations
       )
 

data/lib/rails_vitals/engine.rb

@@ -25,6 +25,10 @@ module RailsVitals
         require "rails_vitals/mcp/request_handler"
         require "rails_vitals/mcp/tools/get_score"
         require "rails_vitals/mcp/tools/get_n1_queries"
+        require "rails_vitals/mcp/tools/get_slow_queries"
+        require "rails_vitals/mcp/tools/get_request_log"
+        require "rails_vitals/mcp/tools/get_schema_context"
+        require "rails_vitals/mcp/tools/explain_query"
       end
     end
 

data/lib/rails_vitals/mcp/tools/explain_query.rb

@@ -0,0 +1,104 @@
+module RailsVitals
+  module MCP
+    module Tools
+      class ExplainQuery < Base
+        TOOL_NAME = "railsvitals_explain_query"
+
+        DESCRIPTION = <<~DESC.strip
+          Runs EXPLAIN ANALYZE on a SELECT query and returns the execution plan summary:
+          total cost, actual execution time, rows examined, detected warnings (Seq Scan,
+          Sort without index, large Nested Loop), and deterministic fix suggestions with
+          migration hints. Only SELECT statements are accepted — any SQL containing DML
+          keywords (INSERT, UPDATE, DELETE, DROP, TRUNCATE, ALTER) is rejected, including
+          CTEs. Use this to investigate a specific slow query from railsvitals_get_slow_queries.
+
+          When presenting results, always lead with the interpretation field as a plain-English
+          verdict. Then highlight each warning by name and explain what it means for this specific
+          query (table name, rows scanned). For each suggestion, show the body explanation first,
+          then the migration snippet in a code block, then the generator command if present.
+          Avoid listing raw numbers without context — translate total_cost and rows_examined into
+          plain language (e.g. "scanned 50,000 rows to return 3" instead of "rows_examined: 50000").
+        DESC
+
+        INPUT_SCHEMA = {
+          type: "object",
+          required: [ "sql" ],
+          properties: {
+            sql: {
+              type: "string",
+              description: "The SELECT query to explain. Must not contain INSERT, UPDATE, DELETE, DROP, TRUNCATE, or ALTER — including inside CTEs."
+            }
+          }
+        }.freeze
+
+        DML_PATTERN = /\b(INSERT|UPDATE|DELETE|DROP|TRUNCATE|ALTER|CREATE)\b/i.freeze
+
+        def call(params)
+          sql = params[:sql] || params["sql"]
+
+          return missing_sql_response if sql.nil? || sql.strip.empty?
+          return rejected_sql_response(sql) if dml_present?(sql)
+
+          result = Analyzers::ExplainAnalyzer.analyze(sql.strip)
+
+          return error_response(result.error) if result.error
+
+          {
+            sql: result.sql,
+            total_cost: result.total_cost,
+            actual_time_ms: result.actual_time_ms,
+            rows_examined: result.rows_examined,
+            warnings: serialize_warnings(result.warnings),
+            suggestions: serialize_suggestions(result.suggestions),
+            interpretation: result.interpretation
+          }
+        end
+
+        private
+
+        def dml_present?(sql)
+          sql.match?(DML_PATTERN)
+        end
+
+        def serialize_warnings(warnings)
+          warnings.map do |w|
+            entry = { type: w[:type].to_s, severity: w[:severity].to_s }
+            entry[:table] = w[:table] if w[:table]
+            entry[:rows_scanned] = w[:rows] if w[:rows]
+            entry
+          end
+        end
+
+        def serialize_suggestions(suggestions)
+          suggestions.map do |s|
+            entry = {
+              severity: s[:severity].to_s,
+              title: s[:title],
+              body: s[:body]
+            }
+            entry[:migration] = s[:migration] if s[:migration]
+            entry[:command] = s[:command] if s[:command]
+            entry
+          end
+        end
+
+        def missing_sql_response
+          { error: "Missing required parameter: sql. Provide a SELECT query to explain." }
+        end
+
+        def rejected_sql_response(sql)
+          keyword = sql.match(DML_PATTERN)&.captures&.first&.upcase
+          { error: "SQL rejected: contains #{keyword}. Only SELECT statements are allowed. " \
+                   "DML inside CTEs (WITH ... DELETE/INSERT/UPDATE) is also rejected because " \
+                   "EXPLAIN ANALYZE executes the query." }
+        end
+
+        def error_response(message)
+          { error: message }
+        end
+      end
+
+      ToolRegistry.register(ExplainQuery)
+    end
+  end
+end

data/lib/rails_vitals/mcp/tools/get_request_log.rb

@@ -0,0 +1,96 @@
+module RailsVitals
+  module MCP
+    module Tools
+      class GetRequestLog < Base
+        TOOL_NAME = "railsvitals_get_request_log"
+        DEFAULT_LIMIT = 20
+
+        DESCRIPTION = <<~DESC.strip
+          Returns recent requests recorded by RailsVitals, ordered most recent first.
+          Each entry includes endpoint, health score, query count, total DB time, N+1
+          pattern count, and request duration. Use the controller param to scope results
+          to a specific controller. Use this to spot whether problems are consistent or
+          intermittent and to identify which requests to investigate further.
+        DESC
+
+        INPUT_SCHEMA = {
+          type: "object",
+          properties: {
+            controller: {
+              type: "string",
+              description: "Filter by controller name (case-insensitive, partial match). 'Feed' matches FeedController."
+            },
+            limit: {
+              type: "integer",
+              description: "Maximum number of requests to return, most recent first. Defaults to 20."
+            }
+          }
+        }.freeze
+
+        def call(params)
+          records = RailsVitals.store.all
+          return no_data_response if records.empty?
+
+          controller_filter = params[:controller] || params["controller"]
+          limit = (params[:limit] || params["limit"] || DEFAULT_LIMIT).to_i
+
+          filtered = filter_records(records, controller_filter)
+          return no_match_response(controller_filter) if filtered.empty?
+
+          shown = filtered.last(limit).reverse
+
+          {
+            total_requests: filtered.size,
+            shown: shown.size,
+            controller_filter: controller_filter,
+            requests: shown.map { |r| serialize(r) }
+          }
+        end
+
+        private
+
+        def filter_records(records, controller_filter)
+          return records unless controller_filter
+
+          records.select { |r| r.controller.downcase.include?(controller_filter.downcase) }
+        end
+
+        def serialize(record)
+          {
+            request_id: record.id,
+            endpoint: record.endpoint,
+            score: record.score,
+            grade: record.label,
+            query_count: record.total_query_count,
+            db_time_ms: record.total_db_time_ms.round(1),
+            n1_patterns: record.n_plus_one_patterns.size,
+            duration_ms: record.duration_ms&.round(1),
+            recorded_at: record.recorded_at.strftime("%H:%M:%S")
+          }
+        end
+
+        def no_data_response
+          {
+            total_requests: 0,
+            shown: 0,
+            controller_filter: nil,
+            requests: [],
+            message: "No requests recorded yet. Make some requests to the app first."
+          }
+        end
+
+        def no_match_response(controller_filter)
+          {
+            total_requests: 0,
+            shown: 0,
+            controller_filter: controller_filter,
+            requests: [],
+            message: "No requests matched controller '#{controller_filter}'."
+          }
+        end
+      end
+
+      ToolRegistry.register(GetRequestLog)
+    end
+  end
+end

data/lib/rails_vitals/mcp/tools/get_schema_context.rb

@@ -0,0 +1,115 @@
+module RailsVitals
+  module MCP
+    module Tools
+      class GetSchemaContext < Base
+        TOOL_NAME = "railsvitals_get_schema_context"
+
+        DESCRIPTION = <<~DESC.strip
+          Returns schema context for ActiveRecord models: columns with types, indexes,
+          associations, and foreign keys missing an index. Use the models param to scope
+          to specific models; omit it to get all models. Use this to understand your data
+          model structure and spot missing indexes that could be causing slow queries or
+          N+1 patterns.
+        DESC
+
+        INPUT_SCHEMA = {
+          type: "object",
+          properties: {
+            models: {
+              type: "array",
+              items: { type: "string" },
+              description: "Model names to include (e.g. ['Post', 'User']). Omit to return all models."
+            }
+          }
+        }.freeze
+
+        def call(params)
+          requested = Array(params[:models] || params["models"]).map(&:to_s)
+
+          all_models = Analyzers::AssociationMapper.discover_models
+          models = requested.empty? ? all_models : filter_models(all_models, requested)
+
+          return no_models_response(requested) if models.empty?
+
+          {
+            models_analyzed: models.size,
+            models: models.map { |m| serialize_model(m) }
+          }
+        end
+
+        private
+
+        def filter_models(all_models, requested)
+          all_models.select do |m|
+            requested.any? { |r| m.name.downcase == r.downcase }
+          end
+        end
+
+        def serialize_model(model)
+          table = model.table_name
+          columns = columns_for(table)
+          indexes = indexes_for(table)
+          assocs = serialize_associations(model, indexes)
+          missing = assocs.select { |a| a[:macro] == "belongs_to" && !a[:indexed] }
+
+          {
+            name: model.name,
+            table: table,
+            columns: columns.map { |c| serialize_column(c) },
+            indexes: indexes.map { |i| serialize_index(i) },
+            associations: assocs,
+            missing_indexes: missing.map { |a| { foreign_key: a[:foreign_key], association: a[:name] } }
+          }
+        end
+
+        def serialize_column(col)
+          { name: col.name, type: col.type.to_s, nullable: col.null }
+        end
+
+        def serialize_index(idx)
+          { name: idx.name, columns: idx.columns, unique: idx.unique }
+        end
+
+        def serialize_associations(model, own_indexes)
+          model.reflect_on_all_associations.filter_map do |assoc|
+            target = assoc.klass rescue next
+
+            fk = assoc.foreign_key.to_s
+            if assoc.macro == :belongs_to
+              indexed = own_indexes.any? { |i| i.columns.first == fk }
+            else
+              indexed = indexes_for(target.table_name).any? { |i| i.columns.first == fk }
+            end
+
+            {
+              macro: assoc.macro.to_s,
+              name: assoc.name.to_s,
+              foreign_key: fk,
+              to: target.name,
+              indexed: indexed
+            }
+          end
+        end
+
+        def columns_for(table)
+          ActiveRecord::Base.connection.columns(table)
+        rescue StandardError
+          []
+        end
+
+        def indexes_for(table)
+          ActiveRecord::Base.connection.indexes(table)
+        rescue StandardError
+          []
+        end
+
+        def no_models_response(requested)
+          msg = requested.empty? ? "No ActiveRecord models found." : "No models matched: #{requested.join(', ')}."
+          { models_analyzed: 0, models: [], message: msg }
+        end
+      end
+
+      ToolRegistry.register(GetSchemaContext)
+    end
+  end
+end

data/lib/rails_vitals/mcp/tools/get_slow_queries.rb

@@ -0,0 +1,98 @@
+module RailsVitals
+  module MCP
+    module Tools
+      class GetSlowQueries < Base
+        TOOL_NAME = "railsvitals_get_slow_queries"
+
+        DESCRIPTION = <<~DESC.strip
+          Returns individual slow queries detected across recent requests, ordered by
+          duration descending. Each result includes the SQL, execution time, and the
+          endpoint that fired it. Use threshold_ms to override the default slow query
+          threshold (configured via mcp_slow_query_threshold_ms, default 100ms).
+          Use this after railsvitals_get_score to find which specific queries are
+          dragging down database performance.
+        DESC
+
+        INPUT_SCHEMA = {
+          type: "object",
+          properties: {
+            threshold_ms: {
+              type: "integer",
+              description: "Minimum query duration in ms to include. Defaults to config.mcp_slow_query_threshold_ms (100ms)."
+            },
+            limit: {
+              type: "integer",
+              description: "Maximum number of queries to return, ordered by duration desc. Defaults to 10."
+            }
+          }
+        }.freeze
+
+        DEFAULT_LIMIT = 10
+
+        def call(params)
+          records = RailsVitals.store.all
+          return no_data_response if records.empty?
+
+          threshold = (params[:threshold_ms] || params["threshold_ms"] || RailsVitals.config.mcp_slow_query_threshold_ms).to_i
+          limit = (params[:limit] || params["limit"] || DEFAULT_LIMIT).to_i
+
+          slow = collect_slow_queries(records, threshold)
+          return no_slow_queries_response(threshold) if slow.empty?
+
+          {
+            total_slow_queries: slow.size,
+            shown: [ limit, slow.size ].min,
+            threshold_ms: threshold,
+            queries: slow.first(limit).map { |q| serialize(q) }
+          }
+        end
+
+        private
+
+        def collect_slow_queries(records, threshold)
+          queries = []
+
+          records.each do |record|
+            record.queries.each do |q|
+              next if q[:duration_ms] < threshold
+
+              queries << q.merge(endpoint: record.endpoint, request_id: record.id)
+            end
+          end
+
+          queries.sort_by { |q| -q[:duration_ms] }
+        end
+
+        def serialize(query)
+          {
+            sql: query[:sql],
+            duration_ms: query[:duration_ms].round(1),
+            endpoint: query[:endpoint],
+            request_id: query[:request_id]
+          }
+        end
+
+        def no_data_response
+          {
+            total_slow_queries: 0,
+            shown: 0,
+            queries: [],
+            message: "No requests recorded yet. Make some requests to the app first."
+          }
+        end
+
+        def no_slow_queries_response(threshold)
+          {
+            total_slow_queries: 0,
+            shown: 0,
+            threshold_ms: threshold,
+            queries: [],
+            message: "No queries exceeded #{threshold}ms in recent requests."
+          }
+        end
+      end
+
+      ToolRegistry.register(GetSlowQueries)
+    end
+  end
+end

data/lib/rails_vitals/playground/safe_chain_builder.rb

@@ -0,0 +1,292 @@
+require "strscan"
+
+module RailsVitals
+  module Playground
+    class SafeChainBuilder
+      ALLOWED_METHODS = %w[
+        all where select limit offset order group
+        includes preload eager_load joins left_joins
+        find find_by first last count sum average
+        pluck distinct having references unscoped not
+      ].freeze
+
+      DISALLOWED_CLASS_METHODS = %w[
+        connection execute exec system eval send public_send __send__
+        instance_eval class_eval module_eval define_method method_missing
+        delete destroy delete_all destroy_all update_all
+      ].freeze
+
+      ParseError = Class.new(StandardError)
+
+      def self.build(chain_str, model)
+        relation = model.all
+        parse_chain(chain_str).each do |method_name, args|
+          if DISALLOWED_CLASS_METHODS.include?(method_name)
+            raise ParseError, "Method '#{method_name}' is not allowed for security reasons"
+          end
+          unless ALLOWED_METHODS.include?(method_name)
+            raise ParseError, "Method '#{method_name}' is not allowed. Allowed: #{ALLOWED_METHODS.join(', ')}"
+          end
+          relation = relation.public_send(method_name, *args)
+        end
+
+        raise ParseError, "Expression must return an ActiveRecord::Relation" unless relation.is_a?(ActiveRecord::Relation)
+        relation
+      end
+
+      private
+
+      def self.parse_chain(str)
+        scanner = StringScanner.new(str)
+        calls = []
+        scanner.skip(/\s+/)
+
+        until scanner.eos?
+          scanner.skip(/\.\s*/)
+
+          name = scanner.scan(/[a-z_][a-zA-Z0-9_!?]*/)
+          raise ParseError, "Expected method name at position #{scanner.pos}" unless name
+
+          scanner.skip(/\s+/)
+          if scanner.scan(/\(/)
+            args = parse_args(scanner)
+            scanner.skip(/\s*\)/)
+            calls << [ name, args ]
+          else
+            calls << [ name, [] ]
+          end
+          scanner.skip(/\s+/)
+        end
+
+        calls
+      end
+
+      def self.parse_args(scanner)
+        args = []
+        scanner.skip(/\s+/)
+        return args if scanner.eos? || scanner.peek(1) == ")"
+
+        loop do
+          scanner.skip(/\s+/)
+          break if scanner.eos? || scanner.peek(1) == ")"
+
+          if keyword_hash_start?(scanner)
+            args << scan_keyword_hash(scanner)
+          else
+            args << scan_value(scanner)
+          end
+
+          scanner.skip(/\s+/)
+          break unless scanner.scan(/,/)
+        end
+
+        args
+      end
+
+      def self.keyword_hash_start?(scanner)
+        pos = scanner.pos
+        ident = scanner.scan(/[a-zA-Z_][a-zA-Z0-9_]*/)
+        return false unless ident
+
+        scanner.skip(/\s*/)
+
+        if scanner.scan(/:/) && !scanner.scan(/:/)
+          scanner.pos = pos
+          return true
+        end
+
+        scanner.pos = pos
+        false
+      end
+
+      def self.scan_keyword_hash(scanner)
+        hash = {}
+        loop do
+          scanner.skip(/\s+/)
+          break if scanner.eos? || scanner.peek(1) == ")" || scanner.peek(1) == "}"
+
+          key = scanner.scan(/[a-zA-Z_][a-zA-Z0-9_]*/)
+          raise ParseError, "Expected hash key" unless key
+          scanner.skip(/\s*:\s*/)
+          value = scan_value(scanner)
+          hash[key.to_sym] = value
+          scanner.skip(/\s+/)
+          break unless scanner.scan(/,/)
+        end
+        hash
+      end
+
+      def self.scan_value(scanner)
+        scanner.skip(/\s+/)
+        ch = scanner.peek(1)
+        raise ParseError, "Unexpected end of expression" unless ch
+
+        case ch
+        when "'" then scan_single_quoted_string(scanner)
+        when '"' then scan_double_quoted_string(scanner)
+        when ":" then scan_symbol(scanner)
+        when "t"
+          if scanner.scan(/true\b/)
+            true
+          else
+            raise ParseError, "Unexpected token at position #{scanner.pos}"
+          end
+        when "f"
+          if scanner.scan(/false\b/)
+            false
+          else
+            raise ParseError, "Unexpected token at position #{scanner.pos}"
+          end
+        when "n"
+          if scanner.scan(/nil\b/)
+            nil
+          else
+            raise ParseError, "Unexpected token at position #{scanner.pos}"
+          end
+        when "[" then scan_array(scanner)
+        when "{" then scan_hash_literal(scanner)
+        when "-", "+", "0", "1", "2", "3", "4", "5", "6", "7", "8", "9" then scan_number(scanner)
+        else
+          raise ParseError, "Unexpected token '#{ch}' at position #{scanner.pos}"
+        end
+      end
+
+      def self.scan_single_quoted_string(scanner)
+        scanner.pos += 1
+        result = +""
+        until scanner.eos?
+          case scanner.peek(1)
+          when "'"
+            scanner.pos += 1
+            return result
+          when "\\"
+            scanner.pos += 1
+            escaped = scanner.getch
+            case escaped
+            when "'" then result << "'"
+            when "\\" then result << "\\"
+            else result << "\\#{escaped}"
+            end
+          else
+            result << scanner.getch
+          end
+        end
+        raise ParseError, "Unterminated single-quoted string"
+      end
+
+      def self.scan_double_quoted_string(scanner)
+        scanner.pos += 1
+        result = +""
+        until scanner.eos?
+          case scanner.peek(1)
+          when '"'
+            scanner.pos += 1
+            return result
+          when "\\"
+            scanner.pos += 1
+            escaped = scanner.getch
+            case escaped
+            when '"' then result << '"'
+            when "\\" then result << "\\"
+            when "n" then result << "\n"
+            when "t" then result << "\t"
+            when "r" then result << "\r"
+            when "#" then result << "#"
+            else result << "\\#{escaped}"
+            end
+          else
+            result << scanner.getch
+          end
+        end
+        raise ParseError, "Unterminated double-quoted string"
+      end
+
+      def self.scan_symbol(scanner)
+        scanner.pos += 1
+        if scanner.scan(/[a-zA-Z_][a-zA-Z0-9_]*/)
+          scanner.matched.to_sym
+        elsif (str = scanner.scan(/"[^"]*"/) || scanner.scan(/'[^']*'/))
+          str[1..-2].to_sym
+        else
+          raise ParseError, "Invalid symbol at position #{scanner.pos}"
+        end
+      end
+
+      def self.scan_number(scanner)
+        num_str = scanner.scan(/-?[0-9]+(\.[0-9]+)?([eE][+-]?[0-9]+)?/)
+        raise ParseError, "Invalid number at position #{scanner.pos}" unless num_str
+        if num_str.include?(".") || num_str.match?(/[eE]/)
+          num_str.to_f
+        else
+          num_str.to_i
+        end
+      end
+
+      def self.scan_array(scanner)
+        scanner.pos += 1
+        arr = []
+        scanner.skip(/\s+/)
+        unless scanner.peek(1) == "]"
+          loop do
+            arr << scan_value(scanner)
+            scanner.skip(/\s+/)
+            break unless scanner.scan(/,/)
+            scanner.skip(/\s+/)
+          end
+        end
+        scanner.skip(/\s*\]/)
+        raise ParseError, "Unterminated array" unless scanner.matched
+        arr
+      end
+
+      def self.scan_hash_literal(scanner)
+        scanner.pos += 1
+        hash = {}
+        scanner.skip(/\s+/)
+        unless scanner.eos? || scanner.peek(1) == "}"
+          loop do
+            scanner.skip(/\s+/)
+            break if scanner.eos? || scanner.peek(1) == "}"
+
+            key = parse_hash_key(scanner)
+            scanner.skip(/\s+/)
+
+            if scanner.scan(/=>/)
+              scanner.skip(/\s+/)
+              hash[key] = scan_value(scanner)
+            elsif scanner.scan(/:\s*/)
+              hash[key.to_sym] = scan_value(scanner)
+            else
+              raise ParseError, "Expected '=>' or ':' after hash key"
+            end
+
+            scanner.skip(/\s+/)
+            break unless scanner.scan(/,/)
+          end
+        end
+        scanner.skip(/\s*}/)
+        raise ParseError, "Unterminated hash" unless scanner.matched
+        hash
+      end
+
+      def self.parse_hash_key(scanner)
+        case scanner.peek(1)
+        when '"', "'" then scan_string(scanner)
+        when ":" then scan_symbol(scanner)
+        else
+          ident = scanner.scan(/[a-zA-Z_][a-zA-Z0-9_]*/)
+          raise ParseError, "Expected hash key" unless ident
+          ident
+        end
+      end
+
+      def self.scan_string(scanner)
+        case scanner.peek(1)
+        when "'" then scan_single_quoted_string(scanner)
+        when '"' then scan_double_quoted_string(scanner)
+        else raise ParseError, "Expected string"
+        end
+      end
+    end
+  end
+end

data/lib/rails_vitals/playground/sandbox.rb

@@ -1,19 +1,16 @@
 module RailsVitals
   module Playground
     class Sandbox
-      ALLOWED_METHODS = %w[
-        all where select limit offset order group
-        includes preload eager_load joins left_joins
-        find find_by first last count sum average
-        pluck distinct having references unscoped
-      ].freeze
-
       BLOCKED_PATTERNS = [
         /\b(insert|update|delete|destroy|drop|truncate|create|alter)\b/i,
         /\.save/i, /\.save!/i, /\.update/i, /\.delete/i,
         /\.destroy/i, /`/
       ].freeze
 
+      SAFE_EXPRESSION_PATTERN = /\A[a-zA-Z0-9_\.\s\(\),:\[\]{}'"!?=<>|&*+\-\/\\%]+\z/
+
+      ASSOCIATION_NAME_PATTERN = /\A[a-zA-Z_][a-zA-Z0-9_]*\z/
+
       DEFAULT_LIMIT = 100
 
       Result = Struct.new(
@@ -26,6 +23,13 @@ module RailsVitals
       def self.run(expression, access_associations: [])
         return blocked_result("No expression provided") if expression.blank?
 
+        expression = expression.gsub(/#[^\n]*/, "").strip
+        return blocked_result("No expression provided") if expression.blank?
+
+        return blocked_result(
+          "Expression contains invalid characters."
+        ) unless expression.match?(SAFE_EXPRESSION_PATTERN)
+
         BLOCKED_PATTERNS.each do |pattern|
           return blocked_result(
             "Expression contains blocked operation. " \
@@ -33,6 +37,10 @@ module RailsVitals
           ) if expression.match?(pattern)
         end
 
+        access_associations = access_associations.select do |name|
+          name.to_s.match?(ASSOCIATION_NAME_PATTERN)
+        end
+
         model_name = extract_model_name(expression)
         return blocked_result(
           "Could not detect model from expression. " \
@@ -111,10 +119,7 @@ module RailsVitals
       end
 
       def self.extract_model_name(expression)
-        # Strip comments first
-        clean = expression.gsub(/#[^\n]*/, "").strip
-        # First word before a dot or whitespace — must look like a constant (CamelCase)
-        match = clean.match(/\A([A-Z][A-Za-z0-9]*)/)
+        match = expression.match(/\A([A-Z][A-Za-z0-9]*)/)
         match ? match[1] : nil
       end
 
@@ -132,31 +137,15 @@ module RailsVitals
       end
 
       def self.build_relation(expression, model)
-        # Parse "Post.includes(:likes).where(published: true).limit(10)"
-        # Strip the model name prefix if present
         chain_str = expression
           .sub(/\A#{Regexp.escape(model.name)}\s*\.?\s*/, "")
           .strip
 
         return model.all if chain_str.blank?
 
-        # Build the chain by safe eval within a controlled binding
-        # Only the model constant is exposed, no access to app globals
-        sandbox_binding = build_binding(model)
-        relation = eval(chain_str, sandbox_binding) # rubocop:disable Security/Eval
-
-        unless relation.is_a?(ActiveRecord::Relation)
-          raise "Expression must return an ActiveRecord::Relation"
-        end
-
-        relation
-      end
-
-      def self.build_binding(model)
-        # Create a minimal binding with only the model exposed
-        ctx = Object.new
-        ctx.define_singleton_method(:relation) { model.all }
-        ctx.instance_eval { binding }
+        SafeChainBuilder.build(chain_str, model)
+      rescue SafeChainBuilder::ParseError => e
+        raise "Expression error: #{e.message}"
       end
 
       def self.apply_limit(relation)

data/lib/rails_vitals/version.rb

@@ -1,3 +1,3 @@
 module RailsVitals
-  VERSION = "0.5.1"
+  VERSION = "0.6.1"
 end

data/lib/rails_vitals.rb

@@ -14,6 +14,7 @@ require "rails_vitals/scorers/base_scorer"
 require "rails_vitals/scorers/query_scorer"
 require "rails_vitals/scorers/n_plus_one_scorer"
 require "rails_vitals/scorers/composite_scorer"
+require "rails_vitals/playground/safe_chain_builder"
 require "rails_vitals/playground/sandbox"
 require "rails_vitals/panel_renderer"
 require "rails_vitals/middleware/panel_injector"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_vitals
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.1
 platform: ruby
 authors:
 - David Sanchez
@@ -86,11 +86,16 @@ files:
 - lib/rails_vitals/mcp/response_builder.rb
 - lib/rails_vitals/mcp/tool_registry.rb
 - lib/rails_vitals/mcp/tools/base.rb
+- lib/rails_vitals/mcp/tools/explain_query.rb
 - lib/rails_vitals/mcp/tools/get_n1_queries.rb
+- lib/rails_vitals/mcp/tools/get_request_log.rb
+- lib/rails_vitals/mcp/tools/get_schema_context.rb
 - lib/rails_vitals/mcp/tools/get_score.rb
+- lib/rails_vitals/mcp/tools/get_slow_queries.rb
 - lib/rails_vitals/middleware/panel_injector.rb
 - lib/rails_vitals/notifications/subscriber.rb
 - lib/rails_vitals/panel_renderer.rb
+- lib/rails_vitals/playground/safe_chain_builder.rb
 - lib/rails_vitals/playground/sandbox.rb
 - lib/rails_vitals/request_record.rb
 - lib/rails_vitals/scorers/base_scorer.rb