rails-profiler 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0cc5830bdf15d65e477e4d7acc5df46262d83737e76962dc4df5af36f6f113f8
-  data.tar.gz: 81abb0423f31141e915776ebcc77819b2d50e48aa13ec44c4ea11a906ad07ccf
+  metadata.gz: a118e9ba5a79bc87f82ee566e0e2af65a7199fff6694561ad080f990fb7bf8cd
+  data.tar.gz: 44e2391b361cbcda4ea4a133fefb7db653cd2f0a48e72859216c368ce1867ded
 SHA512:
-  metadata.gz: 1be16066652bfa11550b5d277d3370eec2457d08dfbb0ceab46ebafe12a484cc342c61892133b030ab4b6d7d1506bcbe53ff8118eaa9ee4ee759c36012a0058e
-  data.tar.gz: a72957818f9d2a7dbdd914f57167ffd0bcfb6eef7df3dfb721a7a651f3acd89536d11cec4dbfa7c47f72f3331862b3279eb0312a7c66a0fbb47bb36e35c1640c
+  metadata.gz: c69ecc008b9b9c79161cdc18326c9b0c43e99b7a7284b2681980c0c2d2b7a94c10f77dc186b2826f2cf111f53063e10a3790c4245e4c8a4a07bdde7f49b02e7a
+  data.tar.gz: 22031e28d3fc173b52dab71ed8f1fe8f0faf350134ed683b2847d1ad3a4e44e5de438b6de76d83a3f2b554aa22175cee5b578af0aacc4a8b247f2fd32390d431

data/app/assets/builds/profiler.css

@@ -867,6 +867,217 @@ tr:hover .btn-row-delete {
   line-height: 1.5;
 }
 
