rails_vitals 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 277b26e5e359214e2fba9795bd3b8498101f0f834ba2c41c935af01618eeff9d
-  data.tar.gz: 758358422faf3c52d11778ce3472940eb43008c0988bfea538d40a0814a73253
+  metadata.gz: 899c0ed5c53864a4498cc68ea499e35aa04799e85b9b7aa0ecad37d049c9b8f1
+  data.tar.gz: f71dfb2d3e615bcaee3db50d80dd01c5169dd6fda71bb8e18f3fa99837e5b06e
 SHA512:
-  metadata.gz: 117124cfef5de4acf5aeb28f237d1e21d26e3658cb280bdc340f53e8c2a0c30573c140e0217e83a2423af56c76c5db2de7956aab4425ff0b527b236c5d1aaf0f
-  data.tar.gz: 6939cd948d253037865299811f8f73a88c17c5805ded7a1b86018ace53a4ab3352748fa54e33806b4cbab355348f212ed4dafc53dcf5735b84261cae78b00b50
+  metadata.gz: 3a54d18fced19b25868b6db6cbc84c9808b9a308dd60ba5247bbc469bd34a937c48620784fd51d3e16000c027d21f53c0fc4691371e4d89fe91e43fa89aed683
+  data.tar.gz: cd69a0bacb284837f611c997220293c64b711573b18090167355307c39727367d4f657dcdc6a74a07e9fb0f341837199e9c7d59e368d611463dfce8c2e552bea

data/README.md

@@ -135,6 +135,10 @@ RailsVitals.configure do |config|
 
   # Custom auth lambda (if auth: :lambda)
   # config.auth = ->(request) { request.session[:admin] == true }
