rails_vitals 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76e3b231f12c366dba7fbd5cf3e54959922fd0b8e26d6ad865d924de95523887
-  data.tar.gz: 56e6c2d230f2fd852f6aded8773e627bbcac09b155c34e49d6b34c6453c2116a
+  metadata.gz: 82d62304d92259c9c248b8033948784ba6bb5075d7f7af627c445624a042901a
+  data.tar.gz: 6285bf97528093389e861f96bb45259d434e336042c7d23e30fab02109e690ce
 SHA512:
-  metadata.gz: a398946361ad02e3c442c498119c952be21e4a379357f59ff674ae599961b5688cd6c0abdbdfe7b675194e94e3f21c67c2c3c276c709036975cf1ab48c52b429
-  data.tar.gz: 60cf92ad429a1aa1d2e706cb2226b1b3637cf757bd66df3bc77ddad4f8e64a9e415d5f6709b542477f5cd0c78e58d7e49cad443729e42af325a2a8ee519b666d
+  metadata.gz: 0ae1ce76d1ac8c1bbf7559a119e1680f87b40faafe989f0e6c6afb9ec5f3cb8c374a1899a32ca28f04d39ee7ddb4e6f4b73251f16835c8a9587590ecc6ff6cc8
+  data.tar.gz: 48245cadf704dc9bced9103cad91485d0b9b1c1173b11b50fd79b8964259cb41eaba8af42ff86ca95c1d6ba16ddc52e1f88120159317065e36fb2a4c53d10792

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/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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_vitals
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - David Sanchez
@@ -86,8 +86,12 @@ 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