pgbus 0.9.4 → 0.9.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f659edeb84f108e166ae2ea981e5eb3e4fabfde1542769a777d9d707aba349d
-  data.tar.gz: 2abf0072cdc0f414670367e4a59881003285c43f895618d1ec63b1b7fca5e27a
+  metadata.gz: 4add7dbee0e372ddbfcb644190f4cb1a564e89c3809ecc0a5c16b6f0ff36a6b9
+  data.tar.gz: c5a028268a5966b2d20849789bdca929451425c7f85ebf98347e298fd91de95f
 SHA512:
-  metadata.gz: c527aa3c60ae917b2589cd23b99f14348fa4eef752ae004b2ffc3a90d248e5c09bc68ee06ddfde3d335c469192dd821551b56bb9b6fb259f6f1b961a61567d9e
-  data.tar.gz: 6f66d58dfe49bca18d3b3a1379e2c458c75954cec3c7fb1ddd23fcfa05e495b00db4d3646d42e32e40b202135e5bb7e51a18d6287ab897e7605fd87250c93391
+  metadata.gz: 83f391a1a0e013a708727f02255b5122dab340f57cdde1b038d77449bc534d30d73296023fafa8cd0985bd1b219a5d7269a6a3ecaba33be24bcd58e846fa1fd0
+  data.tar.gz: f426ac4fcde58e6b6b76154120a9cdfe2bc6efaccdecee72f55fd510a136dd1e0e289e87f912d3b96670b5d8b6531523b551a692c02094e9459ea60e388ed4e8

data/README.md

@@ -838,6 +838,121 @@ When `config.metrics_enabled = true` (default), the dashboard exposes Prometheus
 | `pgbus_worker_pool_busy` | Currently busy worker threads |
 | `pgbus_worker_pool_utilization` | Busy / capacity ratio |
 