+
+  # MCP server (disabled by default, never runs in production)
+  config.mcp_enabled    = false
+  config.mcp_auth_token = nil   # set a token to require Authorization: Bearer <token>
 end
 ```
 
@@ -158,6 +162,86 @@ Navigate to `/rails_vitals` to access the full admin interface.
 
 ---
 
+## MCP Server — AI Tool Integration
+
+RailsVitals includes a built-in [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that exposes your app's performance data as tools that Claude Desktop and other MCP-compatible AI clients can call directly.
+
+Ask Claude things like:
+
+> "What is my Rails app's health score right now?"
+> "Show me the top 3 N+1 patterns and how to fix them."
+
+### Enabling the MCP server
+
+```ruby
+# config/initializers/rails_vitals.rb
+RailsVitals.configure do |config|
+  config.mcp_enabled    = true
+  config.mcp_auth_token = "your-secret-token"   # optional but recommended
+end
+```
+
+The MCP server is disabled by default and raises an error if enabled in production.
+
+### Connecting Claude Desktop
+
+Install `mcp-remote`, which bridges Claude Desktop's stdio transport to the HTTP-based MCP server:
+
+```bash
+npm install -g mcp-remote
+```
+
+Add an entry to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
+
+```json
+{
+  "mcpServers": {
+    "rails-vitals": {
+      "command": "/absolute/path/to/npx",
+      "args": [
+        "mcp-remote",
+        "http://localhost:3000/rails_vitals/mcp",
+        "--header",
+        "Authorization: Bearer your-secret-token"
+      ]
+    }
+  }
+}
+```
+
+Use an absolute path to `npx` (e.g. from `which npx`) — Claude Desktop does not inherit your shell `PATH`.
+
+Restart Claude Desktop and look for the RailsVitals tools in the tool picker.
+
+### Available tools
+
+| 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) |
+
+### How it's structured
+
+```
+lib/rails_vitals/mcp/
+├── auth.rb              # Bearer token validation
+├── request_handler.rb   # JSON-RPC 2.0 dispatcher
+├── 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
+```
+
+Each tool inherits from `Tools::Base`, implements `call(params)` returning a plain hash, and self-registers at load time via `ToolRegistry.register(ToolClass)`.
+
+### Example
+
+![Claude MCP](https://github.com/user-attachments/assets/4cf7d071-1925-4b9f-a1cb-49b61f2e30e7)
+
+---
+
 ## How Scoring Works
 
 RailsVitals scores each request using a `CompositeScorer` with two weighted dimensions:
@@ -264,8 +348,18 @@ rails_vitals/
 │       │   ├── query_scorer.rb                # 40% weight
 │       │   ├── n_plus_one_scorer.rb           # 60% weight
 │       │   └── composite_scorer.rb
-│       └── middleware/
-│           └── panel_injector.rb              # Rack middleware for panel injection
+│       ├── calculable.rb                      # Shared average/percentage helpers
+│       ├── middleware/
+│       │   └── panel_injector.rb              # Rack middleware for panel injection
+│       └── mcp/
+│           ├── auth.rb                        # Bearer token validation
+│           ├── request_handler.rb             # JSON-RPC 2.0 dispatcher
+│           ├── response_builder.rb            # MCP response helpers
+│           ├── tool_registry.rb               # Declarative tool registry
+│           └── tools/
+│               ├── base.rb                    # Base class for all tools
+│               ├── get_score.rb               # railsvitals_get_score
+│               └── get_n1_queries.rb          # railsvitals_get_n1_queries
 └── app/
     ├── controllers/rails_vitals/
     │   ├── dashboard_controller.rb

data/app/controllers/rails_vitals/dashboard_controller.rb

@@ -1,5 +1,7 @@
 module RailsVitals
   class DashboardController < ApplicationController
+    include Calculable
+
     def index
       @records = RailsVitals.store.all.reverse
       @total   = @records.size
@@ -14,12 +16,6 @@ module RailsVitals
 
     private
 
-    def average(records, method)
-      return 0 if records.empty?
-
-      (records.sum(&method).to_f / records.size).round(1)
-    end
-
     def top_offenders(records)
       records
         .group_by(&:endpoint)

data/app/controllers/rails_vitals/heatmap_controller.rb

@@ -1,5 +1,6 @@
 module RailsVitals
   class HeatmapController < ApplicationController
+    include Calculable
     def index
       records   = RailsVitals.store.all
       @heatmap  = build_heatmap(records)
@@ -25,15 +26,9 @@ module RailsVitals
         .sort_by { |row| row[:avg_score] }
     end
 
-    def average(records, method)
-      return 0.0 if records.empty?
-      (records.sum { |r| r.public_send(method) }.to_f / records.size).round(1)
-    end
-
     def n_plus_one_frequency(reqs)
       reqs_with_n1 = reqs.count { |r| r.n_plus_one_patterns.any? }
-      return 0.0 if reqs.empty?
-      ((reqs_with_n1.to_f / reqs.size) * 100).round(1)
+      percentage(reqs_with_n1, reqs.size)
     end
   end
 end

data/app/controllers/rails_vitals/mcp_controller.rb

@@ -0,0 +1,42 @@
+module RailsVitals
+  class McpController < ActionController::API
+    before_action :verify_environment
+    before_action :verify_auth
+
+    def call
+      raw_body = request.body.read
+      result   = handler.handle(raw_body)
+
+      render json: result
+    end
+
+    private
+
+    def verify_environment
+      if Rails.env.production?
+        render json: ResponseBuilder.error(
+          nil,
+          ResponseBuilder::AUTH_ERROR,
+          "RailsVitals MCP is not available in production"
+        ), status: :forbidden
+      end
+    end
+
+    def verify_auth
+      auth = MCP::Auth.new(RailsVitals.config.mcp_auth_token)
+
+      unless auth.valid?(request)
+        render json: MCP::ResponseBuilder.error(
+          nil,
+          MCP::ResponseBuilder::AUTH_ERROR,
+          "Unauthorized",
+          { detail: "Valid Bearer token required" }
+        ), status: :unauthorized
+      end
+    end
+
+    def handler
+      @handler ||= MCP::RequestHandler.new
+    end
+  end
+end

data/config/routes.rb

@@ -8,4 +8,6 @@ RailsVitals::Engine.routes.draw do
   resources :playgrounds, only: [ :index, :create ]
   get "heatmap", to: "heatmap#index", as: :heatmap
   get "requests/:request_id/explain/:query_index", to: "explains#show", as: :explain
+
+  post "/mcp", to: "mcp#call" if RailsVitals.config.mcp_enabled
 end

data/lib/rails_vitals/calculable.rb

@@ -0,0 +1,15 @@
+module RailsVitals
+  module Calculable
+    def average(records, method)
+      return 0.0 if records.empty?
+
+      (records.sum(&method).to_f / records.size).round(1)
+    end
+
+    def percentage(count, total)
+      return 0.0 if total.zero?
+
+      (count.to_f / total * 100).round(1)
+    end
+  end
+end

data/lib/rails_vitals/configuration.rb

@@ -9,7 +9,11 @@ module RailsVitals
                   :query_warn_threshold,
                   :query_critical_threshold,
                   :db_time_warn_ms,
-                  :db_time_critical_ms
+                  :db_time_critical_ms,
+                  :mcp_enabled,
+                  :mcp_auth_token,
+                  :mcp_max_log_size,
+                  :mcp_slow_query_threshold_ms
 
     def initialize
       @enabled                  = defined?(Rails) && !Rails.env.production?
@@ -22,6 +26,12 @@ module RailsVitals
       @query_critical_threshold = 25
       @db_time_warn_ms          = 100
       @db_time_critical_ms      = 500
+
+      # MCP Server — disabled by default
+      @mcp_enabled                 = false
+      @mcp_auth_token              = nil
+      @mcp_max_log_size            = 100
+      @mcp_slow_query_threshold_ms = 100
     end
   end
 end

data/lib/rails_vitals/engine.rb

@@ -14,6 +14,20 @@ module RailsVitals
       end
     end
 
+    initializer "rails_vitals.mcp" do
+      if RailsVitals.config.mcp_enabled
+        raise "RailsVitals MCP cannot run in production" if Rails.env.production?
+
+        require "rails_vitals/mcp/auth"
+        require "rails_vitals/mcp/response_builder"
+        require "rails_vitals/mcp/tool_registry"
+        require "rails_vitals/mcp/tools/base"
+        require "rails_vitals/mcp/request_handler"
+        require "rails_vitals/mcp/tools/get_score"
+        require "rails_vitals/mcp/tools/get_n1_queries"
+      end
+    end
+
     config.to_prepare do
       if RailsVitals.config.enabled
         ActiveRecord::Base.prepend(

data/lib/rails_vitals/mcp/auth.rb

@@ -0,0 +1,21 @@
+module RailsVitals
+  module MCP
+    class Auth
+      BEARER_PATTERN = /\ABearer (.+)\z/
+
+      def initialize(token)
+        @expected_token = token
+      end
+
+      def valid?(request)
+        return false if @expected_token.blank?
+
+        auth_header = request.get_header("HTTP_AUTHORIZATION") || ""
+        match = BEARER_PATTERN.match(auth_header)
+        return false unless match
+
+        ActiveSupport::SecurityUtils.secure_compare(match[1], @expected_token)
+      end
+    end
+  end
+end

data/lib/rails_vitals/mcp/request_handler.rb

@@ -0,0 +1,101 @@
+module RailsVitals
+  module MCP
+    class RequestHandler
+      include ResponseBuilder
+
+      SERVER_INFO = {
+        name: "railsvitals",
+        version: RailsVitals::VERSION
+      }.freeze
+
+      PROTOCOL_VERSION = "2025-11-25"
+      JSON_RPC_VERSION = "2.0"
+
+      INSTRUCTIONS = <<~TEXT.strip
+        RailsVitals exposes Rails app performance diagnostics.
+        Recommended flow: call railsvitals_get_schema_context first to understand
+        the data model, then railsvitals_get_score for a high-level diagnosis,
+        then drill down with the specific query tools.
+      TEXT
+
+      def handle(raw_body)
+        payload = parse_json(raw_body)
+        return payload if payload.is_a?(Hash) && payload[:error]
+
+        id = payload[:id]
+        method = payload[:method]
+
+        unless method.present?
+          return ResponseBuilder.error(id, ResponseBuilder::INVALID_REQUEST, "Missing method")
+        end
+
+        case method
+        when "initialize" then handle_initialize(id, payload[:params] || {})
+        when "tools/list" then handle_tools_list(id)
+        when "tools/call" then handle_tools_call(id, payload[:params] || {})
+        else
+          ResponseBuilder.error(id, ResponseBuilder::METHOD_NOT_FOUND, "Method not found: #{method}")
+        end
+      end
+
+      private
+
+      def parse_json(raw_body)
+        payload = JSON.parse(raw_body, symbolize_names: true)
+
+        unless payload[:jsonrpc] == JSON_RPC_VERSION
+          return ResponseBuilder.error(nil, ResponseBuilder::INVALID_REQUEST, "jsonrpc must be '#{JSON_RPC_VERSION}'")
+        end
+
+        payload
+      rescue JSON::ParserError => e
+        ResponseBuilder.error(nil, ResponseBuilder::PARSE_ERROR, "Parse error: #{e.message}")
+      end
+
+      def handle_initialize(id, _params)
+        ResponseBuilder.success(id, {
+          protocolVersion: PROTOCOL_VERSION,
+          serverInfo: SERVER_INFO,
+          capabilities: { tools: {} },
+          instructions: INSTRUCTIONS
+        })
+      end
+
+      def handle_tools_list(id)
+        ResponseBuilder.success(id, {
+          tools: ToolRegistry.all_definitions
+        })
+      end
+
+      def handle_tools_call(id, params)
+        name = params[:name]
+        arguments = params[:arguments] || {}
+
+        unless name.present?
+          return ResponseBuilder.error(id, ResponseBuilder::INVALID_PARAMS, "Missing tool name")
+        end
+
+        tool_class = ToolRegistry.find(name)
+
+        unless tool_class
+          return ResponseBuilder.error(
+            id,
+            ResponseBuilder::METHOD_NOT_FOUND,
+            "Tool not found",
+            { tool: name }
+          )
+        end
+
+        result = tool_class.new.call(arguments)
+        ResponseBuilder.tool_success(id, result)
+      rescue => e
+        ResponseBuilder.error(
+          id,
+          ResponseBuilder::TOOL_EXEC_ERROR,
+          "Tool execution failed",
+          { tool: name, detail: e.message }
+        )
+      end
+    end
+  end
+end

data/lib/rails_vitals/mcp/response_builder.rb

@@ -0,0 +1,47 @@
+module RailsVitals
+  module MCP
+    module ResponseBuilder
+      JSON_RPC_VERSION = "2.0"
+
+      def self.success(id, result)
+        {
+          jsonrpc: JSON_RPC_VERSION,
+          id: id,
+          result: result
+        }
+      end
+
+      def self.tool_success(id, data)
+        success(id, {
+          content: [
+            {
+              type: "text",
+              text: data.to_json
+            }
+          ]
+        })
+      end
+
+      def self.error(id, code, message, data = nil)
+        err = { code: code, message: message }
+        err[:data] = data if data.present?
+
+        {
+          jsonrpc: JSON_RPC_VERSION,
+          id: id,
+          error: err
+        }
+      end
+
+      # JSON-RPC 2.0 standard error codes
+      PARSE_ERROR      = -32_700
+      INVALID_REQUEST  = -32_600
+      METHOD_NOT_FOUND = -32_601
+      INVALID_PARAMS   = -32_602
+
+      # RailsVitals custom error codes
+      AUTH_ERROR       = -32_000
+      TOOL_EXEC_ERROR  = -32_001
+    end
+  end
+end

data/lib/rails_vitals/mcp/tool_registry.rb

@@ -0,0 +1,29 @@
+module RailsVitals
+  module MCP
+    class ToolRegistry
+      class << self
+        def register(tool_class)
+          registry[tool_class.tool_name] = tool_class
+        end
+
+        def all_definitions
+          registry.values.map(&:definition)
+        end
+
+        def find(name)
+          registry[name]
+        end
+
+        def exists?(name)
+          registry.key?(name)
+        end
+
+        private
+
+        def registry
+          @registry ||= {}
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+module RailsVitals
+  module MCP
+    module Tools
+      class Base
+        # Subclasses must define:
+        #   TOOL_NAME = "railsvitals_example"
+        #   DESCRIPTION = "What this tool does for the AI model"
+        #   INPUT_SCHEMA = { type: "object", properties: {} }
+        #
+        # And implement:
+        #   def call(params) → Hash
+
+        def self.tool_name
+          self::TOOL_NAME
+        end
+
+        def self.definition
+          {
+            name: self::TOOL_NAME,
+            description: self::DESCRIPTION,
+            inputSchema: self::INPUT_SCHEMA
+          }
+        end
+
+        def call(params)
+          raise NotImplementedError, "#{self.class}#call is not implemented"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,93 @@
+module RailsVitals
+  module MCP
+    module Tools
+      class GetN1Queries < Base
+        TOOL_NAME = "railsvitals_get_n1_queries"
+
+        DESCRIPTION = <<~DESC.strip
+          Returns all N+1 query patterns detected across recent requests, grouped and
+          ranked by number of occurrences. Each pattern includes the normalized SQL
+          fingerprint, affected endpoints with hit counts, and a deterministic fix
+          suggestion (the correct includes() call) derived from ActiveRecord reflection.
+          Use this after railsvitals_get_score to identify which N+1 patterns to fix.
+        DESC
+
+        INPUT_SCHEMA = {
+          type: "object",
+          properties: {
+            limit: {
+              type: "integer",
+              description: "Maximum number of patterns to return, ordered by occurrences desc. Defaults to 10."
+            }
+          }
+        }.freeze
+
+        DEFAULT_LIMIT = 10
+
+        def call(params)
+          records = RailsVitals.store.all
+          return no_data_response if records.empty?
+
+          limit = (params[:limit] || params["limit"] || DEFAULT_LIMIT).to_i
+          patterns = Analyzers::NPlusOneAggregator.aggregate(records)
+
+          return no_n1_response if patterns.empty?
+
+          {
+            total_patterns: patterns.size,
+            shown: [ limit, patterns.size ].min,
+            patterns: patterns.first(limit).map { |p| serialize(p) }
+          }
+        end
+
+        private
+
+        def no_data_response
+          {
+            total_patterns: 0,
+            shown: 0,
+            patterns: [],
+            message: "No requests recorded yet. Make some requests to the app first."
+          }
+        end
+
+        def no_n1_response
+          {
+            total_patterns: 0,
+            shown: 0,
+            patterns: [],
+            message: "No N+1 patterns detected in recent requests."
+          }
+        end
+
+        def serialize(pattern)
+          {
+            pattern: pattern[:pattern],
+            occurrences: pattern[:occurrences],
+            table: pattern[:table],
+            foreign_key: pattern[:foreign_key],
+            affected_endpoints: serialize_endpoints(pattern[:endpoints]),
+            fix: serialize_fix(pattern[:fix_suggestion])
+          }
+        end
+
+        def serialize_endpoints(endpoints)
+          endpoints
+            .sort_by { |_, count| -count }
+            .map { |endpoint, count| { endpoint: endpoint, request_count: count } }
+        end
+
+        def serialize_fix(suggestion)
+          {
+            code: suggestion[:code],
+            description: suggestion[:description],
+            owner: suggestion[:owner],
+            association: suggestion[:association]
+          }
+        end
+      end
+
+      ToolRegistry.register(GetN1Queries)
+    end
+  end
+end

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

@@ -0,0 +1,143 @@
+module RailsVitals
+  module MCP
+    module Tools
+      class GetScore < Base
+        include Calculable
+        TOOL_NAME = "railsvitals_get_score"
+
+        DESCRIPTION = <<~DESC.strip
+          Returns the composite health score for the Rails app based on recent requests
+          recorded by RailsVitals. Includes a grade, per-component score breakdown
+          (query count and N+1 patterns), penalty details, and a projected score that
+          shows how much improvement fixing all N+1 patterns would yield.
+          Call this first to get a high-level diagnosis before drilling into specifics.
+        DESC
+
+        INPUT_SCHEMA = {
+          type: "object",
+          properties: {}
+        }.freeze
+
+        WEIGHTS = Scorers::CompositeScorer::WEIGHTS
+
+        def call(_params)
+          records = RailsVitals.store.all
+
+          return no_data_response if records.empty?
+
+          overall_score = average(records, :score)
+
+          {
+            overall_score: overall_score,
+            grade: grade_for(overall_score),
+            color: color_for(overall_score),
+            requests_analyzed: records.size,
+            score_breakdown: build_score_breakdown(records),
+            penalties: build_penalties(records),
+            projected_score_if_n1_fixed: projected_score(records)
+          }
+        end
+
+        private
+
+        def no_data_response
+          {
+            overall_score: nil,
+            grade: "No data",
+            color: "grey",
+            requests_analyzed: 0,
+            message: "No requests recorded yet. Make some requests to the app first."
+          }
+        end
+
+        def build_score_breakdown(records)
+          avg_n1 = avg_n1_score(records)
+          avg_query = avg_query_score(records)
+
+          {
+            query_component: {
+              weight: WEIGHTS[:query],
+              avg_score: avg_query,
+              avg_contribution: (avg_query * WEIGHTS[:query]).round(1)
+            },
+            n1_component: {
+              weight: WEIGHTS[:n_plus_one],
+              avg_score: avg_n1,
+              avg_contribution: (avg_n1 * WEIGHTS[:n_plus_one]).round(1)
+            }
+          }
+        end
+
+        def build_penalties(records)
+          warn_threshold = RailsVitals.config.query_warn_threshold
+          db_warn_ms = RailsVitals.config.db_time_warn_ms
+
+          n1_affected = records.select { |r| r.n_plus_one_patterns.any? }
+          total_patterns = records.sum { |r| r.n_plus_one_patterns.size }
+          unique_patterns = records.flat_map { |r| r.n_plus_one_patterns.keys }.uniq.size
+
+          {
+            n1_patterns: {
+              requests_affected: n1_affected.size,
+              percentage_requests: percentage(n1_affected.size, records.size),
+              unique_patterns: unique_patterns,
+              total_occurrences: total_patterns
+            },
+            high_query_count: {
+              requests_above_threshold: records.count { |r| r.total_query_count > warn_threshold },
+              threshold: warn_threshold
+            },
+            slow_db_time: {
+              requests_above_threshold: records.count { |r| r.total_db_time_ms > db_warn_ms },
+              threshold_ms: db_warn_ms
+            }
+          }
+        end
+
+        # What the average composite score would be if every request had zero N+1 patterns.
+        # Formula: composite_now = query_contribution + n1_contribution
+        #          projected = composite_now - n1_contribution + (100 * WEIGHTS[:n_plus_one])
+        def projected_score(records)
+          gain_per_record = records.map do |r|
+            n1_now = n1_score_for(r)
+            ((100 - n1_now) * WEIGHTS[:n_plus_one]).round(1)
+          end
+
+          avg_gain = gain_per_record.sum.to_f / gain_per_record.size
+          (average(records, :score) + avg_gain).round.clamp(0, 100)
+        end
+
+        def n1_score_for(record)
+          Scorers::NPlusOneScorer.score_for(record.n_plus_one_patterns.size)
+        end
+
+        def avg_n1_score(records)
+          (records.sum { |r| n1_score_for(r) }.to_f / records.size).round(1)
+        end
+
+        # Back-calculates query score from composite and N+1 scores.
+        # composite = (query_score * W_query).round + (n1_score * W_n1).round
+        # Approximation is sufficient for AI context.
+        def query_score_for(record)
+          n1_contribution = (n1_score_for(record) * WEIGHTS[:n_plus_one]).round
+          query_contribution = record.score - n1_contribution
+          (query_contribution.to_f / WEIGHTS[:query]).round(1).clamp(0, 100)
+        end
+
+        def avg_query_score(records)
+          (records.sum { |r| query_score_for(r) }.to_f / records.size).round(1)
+        end
+
+        def grade_for(score)
+          Scorers::BaseScorer.label_for(score)
+        end
+
+        def color_for(score)
+          Scorers::BaseScorer.color_for(score)
+        end
+      end
+
+      ToolRegistry.register(GetScore)
+    end
+  end
+end

data/lib/rails_vitals/playground/sandbox.rb

@@ -199,7 +199,7 @@ module RailsVitals
       end
 
       def self.score_n1(count)
-        [ 100 - (count * 25), 0 ].max
+        Scorers::NPlusOneScorer.score_for(count)
       end
 
       def self.blocked_result(message)

data/lib/rails_vitals/scorers/base_scorer.rb

@@ -6,6 +6,24 @@ module RailsVitals
       WARNING = (50..69)
       CRITICAL = (0..49)
 
+      def self.label_for(score)
+        case score
+        when HEALTHY    then "Healthy"
+        when ACCEPTABLE then "Acceptable"
+        when WARNING    then "Warning"
+        else                 "Critical"
+        end
+      end
+
+      def self.color_for(score)
+        case score
+        when HEALTHY    then "green"
+        when ACCEPTABLE then "blue"
+        when WARNING    then "amber"
+        else                 "red"
+        end
+      end
+
       def initialize(collector)
         @collector = collector
       end

data/lib/rails_vitals/scorers/composite_scorer.rb

@@ -15,21 +15,11 @@ module RailsVitals
       end
 
       def label
-        case score
-        when BaseScorer::HEALTHY    then "Healthy"
-        when BaseScorer::ACCEPTABLE then "Acceptable"
-        when BaseScorer::WARNING    then "Warning"
-        else                             "Critical"
-        end
+        BaseScorer.label_for(score)
       end
 
       def color
-        case score
-        when BaseScorer::HEALTHY    then "green"
-        when BaseScorer::ACCEPTABLE then "blue"
-        when BaseScorer::WARNING    then "amber"
-        else                             "red"
-        end
+        BaseScorer.color_for(score)
       end
     end
   end

data/lib/rails_vitals/scorers/n_plus_one_scorer.rb

@@ -4,11 +4,12 @@ module RailsVitals
       # Minimum times the same query must repeat to be flagged
       REPEAT_THRESHOLD = 3
 
-      def score
-        return 100 if n_plus_one_count.zero?
+      def self.score_for(pattern_count)
+        [ 100 - (pattern_count * 25), 0 ].max
+      end
 
-        # Each N+1 pattern costs 25 points, floored at 0
-        clamp(100 - (n_plus_one_count * 25))
+      def score
+        self.class.score_for(n_plus_one_count)
       end
 
       def n_plus_one_patterns

data/lib/rails_vitals/version.rb

@@ -1,3 +1,3 @@
 module RailsVitals
-  VERSION = "0.4.2"
+  VERSION = "0.5.0"
 end

data/lib/rails_vitals.rb

@@ -1,5 +1,6 @@
 require "rails_vitals/version"
 require "rails_vitals/configuration"
+require "rails_vitals/calculable"
 require "rails_vitals/store"
 require "rails_vitals/collector"
 require "rails_vitals/request_record"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_vitals
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.5.0
 platform: ruby
 authors:
 - David Sanchez
@@ -45,6 +45,7 @@ files:
 - app/controllers/rails_vitals/dashboard_controller.rb
 - app/controllers/rails_vitals/explains_controller.rb
 - app/controllers/rails_vitals/heatmap_controller.rb
+- app/controllers/rails_vitals/mcp_controller.rb
 - app/controllers/rails_vitals/models_controller.rb
 - app/controllers/rails_vitals/n_plus_ones_controller.rb
 - app/controllers/rails_vitals/playgrounds_controller.rb
@@ -75,10 +76,18 @@ files:
 - lib/rails_vitals/analyzers/explain_analyzer.rb
 - lib/rails_vitals/analyzers/n_plus_one_aggregator.rb
 - lib/rails_vitals/analyzers/sql_tokenizer.rb
+- lib/rails_vitals/calculable.rb
 - lib/rails_vitals/collector.rb
 - lib/rails_vitals/configuration.rb
 - lib/rails_vitals/engine.rb
 - lib/rails_vitals/instrumentation/callback_instrumentation.rb
+- lib/rails_vitals/mcp/auth.rb
+- lib/rails_vitals/mcp/request_handler.rb
+- 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/get_n1_queries.rb
+- lib/rails_vitals/mcp/tools/get_score.rb
 - lib/rails_vitals/middleware/panel_injector.rb
 - lib/rails_vitals/notifications/subscriber.rb
 - lib/rails_vitals/panel_renderer.rb