+.profiler-query-card--n1 {
+  border-left: 3px solid var(--profiler-warning);
+  background: var(--profiler-warning-bg);
+}
+
+.profiler-n1-group {
+  border: 1px solid var(--profiler-warning);
+  border-radius: var(--profiler-radius-md);
+  overflow: hidden;
+}
+.profiler-n1-group__header {
+  display: flex;
+  align-items: center;
+  gap: var(--profiler-space-3);
+  padding: var(--profiler-space-2) var(--profiler-space-3);
+  background: var(--profiler-warning-bg);
+  cursor: pointer;
+  user-select: none;
+}
+.profiler-n1-group__header:hover {
+  filter: brightness(0.97);
+}
+.profiler-n1-group__count {
+  font-size: var(--profiler-text-xs);
+  font-weight: 700;
+  font-family: var(--profiler-font-mono);
+  color: var(--profiler-warning);
+  white-space: nowrap;
+}
+.profiler-n1-group__pattern {
+  flex: 1;
+  font-size: var(--profiler-text-xs);
+  font-family: var(--profiler-font-mono);
+  color: var(--profiler-text);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.profiler-n1-group__toggle {
+  font-size: var(--profiler-text-xs);
+  color: var(--profiler-text-muted);
+  white-space: nowrap;
+}
+
+.profiler-n1-backtrace {
+  background: var(--profiler-bg-lighter);
+  border-top: 1px solid var(--profiler-border);
+  padding: var(--profiler-space-2) var(--profiler-space-3);
+}
+.profiler-n1-backtrace__frame {
+  font-size: var(--profiler-text-xs);
+  font-family: var(--profiler-font-mono);
+  color: var(--profiler-text-muted);
+  line-height: 1.8;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.profiler-alert-banner {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--profiler-space-3);
+  padding: var(--profiler-space-3) var(--profiler-space-4);
+  border-radius: var(--profiler-radius-md);
+  border: 1px solid;
+  font-size: var(--profiler-text-sm);
+}
+.profiler-alert-banner--warning {
+  background: var(--profiler-warning-bg);
+  border-color: var(--profiler-warning);
+  color: var(--profiler-text);
+}
+.profiler-alert-banner--error {
+  background: var(--profiler-error-bg);
+  border-color: var(--profiler-error);
+}
+.profiler-alert-banner__icon {
+  flex-shrink: 0;
+  font-size: var(--profiler-text-base);
+}
+
+.profiler-badge {
+  display: inline-block;
+  padding: 1px 6px;
+  border-radius: var(--profiler-radius-sm);
+  font-size: var(--profiler-text-xs);
+  font-weight: 600;
+  font-family: var(--profiler-font-mono);
+  line-height: 1.6;
+}
+.profiler-badge--warning {
+  background: var(--profiler-warning-bg);
+  color: var(--profiler-warning);
+  border: 1px solid rgba(251, 146, 60, 0.3);
+}
+.profiler-badge--error {
+  background: var(--profiler-error-bg);
+  color: var(--profiler-error);
+}
+
+.profiler-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--profiler-space-1);
+  border: 1px solid var(--profiler-border);
+  border-radius: var(--profiler-radius-sm);
+  background: var(--profiler-bg-elevated);
+  color: var(--profiler-text-muted);
+  font-size: var(--profiler-text-sm);
+  font-family: var(--profiler-font-mono);
+  cursor: pointer;
+  transition: all var(--profiler-transition-base);
+}
+.profiler-btn:hover {
+  border-color: var(--profiler-accent);
+  color: var(--profiler-accent);
+}
+.profiler-btn--sm {
+  padding: 1px 8px;
+  font-size: var(--profiler-text-xs);
+}
+
+.profiler-modal__overlay {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.6);
+  z-index: 9000;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: var(--profiler-space-4);
+}
+
+.profiler-modal {
+  background: var(--profiler-bg-elevated);
+  border: 1px solid var(--profiler-border);
+  border-radius: var(--profiler-radius-lg, var(--profiler-radius-md));
+  box-shadow: var(--profiler-shadow-lg, var(--profiler-shadow-sm));
+  width: 100%;
+  max-width: 760px;
+  max-height: 80vh;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+.profiler-modal__header {
+  display: flex;
+  align-items: center;
+  gap: var(--profiler-space-3);
+  padding: var(--profiler-space-3) var(--profiler-space-4);
+  border-bottom: 1px solid var(--profiler-border);
+  background: var(--profiler-bg-light);
+  flex-shrink: 0;
+}
+.profiler-modal__title {
+  font-weight: 600;
+  font-family: var(--profiler-font-mono);
+  font-size: var(--profiler-text-sm);
+  flex: 1;
+}
+.profiler-modal__close {
+  background: none;
+  border: none;
+  color: var(--profiler-text-muted);
+  font-size: var(--profiler-text-lg);
+  cursor: pointer;
+  padding: 0 var(--profiler-space-1);
+  line-height: 1;
+}
+.profiler-modal__close:hover {
+  color: var(--profiler-text);
+}
+.profiler-modal__body {
+  padding: var(--profiler-space-4);
+  overflow-y: auto;
+  flex: 1;
+}
+
+.profiler-explain-result {
+  font-family: var(--profiler-font-mono);
+  font-size: var(--profiler-text-xs);
+  color: var(--profiler-text);
+  white-space: pre-wrap;
+  word-break: break-all;
+  line-height: 1.6;
+  margin: 0;
+}
+
+.profiler-explain-node {
+  padding: var(--profiler-space-1) var(--profiler-space-2);
+  margin-bottom: 2px;
+  border-radius: var(--profiler-radius-sm);
+  font-family: var(--profiler-font-mono);
+  font-size: var(--profiler-text-xs);
+}
+.profiler-explain-node--expensive {
+  background: var(--profiler-error-bg);
+  border-left: 2px solid var(--profiler-error);
+}
+.profiler-explain-node__type {
+  font-weight: 600;
+  color: var(--profiler-accent);
+}
+.profiler-explain-node__stats {
+  display: flex;
+  gap: var(--profiler-space-3);
+  margin-top: 1px;
+  flex-wrap: wrap;
+}
+
 .profiler-dump-card {
   background: var(--profiler-bg-light);
   border: 1px solid var(--profiler-border);

data/app/assets/builds/profiler.js

@@ -1263,10 +1263,154 @@
   }
 
   // app/assets/typescript/profiler/components/dashboard/tabs/DatabaseTab.tsx
-  function DatabaseTab({ dbData }) {
+  function normalizeSql(sql) {
+    return sql.replace(/\$\d+/g, "?").replace(/\b\d+\b/g, "?").replace(/'[^']*'/g, "?").replace(/"[^"]*"/g, "?").trim();
+  }
+  function computeN1Groups(queries) {
+    const groups = /* @__PURE__ */ new Map();
+    queries.forEach((query, index) => {
+      if (query.cached || query.transaction) return;
+      const pattern = normalizeSql(query.sql);
+      if (!groups.has(pattern)) {
+        groups.set(pattern, { indices: [], backtrace: query.backtrace ?? [] });
+      }
+      groups.get(pattern).indices.push(index);
+    });
+    const result = [];
+    groups.forEach(({ indices, backtrace }, pattern) => {
+      if (indices.length >= 3) {
+        result.push({ pattern, indices, backtrace });
+      }
+    });
+    return result.sort((a3, b) => b.indices.length - a3.indices.length);
+  }
+  function renderPlanNode(node, depth = 0) {
+    const type = node["Node Type"] ?? "";
+    const actualRows = node["Actual Rows"] ?? 0;
+    const planRows = node["Plan Rows"] ?? 1;
+    const isExpensive = type.includes("Seq Scan") || type.includes("Hash Join") || type.includes("Nested Loop") || type.includes("Filter") || actualRows > 0 && planRows > 0 && actualRows > planRows * 10;
+    const children = node["Plans"] ?? [];
+    return /* @__PURE__ */ u3("div", { class: `profiler-explain-node${isExpensive ? " profiler-explain-node--expensive" : ""}`, style: `margin-left:${depth * 14}px`, children: [
+      /* @__PURE__ */ u3("span", { class: "profiler-explain-node__type", children: type }),
+      node["Relation Name"] && /* @__PURE__ */ u3("span", { class: "profiler-text--muted", children: [
+        " on ",
+        node["Relation Name"]
+      ] }),
+      node["Index Name"] && /* @__PURE__ */ u3("span", { class: "profiler-text--muted", children: [
+        " using ",
+        node["Index Name"]
+      ] }),
+      /* @__PURE__ */ u3("div", { class: "profiler-explain-node__stats profiler-text--xs profiler-text--muted", children: [
+        node["Actual Total Time"] != null && /* @__PURE__ */ u3("span", { children: [
+          "time: ",
+          node["Actual Total Time"].toFixed(3),
+          "ms"
+        ] }),
+        node["Actual Rows"] != null && /* @__PURE__ */ u3("span", { children: [
+          "rows: ",
+          actualRows,
+          " (est: ",
+          planRows,
+          ")"
+        ] }),
+        node["Total Cost"] != null && /* @__PURE__ */ u3("span", { children: [
+          "cost: ",
+          node["Total Cost"].toFixed(2)
+        ] }),
+        node["Filter"] && /* @__PURE__ */ u3("span", { class: "profiler-text--warning", children: [
+          "filter: ",
+          node["Filter"]
+        ] })
+      ] }),
+      children.map((child, i3) => renderPlanNode(child, depth + 1))
+    ] });
+  }
+  function ExplainModal({ state, onClose }) {
+    if (!state.open) return null;
+    const renderResult = () => {
+      if (state.loading) return /* @__PURE__ */ u3("div", { class: "profiler-text--muted", children: "Running EXPLAIN ANALYZE\u2026" });
+      if (state.error) return /* @__PURE__ */ u3("div", { class: "profiler-text--error", children: state.error });
+      if (!state.result) return null;
+      if (state.format === "json") {
+        try {
+          const parsed = typeof state.result === "string" ? JSON.parse(state.result) : state.result;
+          const plans = Array.isArray(parsed) ? parsed : [parsed];
+          return /* @__PURE__ */ u3("div", { class: "profiler-explain-result", children: plans.map((entry, i3) => /* @__PURE__ */ u3("div", { children: [
+            renderPlanNode(entry["Plan"] ?? entry),
+            entry["Planning Time"] != null && /* @__PURE__ */ u3("div", { class: "profiler-text--xs profiler-text--muted profiler-mt-2", children: [
+              "Planning: ",
+              entry["Planning Time"].toFixed(3),
+              "ms",
+              entry["Execution Time"] != null && /* @__PURE__ */ u3(k, { children: [
+                " \xB7 Execution: ",
+                entry["Execution Time"].toFixed(3),
+                "ms"
+              ] })
+            ] })
+          ] }, i3)) });
+        } catch {
+          return /* @__PURE__ */ u3("pre", { class: "profiler-explain-result", children: String(state.result) });
+        }
+      }
+      return /* @__PURE__ */ u3("pre", { class: "profiler-explain-result", children: String(state.result) });
+    };
+    return /* @__PURE__ */ u3("div", { class: "profiler-modal__overlay", onClick: onClose, children: /* @__PURE__ */ u3("div", { class: "profiler-modal", onClick: (e3) => e3.stopPropagation(), children: [
+      /* @__PURE__ */ u3("div", { class: "profiler-modal__header", children: [
+        /* @__PURE__ */ u3("span", { class: "profiler-modal__title", children: "EXPLAIN ANALYZE" }),
+        /* @__PURE__ */ u3("span", { class: "profiler-text--xs profiler-text--muted", children: state.adapter }),
+        /* @__PURE__ */ u3("button", { class: "profiler-modal__close", onClick: onClose, children: "\xD7" })
+      ] }),
+      /* @__PURE__ */ u3("div", { class: "profiler-modal__body", children: renderResult() })
+    ] }) });
+  }
+  function DatabaseTab({ dbData, token }) {
+    const [openBacktraces, setOpenBacktraces] = d2(/* @__PURE__ */ new Set());
+    const [explainState, setExplainState] = d2({
+      open: false,
+      loading: false,
+      result: null,
+      format: "text",
+      adapter: "",
+      error: null
+    });
     if (!dbData?.queries) {
       return /* @__PURE__ */ u3("div", { class: "profiler-empty", children: /* @__PURE__ */ u3("p", { class: "profiler-empty__description", children: "No database queries recorded" }) });
     }
+    const n1Groups = computeN1Groups(dbData.queries);
+    const n1IndexSet = new Set(n1Groups.flatMap((g2) => g2.indices));
+    const toggleBacktrace = (pattern) => {
+      setOpenBacktraces((prev) => {
+        const next = new Set(prev);
+        next.has(pattern) ? next.delete(pattern) : next.add(pattern);
+        return next;
+      });
+    };
+    const runExplain = async (queryIndex) => {
+      setExplainState({ open: true, loading: true, result: null, format: "text", adapter: "", error: null });
+      try {
+        const res = await fetch("/_profiler/api/explain", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ token, query_index: queryIndex })
+        });
+        if (!res.ok) {
+          const body = await res.json().catch(() => ({}));
+          setExplainState((s3) => ({ ...s3, loading: false, error: body.error ?? `HTTP ${res.status}` }));
+          return;
+        }
+        const data = await res.json();
+        setExplainState((s3) => ({
+          ...s3,
+          loading: false,
+          result: data.result,
+          format: data.format ?? "text",
+          adapter: data.adapter ?? ""
+        }));
+      } catch (err) {
+        setExplainState((s3) => ({ ...s3, loading: false, error: err.message ?? "Request failed" }));
+      }
+    };
+    const closeExplain = () => setExplainState((s3) => ({ ...s3, open: false }));
     return /* @__PURE__ */ u3(k, { children: [
       /* @__PURE__ */ u3("h2", { class: "profiler-section__header", children: [
         "Database Queries (",
@@ -1290,19 +1434,60 @@
           /* @__PURE__ */ u3("strong", { children: dbData.cached_queries })
         ] })
       ] }),