+### MCP diagnostic server (read-only)
+
+Pgbus ships an optional, **read-only** [MCP](https://modelcontextprotocol.io) server so an AI agent (or any MCP client) can diagnose pgbus directly — "are queues backed up?", "is `read_ct` advancing?", "are workers heart-beating but not claiming?" — instead of hand-writing `pgmq` / `pg_stat_activity` SQL against production. It is a thin adapter over the same read layer the dashboard uses, so it adds no new database access path.
+
+Add the optional `mcp` gem to your `Gemfile` first (`gem "mcp"`); both entry points below tell you if it's missing.
+
+#### Choosing a deployment
+
+There are two ways to run it, depending on **who connects and from where**:
+
+| | **stdio** (`pgbus mcp`) | **HTTP** (mount in Rails) |
+|---|---|---|
+| Who connects | A local operator (Claude Desktop / Claude Code on your machine) | A remote agent or alerting system |
+| Process model | The MCP client **spawns** a short-lived process on demand | Runs **inside your existing Rails server** — no second process |
+| Reaches production? | Only if run where prod DB creds are available | Yes — co-located with the app, same credentials |
+| Use it for | Hands-on, interactive debugging | Automated/remote diagnostics & alerting |
+
+> **Don't start a second `bin/pgbus` instance for HTTP.** The HTTP transport is a Rack app — mount it in the Rails app you already deploy.
+
+##### stdio (local operator)
+
+```bash
+bundle exec pgbus mcp        # speaks MCP over stdio
+```
+
+##### HTTP (mount in Rails)
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  # ... your routes ...
+  mount Pgbus::MCP.rack_app(token: ENV["PGBUS_MCP_TOKEN"]) => "/pgbus/mcp"
+end
+```
+
+`Pgbus::MCP.rack_app` returns a gated Rack app. It runs the transport in **stateless + JSON-response mode**, so every request is a self-contained POST with no in-memory session — safe behind multiple Puma/Falcon workers (any worker can answer any request). Keep the endpoint on an internal network / behind your VPN; it is not meant to be internet-exposed.
+
+Options:
+
+| Option | Default | Meaning |
+|--------|---------|---------|
+| `token:` | `nil` | Shared secret. When set, requests must send `Authorization: Bearer <token>` (constant-time compared). |
+| `auth:` | `nil` | A callable `->(rack_request) { ... }` returning truthy to allow — mirrors `config.web_auth`. Wins over `token:`. |
+| `allow_payloads:` | `false` | When true, tools honor a per-call `include_payloads` flag (see Security). |
+
+If you set neither `token:` nor `auth:`, pgbus logs a warning — an unauthenticated diagnostic endpoint exposes operational metadata to anyone who can reach it.
+
+> Clients must send `Accept: application/json` and `Content-Type: application/json` on every POST, or the transport replies `406 Not Acceptable`. MCP clients do this automatically.
+
+Need a **standalone HTTP pod** instead of mounting in your main app? The same Rack app works under any Rack server, e.g. a one-line `config.ru`:
+
+```ruby
+require "pgbus"
+Pgbus::MCP.load!
+run Pgbus::MCP.rack_app(token: ENV["PGBUS_MCP_TOKEN"])
+# rackup -p 9293   (run it in a container that shares the app's DB config)
+```
+
+#### Tools
+
+All tools are read-only — no tool mutates state, and there is no raw-SQL passthrough.
+
+| Tool | Purpose |
+|------|---------|
+| `pgbus_health` | One-call verdict: `OK` / `DEGRADED` / `STALLED`. STALLED is the silent-worker-wedge signal (visible backlog while workers heart-beat but don't claim). Suitable for automated alerting. |
+| `pgbus_queues` | All queues: depth, visible count, oldest-message age, paused state. |
+| `pgbus_queue_detail` | Per-queue metrics + paused state + table health (dead tuples, bloat, vacuum age). |
+| `pgbus_processes` | Every process with kind, pid, heartbeat age, and `healthy`/`stale`/`stalled` status. |
+| `pgbus_jobs` / `pgbus_job_detail` | Inspect enqueued messages (`read_ct`, `vt`, `enqueued_at`). Paginated. |
+| `pgbus_dlq` / `pgbus_dlq_detail` | Dead-letter inspection. Paginated. |
+| `pgbus_locks` | Active uniqueness locks (the leaked-lock diagnostic). |
+| `pgbus_throughput` / `pgbus_stats` | Recent throughput time series and status counts. |
+| `pgbus_recurring` | Recurring task schedule + last/next run times. |
+
+#### Security
+
+The server is built to be safe against a production datastore:
+
+- **Read-only by default.** No tool mutates state and no arbitrary-query tool exists.
+- **Payloads redacted.** Message bodies, headers, and job arguments are replaced with `[redacted]` unless payloads are explicitly allowed **and** `include_payloads: true` is passed on the call. Both gates must be open. Allow payloads with `PGBUS_MCP_ALLOW_PAYLOADS=1` (stdio) or `Pgbus::MCP.rack_app(allow_payloads: true)` (HTTP).
+- **Bounded queries.** Every list tool paginates with a row cap (`pgbus_jobs` / `pgbus_dlq` cap at 100 rows/page; time windows cap at 1440 minutes).
+- **Reuses your DB credentials.** No new privileged path — it reads through the app's existing connection config.
+- **Authentication.**
+  - *HTTP:* set `token:` (clients send `Authorization: Bearer <token>`) or a custom `auth:` callable; unauthenticated requests get `401`.
+  - *stdio:* the channel is local (the client spawns the process), so the gate is a boot-time precondition — set `PGBUS_MCP_TOKEN` and the server refuses to start unless `PGBUS_MCP_AUTH_TOKEN` matches (constant-time compare).
+
+#### Client configuration
+
+For the **stdio** transport, a minimal MCP client config (Claude Code / Claude Desktop style):
+
+```json
+{
+  "mcpServers": {
+    "pgbus": {
+      "command": "bundle",
+      "args": ["exec", "pgbus", "mcp"],
+      "env": { "RAILS_ENV": "production" }
+    }
+  }
+}
+```
+
+For the **HTTP** transport, point the client at the mounted URL with a streamable-HTTP server config, sending the bearer token, e.g.:
+
+```json
+{
+  "mcpServers": {
+    "pgbus": {
+      "url": "https://your-app.internal/pgbus/mcp",
+      "headers": { "Authorization": "Bearer ${PGBUS_MCP_TOKEN}" }
+    }
+  }
+}
+```
+
 ## Real-time broadcasts (turbo-streams replacement)
 
 Pgbus ships a drop-in replacement for turbo-rails' `turbo_stream_from` helper that fixes several well-known ActionCable correctness bugs by using PGMQ message IDs as a replay cursor. Same API as turbo-rails. No Redis. No ActionCable. No lost messages on reconnect.

data/app/helpers/pgbus/application_helper.rb

@@ -29,10 +29,20 @@ module Pgbus
       end
     end
 
-    def pgbus_status_badge(healthy)
-      if healthy
+    def pgbus_status_badge(healthy_or_status)
+      status = case healthy_or_status
+               when true then :healthy
+               when Symbol, String then healthy_or_status.to_sym
+               else :stale
+               end
+
+      case status
+      when :healthy
         tag.span(I18n.t("pgbus.helpers.status_badge.healthy"),
                  class: "inline-flex items-center rounded-full bg-green-100 px-2.5 py-0.5 text-xs font-medium text-green-800")
+      when :stalled
+        tag.span(I18n.t("pgbus.helpers.status_badge.stalled"),
+                 class: "inline-flex items-center rounded-full bg-yellow-100 px-2.5 py-0.5 text-xs font-medium text-yellow-800")
       else
         tag.span(I18n.t("pgbus.helpers.status_badge.stale"),
                  class: "inline-flex items-center rounded-full bg-red-100 px-2.5 py-0.5 text-xs font-medium text-red-800")

data/app/views/pgbus/dashboard/_processes_table.html.erb

@@ -17,7 +17,7 @@
               <td data-label="Kind" class="px-4 py-3 text-sm font-medium text-gray-900 dark:text-white"><%= p[:kind] %></td>
               <td data-label="Host" class="px-4 py-3 text-sm text-gray-500"><%= p[:hostname] %></td>
               <td data-label="PID" class="px-4 py-3 text-sm text-gray-500"><%= p[:pid] %></td>
-              <td data-label="Status" class="px-4 py-3 text-sm"><%= pgbus_status_badge(p[:healthy]) %></td>
+              <td data-label="Status" class="px-4 py-3 text-sm"><%= pgbus_status_badge(p[:status] || p[:healthy]) %></td>
             </tr>
           <% end %>
           <% if @processes.empty? %>

data/app/views/pgbus/processes/_processes_table.html.erb

@@ -17,7 +17,7 @@
             <td data-label="Kind" class="px-4 py-3 text-sm font-medium text-gray-900 dark:text-white"><%= p[:kind] %></td>
             <td data-label="Host" class="px-4 py-3 text-sm text-gray-700"><%= p[:hostname] %></td>
             <td data-label="PID" class="px-4 py-3 text-sm font-mono text-gray-700"><%= p[:pid] %></td>
-            <td data-label="Status" class="px-4 py-3 text-sm"><%= pgbus_status_badge(p[:healthy]) %></td>
+            <td data-label="Status" class="px-4 py-3 text-sm"><%= pgbus_status_badge(p[:status] || p[:healthy]) %></td>
             <td data-label="Last Heartbeat" class="px-4 py-3 text-sm text-gray-500"><%= pgbus_time_ago(p[:last_heartbeat_at]) %></td>
             <td data-label="Metadata" class="px-4 py-3 text-sm text-gray-500 font-mono text-xs max-w-xs truncate">
               <% if p[:metadata].is_a?(Hash) %>

data/config/locales/da.yml

@@ -235,6 +235,7 @@ da:
       status_badge:
         healthy: Sund
         stale: Forældet
+        stalled: Gået i stå
     insights:
       show:
         charts:

data/config/locales/de.yml

@@ -235,6 +235,7 @@ de:
       status_badge:
         healthy: Gesund
         stale: Veraltet
+        stalled: Blockiert
     insights:
       show:
         charts:

data/config/locales/en.yml

@@ -235,6 +235,7 @@ en:
       status_badge:
         healthy: Healthy
         stale: Stale
+        stalled: Stalled
     insights:
       show:
         charts:

data/config/locales/es.yml

@@ -235,6 +235,7 @@ es:
       status_badge:
         healthy: Saludable
         stale: Obsoleto
+        stalled: Bloqueado
     insights:
       show:
         charts:

data/config/locales/fi.yml

@@ -235,6 +235,7 @@ fi:
       status_badge:
         healthy: Toimiva
         stale: Vanha
+        stalled: Juuttunut
     insights:
       show:
         charts:

data/config/locales/fr.yml

@@ -235,6 +235,7 @@ fr:
       status_badge:
         healthy: Sain
         stale: Obsolète
+        stalled: Bloqué
     insights:
       show:
         charts:

data/config/locales/it.yml

@@ -235,6 +235,7 @@ it:
       status_badge:
         healthy: Sano
         stale: Obsoleto
+        stalled: Bloccato
     insights:
       show:
         charts:

data/config/locales/ja.yml

@@ -235,6 +235,7 @@ ja:
       status_badge:
         healthy: 正常
         stale: 期限切れ
+        stalled: 停滞
     insights:
       show:
         charts:

data/config/locales/nb.yml

@@ -235,6 +235,7 @@ nb:
       status_badge:
         healthy: Sunn
         stale: Utdatert
+        stalled: Fastlåst
     insights:
       show:
         charts:

data/config/locales/nl.yml

@@ -235,6 +235,7 @@ nl:
       status_badge:
         healthy: Gezond
         stale: Verouderd
+        stalled: Vastgelopen
     insights:
       show:
         charts:

data/config/locales/pt.yml

@@ -235,6 +235,7 @@ pt:
       status_badge:
         healthy: Saudável
         stale: Obsoleto
+        stalled: Bloqueado
     insights:
       show:
         charts:

data/config/locales/sv.yml

@@ -235,6 +235,7 @@ sv:
       status_badge:
         healthy: Hälsosam
         stale: Föråldrad
+        stalled: Fastlåst
     insights:
       show:
         charts:

data/lib/pgbus/cli.rb

@@ -16,6 +16,8 @@ module Pgbus
         show_status
       when "queues"
         list_queues
+      when "mcp"
+        start_mcp_server
       when "version"
         puts "pgbus #{Pgbus::VERSION}"
       when "help", "--help", "-h"
@@ -132,6 +134,13 @@ module Pgbus
       end
     end
 
+    # Boots the read-only MCP diagnostic server over stdio. Loaded lazily so
+    # the optional `mcp` gem is only required when this command is invoked.
+    def start_mcp_server
+      Pgbus::MCP.load!
+      Pgbus::MCP::Runner.run
+    end
+
     def list_queues
       Pgbus.client.list_queues
       metrics = Pgbus.client.metrics
@@ -154,6 +163,7 @@ module Pgbus
           start    Start the Pgbus supervisor (workers + dispatcher)
           status   Show running Pgbus processes
           queues   List queues with metrics
+          mcp      Start the read-only MCP diagnostic server over stdio
           version  Show version
           help     Show this help
 
@@ -172,6 +182,12 @@ module Pgbus
                              pattern)
           --execution-mode   Execution mode: threads (default) or async
                              (fiber-based, lower connection usage)
+
+        Environment for `mcp`:
+          PGBUS_MCP_TOKEN          If set, PGBUS_MCP_AUTH_TOKEN must match for
+                                   the server to start (optional token gate).
+          PGBUS_MCP_ALLOW_PAYLOADS Truthy to let tools return raw message
+                                   bodies/headers (off by default; redacted).
       HELP
     end
   end

data/lib/pgbus/client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "timeout"
 require_relative "client/read_after"
 require_relative "client/ensure_stream_queue"
 require_relative "client/notify_stream"
@@ -110,7 +111,7 @@ module Pgbus
       full_name = config.queue_name(queue_name)
       Instrumentation.instrument("pgbus.client.read_message", queue: full_name) do
         with_stale_connection_retry do
-          synchronized { @pgmq.read(full_name, vt: vt || config.visibility_timeout) }
+          synchronized { with_read_timeout { @pgmq.read(full_name, vt: vt || config.visibility_timeout) } }
         end
       end
     end
@@ -119,7 +120,7 @@ module Pgbus
       full_name = config.queue_name(queue_name)
       Instrumentation.instrument("pgbus.client.read_batch", queue: full_name, qty: qty) do
         with_stale_connection_retry do
-          synchronized { @pgmq.read_batch(full_name, vt: vt || config.visibility_timeout, qty: qty) }
+          synchronized { with_read_timeout { @pgmq.read_batch(full_name, vt: vt || config.visibility_timeout, qty: qty) } }
         end
       end
     end
@@ -141,7 +142,7 @@ module Pgbus
 
         msgs = Instrumentation.instrument("pgbus.client.read_batch", queue: pq_name, qty: remaining) do
           with_stale_connection_retry do
-            synchronized { @pgmq.read_batch(pq_name, vt: vt || config.visibility_timeout, qty: remaining) }
+            synchronized { with_read_timeout { @pgmq.read_batch(pq_name, vt: vt || config.visibility_timeout, qty: remaining) } }
           end
         end || []
 
@@ -180,7 +181,9 @@ module Pgbus
       Instrumentation.instrument("pgbus.client.read_multi", queues: full_names, qty: qty, limit: limit) do
         with_stale_connection_retry do
           synchronized do
-            @pgmq.read_multi(full_names, vt: vt || config.visibility_timeout, qty: qty, limit: limit)
+            with_read_timeout do
+              @pgmq.read_multi(full_names, vt: vt || config.visibility_timeout, qty: qty, limit: limit)
+            end
           end
         end
       end
@@ -357,7 +360,7 @@ module Pgbus
       full_name = config.queue_name(queue_name)
       Instrumentation.instrument("pgbus.client.read_grouped", queue: full_name, qty: qty) do
         with_stale_connection_retry do
-          synchronized { @pgmq.read_grouped(full_name, vt: vt || config.visibility_timeout, qty: qty) }
+          synchronized { with_read_timeout { @pgmq.read_grouped(full_name, vt: vt || config.visibility_timeout, qty: qty) } }
         end
       end
     end
@@ -366,7 +369,7 @@ module Pgbus
       full_name = config.queue_name(queue_name)
       Instrumentation.instrument("pgbus.client.read_grouped_rr", queue: full_name, qty: qty) do
         with_stale_connection_retry do
-          synchronized { @pgmq.read_grouped_rr(full_name, vt: vt || config.visibility_timeout, qty: qty) }
+          synchronized { with_read_timeout { @pgmq.read_grouped_rr(full_name, vt: vt || config.visibility_timeout, qty: qty) } }
         end
       end
     end
@@ -374,7 +377,7 @@ module Pgbus
     def read_grouped_head(queue_name, qty:, vt: nil)
       full_name = config.queue_name(queue_name)
       with_stale_connection_retry do
-        synchronized { @pgmq.read_grouped_head(full_name, vt: vt || config.visibility_timeout, qty: qty) }
+        synchronized { with_read_timeout { @pgmq.read_grouped_head(full_name, vt: vt || config.visibility_timeout, qty: qty) } }
       end
     end
 
@@ -696,6 +699,30 @@ module Pgbus
     # connection was dead *before* pgmq-ruby tried to use it, so no SQL was
     # ever sent. Mid-flight errors like "server closed the connection" are
     # excluded from the pattern list for this reason.
+    # Bound a read at config.read_timeout so a dead socket raises
+    # Pgbus::ReadTimeoutError instead of blocking the worker loop forever.
+    #
+    # MUST wrap only the bare `@pgmq.read*` call, sitting *inside* both
+    # `synchronized` and `with_stale_connection_retry`:
+    #
+    #   with_stale_connection_retry { synchronized { with_read_timeout { @pgmq.read* } } }
+    #
+    # Two reasons for this nesting:
+    #   1. On the shared-connection path @pgmq_mutex serializes all reads.
+    #      The timeout clock must start only after the mutex is acquired,
+    #      otherwise a thread queued behind another read is charged for the
+    #      wait and raises a false ReadTimeoutError for a socket it never
+    #      touched.
+    #   2. with_stale_connection_retry can retry once; with the timeout
+    #      inside, each socket attempt gets its own full timeout budget
+    #      rather than sharing one across both attempts.
+    def with_read_timeout(&)
+      timeout = config.read_timeout
+      return yield unless timeout&.positive?
+
+      Timeout.timeout(timeout, Pgbus::ReadTimeoutError, &)
+    end
+
     def with_stale_connection_retry
       attempts = 0
       begin

data/lib/pgbus/configuration.rb

@@ -26,6 +26,12 @@ module Pgbus
     # Worker recycling
     attr_accessor :max_jobs_per_worker, :max_memory_mb, :max_worker_lifetime
 
+    # Liveness probe: supervisor kills a worker whose claim loop has not
+    # advanced for longer than stall_threshold seconds (default 90).
+    # read_timeout caps how long a single PGMQ read can block (default 30s),
+    # so a dead socket raises instead of parking the loop forever.
+    attr_accessor :stall_threshold, :read_timeout
+
     # Dispatcher settings
     attr_accessor :dispatch_interval
 
@@ -150,6 +156,9 @@ module Pgbus
       @max_memory_mb = nil
       @max_worker_lifetime = nil
 
+      @stall_threshold = 90
+      @read_timeout = 30
+
       @dispatch_interval = 1.0
 
       @circuit_breaker_enabled = true
@@ -374,6 +383,13 @@ module Pgbus
         raise ArgumentError, "retry_backoff_jitter must be between 0 and 1"
       end
 
+      unless stall_threshold.nil? || (stall_threshold.is_a?(Numeric) && stall_threshold.positive?)
+        raise ArgumentError, "stall_threshold must be a positive number or nil to disable"
+      end
+      unless read_timeout.nil? || (read_timeout.is_a?(Numeric) && read_timeout.positive?)
+        raise ArgumentError, "read_timeout must be a positive number or nil to disable"
+      end
+
       # Validate global execution_mode
       ExecutionPools.normalize_mode(execution_mode)
 

data/lib/pgbus/mcp/base_tool.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Pgbus
+  module MCP
+    # Base class for every pgbus diagnostic tool. Provides the shared
+    # read-only annotation, a JSON response helper, and access to the
+    # DataSource the tool delegates to.
+    #
+    # The DataSource is pulled from +server_context[:data_source]+ so the
+    # server can inject a configured instance (and tests can inject a double).
+    # Every subclass is read-only by contract — see issue #180 security
+    # requirements. Write/admin tools, if ever added, must live in a separate,
+    # explicitly opt-in surface and never inherit from this class.
+    class BaseTool < ::MCP::Tool
+      # Marks the tool read-only and non-destructive so MCP clients can show
+      # the right affordance and never treat a call as a mutation.
+      annotations(
+        read_only_hint: true,
+        destructive_hint: false,
+        idempotent_hint: true,
+        open_world_hint: false
+      )
+
+      class << self
+        # MCP::Tool.inherited resets @annotations_value to nil on every
+        # subclass, so the read_only_hint set on BaseTool would not reach the
+        # concrete tools. Fall back to the nearest ancestor that defined
+        # annotations so all tools inherit the read-only contract without
+        # repeating it. (annotations_value is what MCP::Tool#to_h reads.)
+        def annotations_value
+          super || (superclass.respond_to?(:annotations_value) ? superclass.annotations_value : nil)
+        end
+
+        # Pull the injected DataSource (or build a default one). Kept as a
+        # class method because MCP tool entry points (`self.call`) are class
+        # methods.
+        def data_source_from(server_context)
+          (server_context && server_context[:data_source]) || Pgbus::Web::DataSource.new
+        end
+
+        # Whether payloads may be returned for this call. Honors a per-call
+        # `include_payloads` argument only when the server was started with
+        # payloads globally allowed (`server_context[:allow_payloads]`).
+        # Defaults to false on both axes so nothing leaks by accident.
+        def payloads_allowed?(server_context, include_payloads)
+          return false unless server_context && server_context[:allow_payloads]
+
+          !!include_payloads
+        end
+
+        # Wrap any Ruby value as a single text-content JSON response, applying
+        # payload redaction at this boundary as a fail-safe. Redaction is the
+        # default: a tool returns metadata, and any payload-bearing key (at any
+        # depth) is stripped unless this call is explicitly allowed to include
+        # payloads. A tool author who forgets about redaction therefore cannot
+        # leak message bodies — they have to opt in.
+        #
+        # Pass +server_context+ and the tool's per-call +include_payloads+ flag
+        # to enable payloads; both gates must be open (see #payloads_allowed?).
+        def json_response(value, server_context: nil, include_payloads: false)
+          allow = payloads_allowed?(server_context, include_payloads)
+          redacted = Redactor.deep_redact(value, include_payloads: allow)
+          ::MCP::Tool::Response.new([{ type: "text", text: JSON.generate(redacted) }])
+        end
+
+        # Wrap an error message as an MCP error response (isError: true) so the
+        # client surfaces it as a tool failure rather than a normal result.
+        def error_response(message)
+          ::MCP::Tool::Response.new(
+            [{ type: "text", text: message }],
+            error: true
+          )
+        end
+      end
+    end
+  end
+end