-      dbData.queries.map((query, index) => /* @__PURE__ */ u3("div", { class: `profiler-query-card${query.slow ? " profiler-query-card--slow" : ""}`, children: [
+      n1Groups.length > 0 && /* @__PURE__ */ u3("div", { class: "profiler-alert-banner profiler-alert-banner--warning profiler-mb-4", children: [
+        /* @__PURE__ */ u3("span", { class: "profiler-alert-banner__icon", children: "\u26A0\uFE0F" }),
+        /* @__PURE__ */ u3("div", { children: [
+          /* @__PURE__ */ u3("strong", { children: "Potential N+1 detected" }),
+          " \u2014 ",
+          n1Groups.length,
+          " pattern",
+          n1Groups.length > 1 ? "s" : "",
+          " repeated ",
+          n1Groups.reduce((sum, g2) => sum + g2.indices.length, 0),
+          " times total",
+          /* @__PURE__ */ u3("div", { class: "profiler-text--xs profiler-text--muted profiler-mt-1", children: "Queries causing N+1 are highlighted below. Expand each group to see the call stack." })
+        ] })
+      ] }),
+      n1Groups.map((group) => /* @__PURE__ */ u3("div", { class: "profiler-n1-group profiler-mb-4", children: [
+        /* @__PURE__ */ u3("div", { class: "profiler-n1-group__header", onClick: () => toggleBacktrace(group.pattern), children: [
+          /* @__PURE__ */ u3("span", { class: "profiler-n1-group__count", children: [
+            "N+1 \xB7 ",
+            group.indices.length,
+            "\xD7"
+          ] }),
+          /* @__PURE__ */ u3("code", { class: "profiler-n1-group__pattern", children: group.pattern }),
+          /* @__PURE__ */ u3("span", { class: "profiler-n1-group__toggle", children: [
+            openBacktraces.has(group.pattern) ? "\u25B2" : "\u25BC",
+            " backtrace"
+          ] })
+        ] }),
+        openBacktraces.has(group.pattern) && group.backtrace.length > 0 && /* @__PURE__ */ u3("div", { class: "profiler-n1-backtrace", children: group.backtrace.map((frame, i3) => /* @__PURE__ */ u3("div", { class: "profiler-n1-backtrace__frame", children: frame }, i3)) })
+      ] }, group.pattern)),
+      dbData.queries.map((query, index) => /* @__PURE__ */ u3("div", { class: [
+        "profiler-query-card",
+        query.slow ? "profiler-query-card--slow" : "",
+        n1IndexSet.has(index) ? "profiler-query-card--n1" : ""
+      ].filter(Boolean).join(" "), children: [
         /* @__PURE__ */ u3("div", { class: "profiler-query-card__header", children: [
-          /* @__PURE__ */ u3("span", { class: "profiler-text--muted", children: [
-            "#",
-            index + 1
+          /* @__PURE__ */ u3("div", { class: "profiler-flex profiler-flex--gap-2", children: [
+            /* @__PURE__ */ u3("span", { class: "profiler-text--muted", children: [
+              "#",
+              index + 1
+            ] }),
+            n1IndexSet.has(index) && /* @__PURE__ */ u3("span", { class: "profiler-badge profiler-badge--warning", children: "N+1" }),
+            query.name && /* @__PURE__ */ u3("span", { class: "profiler-text--xs profiler-text--muted", children: query.name })
           ] }),
-          /* @__PURE__ */ u3("span", { class: `profiler-query-card__duration ${query.slow ? "profiler-query-card__duration--slow" : "profiler-query-card__duration--fast"}`, children: [
-            query.duration.toFixed(2),
-            " ms"
+          /* @__PURE__ */ u3("div", { class: "profiler-flex profiler-flex--gap-2", children: [
+            /* @__PURE__ */ u3("span", { class: `profiler-query-card__duration ${query.slow ? "profiler-query-card__duration--slow" : "profiler-query-card__duration--fast"}`, children: [
+              query.duration.toFixed(2),
+              " ms"
+            ] }),
+            !query.cached && !query.transaction && /* @__PURE__ */ u3("button", { class: "profiler-btn profiler-btn--sm", onClick: () => runExplain(index), children: "Explain" })
           ] })
         ] }),
         /* @__PURE__ */ u3("code", { class: "profiler-query-card__code", children: query.sql })
-      ] }, index))
+      ] }, index)),
+      /* @__PURE__ */ u3(ExplainModal, { state: explainState, onClose: closeExplain })
     ] });
   }
 
@@ -2545,7 +2730,7 @@
           activeTab === "exception" && /* @__PURE__ */ u3(ExceptionTab, { exceptionData: cd["exception"] }),
           activeTab === "request" && /* @__PURE__ */ u3(RequestTab, { profile }),
           activeTab === "dump" && /* @__PURE__ */ u3(DumpsTab, { dumpData: cd["dump"] }),
-          activeTab === "database" && /* @__PURE__ */ u3(DatabaseTab, { dbData: cd["database"] }),
+          activeTab === "database" && /* @__PURE__ */ u3(DatabaseTab, { dbData: cd["database"], token: profile.token }),
           activeTab === "ajax" && /* @__PURE__ */ u3(AjaxTab, { ajaxData: cd["ajax"] }),
           activeTab === "http" && /* @__PURE__ */ u3(HttpTab, { httpData: cd["http"] }),
           activeTab === "timeline" && /* @__PURE__ */ u3(FlameGraphTab, { flamegraphData: cd["flamegraph"], perfData: cd["performance"] }),

data/app/controllers/profiler/api/explain_controller.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "profiler/explain_runner"
+
+module Profiler
+  module Api
+    class ExplainController < ApplicationController
+      skip_before_action :verify_authenticity_token
+
+      def create
+        unless Profiler.configuration.enabled
+          return render json: { error: "EXPLAIN is only available when the profiler is enabled" }, status: :forbidden
+        end
+
+        token       = params[:token].to_s
+        query_index = params[:query_index].to_i
+
+        if token.blank?
+          return render json: { error: "token is required" }, status: :unprocessable_entity
+        end
+
+        result = Profiler::ExplainRunner.run(token, query_index)
+        render json: result
+      rescue ArgumentError => e
+        render json: { error: e.message }, status: :unprocessable_entity
+      rescue => e
+        render json: { error: e.message }, status: :internal_server_error
+      end
+    end
+  end
+end

data/config/routes.rb

@@ -32,5 +32,6 @@ Profiler::Engine.routes.draw do
     resources :outbound_http, only: [:index]
     get "toolbar/:token", to: "toolbar#show"
     post "ajax/link", to: "ajax#link"
+    post "explain", to: "explain#create"
   end
 end

data/lib/profiler/explain_runner.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Profiler
+  # Shared service for running EXPLAIN ANALYZE on a stored query.
+  # Used by both the HTTP API controller and the MCP explain_query tool.
+  module ExplainRunner
+    # @param profile_token [String]
+    # @param query_index   [Integer]
+    # @return [Hash] { result:, format: "json"|"text", adapter: String }
+    #         or raises ArgumentError / RuntimeError
+    def self.run(profile_token, query_index)
+      unless Profiler.configuration.enabled
+        raise SecurityError, "EXPLAIN is only available when the profiler is enabled"
+      end
+
+      profile = Profiler.storage.load(profile_token)
+      raise ArgumentError, "Profile not found: #{profile_token}" unless profile
+
+      db_data = profile.collector_data("database")
+      raise ArgumentError, "No database data in this profile" unless db_data && db_data["queries"]
+
+      queries = db_data["queries"]
+      query_index = query_index.to_i
+      unless query_index >= 0 && query_index < queries.size
+        raise ArgumentError, "Query index #{query_index} out of range (0..#{queries.size - 1})"
+      end
+
+      query = queries[query_index]
+      sql   = query["sql"].to_s
+      binds = Array(query["binds"])
+
+      conn    = ActiveRecord::Base.connection
+      adapter = conn.adapter_name.downcase
+      full_sql = reconstruct_sql(sql, binds, conn, adapter)
+
+      explain_sql, format = build_explain_statement(full_sql, adapter)
+
+      rows = conn.exec_query(explain_sql, "EXPLAIN").to_a
+
+      result = if format == "json"
+        # PostgreSQL / MySQL return JSON in rows[0]["QUERY PLAN"] or rows[0]["EXPLAIN"]
+        raw = rows.first&.values&.first.to_s
+        JSON.parse(raw) rescue raw
+      else
+        rows.map { |r| r.values.join("\t") }.join("\n")
+      end
+
+      { result: result, format: format, adapter: adapter }
+    end
+
+    private
+
+    def self.reconstruct_sql(sql, binds, conn, adapter)
+      return sql if binds.empty?
+
+      if adapter.include?("postgresql")
+        result = sql.dup
+        binds.each_with_index do |value, i|
+          result = result.gsub("$#{i + 1}", conn.quote(value))
+        end
+        result
+      else
+        # MySQL / SQLite: replace ? sequentially
+        result = sql.dup
+        binds.each do |value|
+          result = result.sub("?", conn.quote(value))
+        end
+        result
+      end
+    end
+
+    def self.build_explain_statement(sql, adapter)
+      if adapter.include?("postgresql")
+        ["EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) #{sql}", "json"]
+      elsif adapter.include?("mysql")
+        ["EXPLAIN FORMAT=JSON #{sql}", "json"]
+      else
+        ["EXPLAIN QUERY PLAN #{sql}", "text"]
+      end
+    end
+  end
+end

data/lib/profiler/mcp/body_formatter.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Profiler
+  module MCP
+    module BodyFormatter
+      # Formats a body string for MCP output.
+      #
+      # params keys used:
+      #   "save_bodies"   (boolean) — save to /tmp/rails-profiler/{token}/{name} and return path
+      #   "max_body_size" (number)  — truncate inline body at N chars
+      #   "json_path"     (string)  — JSONPath to extract from body when save_bodies is true
+      #   "xml_path"      (string)  — XPath to extract from body when save_bodies is true
+      #
+      # Returns a formatted string ready to embed in markdown, or nil if body is blank.
+      def self.format_body(token, name, body, encoding, params)
+        return "  *(binary, base64 encoded)*" if encoding == "base64"
+        return nil if body.nil? || body.empty?
+
+        if params["save_bodies"]
+          path = FileCache.save(token, name, body)
+          if path
+            result = "  *(saved → `#{path}`)*"
+            if params["json_path"]
+              extracted = PathExtractor.extract_json(body, params["json_path"])
+              result += "\n  `#{params['json_path']}` → `#{extracted}`"
+            elsif params["xml_path"]
+              extracted = PathExtractor.extract_xml(body, params["xml_path"])
+              result += "\n  `#{params['xml_path']}` → `#{extracted}`"
+            end
+            result
+          else
+            truncate_body(body, params["max_body_size"])
+          end
+        else
+          truncate_body(body, params["max_body_size"])
+        end
+      end
+
+      def self.truncate_body(body, max_size)
+        max = max_size&.to_i
+        content = if max && body.length > max
+          "#{body[0, max]}\n... [truncated, #{body.length} chars total]"
+        else
+          body
+        end
+        "```\n#{content}\n```"
+      end
+    end
+  end
+end

data/lib/profiler/mcp/file_cache.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Profiler
+  module MCP
+    class FileCache
+      BASE_DIR = "/tmp/rails-profiler"
+
+      def self.save(token, name, content)
+        cleanup if rand < 0.05
+
+        dir = File.join(BASE_DIR, token)
+        FileUtils.mkdir_p(dir)
+        path = File.join(dir, name)
+        File.write(path, content)
+        path
+      rescue Errno::EACCES, Errno::EROFS
+        nil
+      end
+
+      def self.cleanup(max_age: 3600)
+        return unless Dir.exist?(BASE_DIR)
+
+        Dir.glob(File.join(BASE_DIR, "*")).each do |dir|
+          FileUtils.rm_rf(dir) if File.directory?(dir) && (Time.now - File.mtime(dir)) > max_age
+        end
+      end
+    end
+  end
+end