resque-mcp 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7aaa6b78cc06fac6720e3b95b382f2bc32b69d9cb8abe72ce9b0ab35c82561f
-  data.tar.gz: 8b908e0fdb79b0daee88070b2dd8121dad22c251328353759be555b30adf866b
+  metadata.gz: 890b5b8eb96c160226ce467a2a626861f25e774e5cd80402a4e8256a5aa361f1
+  data.tar.gz: fb3e64270e1d0dd2fca69d4ecedbd9c06b72ff146dd6160b5fc305420bc49117
 SHA512:
-  metadata.gz: a977ac62ae2eb47fde93099cc1583967da2186e87dc8aaa8f4bc5b613b50f70c160eb13ffa65327ca639d9a9d050e5b8561a975e39a30d34da7f85b9e1141eff
-  data.tar.gz: aa95121a61ce913be0702d1be6ee2d40d5ff83fbe080a1d59e8f63c30ecdc91a3f4056c832810b8dcf5922ebbf6e3a164ce6410d86959303fdb8584f349b5b14
+  metadata.gz: d066b59609ab3e12a1c0e7458bbf9503751b94f548c858e51aeb5a1cd921aa0675f1643d6d64c2bf83cc524314961104f9d11b5c25ec874731e5726f29799edf
+  data.tar.gz: 5e84b9b0249ee94416e9c505abba4637f01d8669dec570bab97a4bedb556a6008497525b4d0f19233c5b002f9228aede5c2ee8ae5e1467ae7a5c17d14d458c32

data/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [0.3.0]
+
+- `worker_stats` tool: list registered workers (state, subscribed queues, per-worker processed/failed counts, start time, current job with filtered args preview) with a `state` filter (`working`/`idle`/`all`), global counts including `heartbeat_expired`, and the standard pagination envelope. Workers whose heartbeat is older than `Resque.prune_interval` are flagged as likely dead.
+- Parameter filtering: job args in all tool responses are masked with `[FILTERED]` via `ActiveSupport::ParameterFilter` before any preview/truncation. Inherits `Rails.application.config.filter_parameters` by default; `Resque::Mcp.configure { |c| c.filter_parameters = [...] }` replaces the list (`[]` disables).
+- Internal: the adapter now returns model objects instead of hashes; raw job args are sealed inside `Models::Job` and only accessible filtered. No change to any tool response.
+
 ## [0.2.0]
 
 - `list_failures` tool: page through failed jobs newest-first with compact records (truncated error, args preview, no backtrace); optional `class_name` filter (filtered totals are marked `"total_note": "scan"` and paging must follow the returned `next_offset` cursor).

data/README.md

@@ -1,5 +1,7 @@
 # resque-mcp
 
+[![Gem Version](https://badge.fury.io/rb/resque-mcp.svg)](https://rubygems.org/gems/resque-mcp)
+
 An MCP server for [Resque](https://github.com/resque/resque), mountable as a Rails engine. Lets MCP clients (e.g. Claude Code) inspect queues, workers, and failed jobs — and retry or clear failures — over a single authenticated Streamable HTTP endpoint.
 
 ## Requirements
@@ -10,13 +12,15 @@ An MCP server for [Resque](https://github.com/resque/resque), mountable as a Rai
 
 ## Installation
 
-Not yet published to RubyGems. Until then, install from git:
+Add the gem to your application's Gemfile:
 
 ```ruby
 # Gemfile
-gem "resque-mcp", github: "jbockler/resque-mcp"
+gem "resque-mcp"
 ```
 
+Then run `bundle install`. Or install it yourself with `gem install resque-mcp`.
+
 ## Usage
 
 Mount the engine and configure the auth token:
@@ -29,11 +33,20 @@ mount Resque::Mcp::Engine => "/resque-mcp"
 Resque::Mcp.configure do |c|
   # token could be created by e.g.: `bin/rails runner 'puts SecureRandom.base58(32)'`
   c.auth_token = Rails.application.credentials.dig(:resque_mcp, :token)
+
+  # Optional: which job-args keys to mask as [FILTERED] in tool responses.
+  # Defaults to your app's config.filter_parameters; an explicit list
+  # replaces it (merge yourself if you want both):
+  # c.filter_parameters = Rails.application.config.filter_parameters + [:iban]
 end
 ```
 
 The token is **required** — the endpoint answers `503` until one is configured, and `401` on any request without a matching `Authorization: Bearer` header. The engine talks to whatever `Resque.redis` your app already configured; it never opens its own Redis connection.
 
+Job arguments shown by any tool are filtered through `ActiveSupport::ParameterFilter` **before** preview/truncation, using your Rails `filter_parameters` by default — the same keys you hide from your logs are hidden from the model. Filters match hash keys (at any depth, same semantics as Rails log filtering, including anchored dot-notation like `/\Acredit_card\.code\z/`); positional scalar args have no key and pass through. Set `c.filter_parameters = []` to disable.
+
+Scope honestly stated: filtering covers **job args only**. Exception messages and backtraces in failure records are shown unfiltered (Rails doesn't scrub those from logs either) — a secret interpolated into an exception message will be visible, so treat error text accordingly.
+
 Connect Claude Code:
 
 ```sh
@@ -45,7 +58,7 @@ Then ask, e.g., "How is my Resque doing?"
 
 ## Tools
 
-The tool surface is read-only so far (worker inspection and failure retry/clear are planned). Every tool response returns structured JSON alongside a text body and ends in a `meta` footer naming the Rails environment and the Redis target (with any credentials stripped), so you always see what you are talking to.
+The tool surface is read-only so far (failure retry/clear are planned). Every tool response returns structured JSON alongside a text body and ends in a `meta` footer naming the Rails environment and the Redis target (with any credentials stripped), so you always see what you are talking to.
 
 ### `overview` — read-only
 
@@ -82,6 +95,30 @@ List all queues with sizes, or inspect a single queue. With `queue` and `include
 
 Every paginated response carries this `page` envelope. Limits are capped at 100 — a larger request is clamped and the clamp noted in the response.
 
+### `worker_stats` — read-only
+
+List registered workers with their current state, optionally filtered by `state` (`working` / `idle` / `all`):
+
+```json
+{
+  "workers": [
+    {
+      "id": "worker-host-1:4021:imports,default", "state": "working",
+      "queues": ["imports", "default"], "started": "2026-06-30 04:12:09 UTC",
+      "processed": 48211, "failed": 12, "heartbeat_expired": false,
+      "current_job": { "queue": "imports", "class": "ImportWorker",
+                       "args_preview": "[812, …]", "run_at": "2026-07-02T09:14:55Z" }
+    }
+  ],
+  "counts": { "total": 12, "working": 3, "idle": 9, "heartbeat_expired": 1 },
+  "page": { "total": 12, "offset": 0, "limit": 50, "returned": 12, "has_more": false, "next_offset": null },
+  "meta": { "…": "…" }
+}
+```
+
+- `heartbeat_expired: true` flags a worker whose last heartbeat is older than `Resque.prune_interval` — it is likely dead and its record stale.
+- `counts` always covers all workers; a `state` filter only narrows the `workers` list (and its `page` envelope).
+
 ### `list_failures` — read-only
 
 Page through failed jobs, newest first, as compact records (truncated error, args preview, no backtrace). Optionally filter by `class_name`.

data/lib/resque/mcp/adapter.rb

@@ -58,7 +58,10 @@ module Resque
 
       def peek(queue, offset:, limit:)
         ensure_known_queue!(queue)
-        {size: @resque.size(queue), jobs: to_array(@resque.peek(queue, offset, limit))}
+        jobs = to_array(@resque.peek(queue, offset, limit)).map do |item|
+          build_job(item, queue: queue)
+        end
+        {size: @resque.size(queue), jobs: jobs}
       end
 
       # Newest-first pagination over the failed list. `offset` counts raw
@@ -87,6 +90,16 @@ module Resque
         normalize_failure(index, item)
       end
 
+      # Normalized snapshot of all registered workers, sorted by id so
+      # pagination over the unordered Redis set is deterministic.
+      # `started` is an opaque string (never parsed, like failed_at).
+      def workers
+        expired_ids = @resque::Worker.all_workers_with_expired_heartbeats.map(&:to_s)
+        @resque.workers
+          .map { |worker| normalize_worker(worker, expired_ids) }
+          .sort_by(&:id)
+      end
+
       # Resque.redis_id can embed user:password@; only this stripped form
       # may reach tool responses.
       def redis_identifier
@@ -151,20 +164,39 @@ module Resque
         }
       end
 
+      def normalize_worker(worker, expired_ids)
+        id = worker.to_s
+        job = worker.job
+        Models::Worker.new(
+          id: id,
+          state: job.empty? ? "idle" : "working",
+          queues: worker.queues,
+          started: worker.started,
+          processed: worker.processed,
+          failed: worker.failed,
+          heartbeat_expired: expired_ids.include?(id),
+          current_job: job.empty? ? nil : build_job(job["payload"], queue: job["queue"], run_at: job["run_at"])
+        )
+      end
+
+      # The single place mapping resque's payload keys to Models::Job.
+      def build_job(payload, queue: nil, run_at: nil)
+        payload ||= {}
+        Models::Job.new(class_name: payload["class"], args: payload["args"], queue: queue, run_at: run_at)
+      end
+
       def normalize_failure(index, item)
-        payload = item["payload"] || {}
-        {
+        Models::Failure.new(
           index: index,
           failed_at: item["failed_at"],
           queue: item["queue"],
-          class: payload["class"],
-          args: payload["args"],
           exception: item["exception"],
           error: item["error"],
           backtrace: item["backtrace"],
           worker: item["worker"],
-          retried_at: item["retried_at"]
-        }
+          retried_at: item["retried_at"],
+          job: build_job(item["payload"])
+        )
       end
 
       # Resque's list reads (Resque.peek, Failure.all) return a bare hash

data/lib/resque/mcp/configuration.rb

@@ -4,6 +4,25 @@ module Resque
   module Mcp
     class Configuration
       attr_accessor :auth_token
+      # nil = inherit the host default (the engine wires Rails'
+      # filter_parameters as a lazy source); an explicit list replaces it
+      # ([] disables filtering).
+      attr_accessor :filter_parameters
+      # Internal seam: a callable returning the host's filter list, read
+      # lazily so late additions to Rails' list (or other engines'
+      # after_initialize hooks) are never missed.
+      attr_accessor :default_filter_parameters
+
+      # Memoized against the *effective* list, so both reassignment and
+      # in-place mutation (config.filter_parameters << :iban) take effect.
+      def param_filter
+        list = filter_parameters || default_filter_parameters&.call || []
+        unless defined?(@param_filter) && @param_filter_list == list
+          @param_filter_list = list.dup
+          @param_filter = ActiveSupport::ParameterFilter.new(list)
+        end
+        @param_filter
+      end
     end
   end
 end

data/lib/resque/mcp/engine.rb

@@ -6,6 +6,14 @@ module Resque
   module Mcp
     class Engine < ::Rails::Engine
       isolate_namespace Resque::Mcp
+
+      # A lazy source, not a boot-time snapshot: evaluated per use so
+      # post-boot additions to Rails' filter list (or other engines'
+      # after_initialize hooks) are never missed. An explicitly configured
+      # filter_parameters still takes precedence.
+      initializer "resque_mcp.filter_parameters" do
+        Resque::Mcp.config.default_filter_parameters = -> { Rails.application.config.filter_parameters }
+      end
     end
   end
 end

data/lib/resque/mcp/models/failure.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Resque
+  module Mcp
+    module Models
+      # One failed-job record. `index` is the record's mutable position in
+      # the Redis failed list, not a stable id. `failed_at`/`retried_at`
+      # are opaque strings. `job` is a Models::Job (sealed args); the
+      # origin queue lives here, not on the job.
+      Failure = Data.define(
+        :index, :failed_at, :queue, :exception, :error,
+        :backtrace, :worker, :retried_at, :job
+      )
+    end
+  end
+end

data/lib/resque/mcp/models/job.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Resque
+  module Mcp
+    module Models
+      # One job payload. Raw args are sealed — filtered access is the only
+      # public surface, so no caller can serialize them unfiltered.
+      class Job
+        attr_reader :class_name, :queue, :run_at
+
+        def initialize(class_name:, args:, queue: nil, run_at: nil)
+          @class_name = class_name
+          @args = args
+          @queue = queue
+          @run_at = run_at
+        end
+
+        # Key-based filtering runs here, before any presentation-layer
+        # truncation, so a secret can't survive inside a truncated JSON
+        # string. Each hash arg is filtered as its own root, so anchored
+        # dot-notation filters (/\Acredit_card\.code\z/) match exactly as
+        # in Rails log filtering. Only hash keys can match — bare
+        # positional scalars pass through. A raising host filter (e.g. a
+        # proc assuming string values) fails CLOSED: args are withheld
+        # with an in-band mark, never leaked.
+        #
+        # Memoization assumes a Job never outlives its request (the
+        # adapter is per-request): the filter config and a transient
+        # fail-closed result are frozen in at first read. Revisit before
+        # ever caching adapter results across requests.
+        def filtered_args
+          return @filtered_args if defined?(@filtered_args)
+          @filtered_args = filter(Resque::Mcp.config.param_filter, @args)
+        rescue => e
+          @filtered_args = "[args withheld: filter_parameters raised #{e.class}]"
+        end
+
+        # Debug and generic-serialization surfaces must not undo the
+        # sealing: the default #inspect renders @args, ActiveSupport's
+        # Object#as_json/#to_json walk instance variables, and pp bypasses
+        # #inspect via #pretty_print.
+        def inspect
+          "#<#{self.class.name} class_name=#{@class_name.inspect} " \
+            "queue=#{@queue.inspect} run_at=#{@run_at.inspect} args=[sealed]>"
+        end
+
+        def pretty_print(pp)
+          pp.text(inspect)
+        end
+
+        def as_json(_options = nil)
+          {"class_name" => @class_name, "queue" => @queue, "run_at" => @run_at,
+           "args" => filtered_args}
+        end
+
+        private
+
+        def filter(param_filter, value)
+          case value
+          when Hash then param_filter.filter(value)
+          when Array then value.map { |element| filter(param_filter, element) }
+          else value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/resque/mcp/models/worker.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Resque
+  module Mcp
+    module Models
+      # One registered worker. `started` is an opaque string.
+      # `current_job` is a Models::Job (with queue/run_at) or nil.
+      Worker = Data.define(
+        :id, :state, :queues, :started, :processed, :failed,
+        :heartbeat_expired, :current_job
+      ) do
+        def working? = state == "working"
+
+        def idle? = state == "idle"
+      end
+    end
+  end
+end

data/lib/resque/mcp/server_factory.rb

@@ -9,7 +9,7 @@ module Resque
         ::MCP::Server.new(
           name: "resque-mcp",
           version: Resque::Mcp::VERSION,
-          tools: [Tools::Overview, Tools::QueueStats, Tools::ListFailures, Tools::GetFailure],
+          tools: [Tools::Overview, Tools::QueueStats, Tools::WorkerStats, Tools::ListFailures, Tools::GetFailure],
           server_context: {adapter: Adapter.new, environment: environment}
         )
       end

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

@@ -38,11 +38,14 @@ module Resque
             page
           end
 
-          def args_preview(args)
-            truncate_text(JSON.generate(args), ARGS_PREVIEW_MAX)
+          # Both take a Models::Job — raw args are sealed inside it
+          # (filtering already applied); these helpers only truncate.
+          def args_preview(job)
+            truncate_text(JSON.generate(job.filtered_args), ARGS_PREVIEW_MAX)
           end
 
-          def full_args(args)
+          def full_args(job)
+            args = job.filtered_args
             json = JSON.generate(args)
             (json.length <= ARGS_FULL_MAX) ? args : truncate_text(json, ARGS_FULL_MAX)
           end

data/lib/resque/mcp/tools/get_failure.rb

@@ -19,19 +19,19 @@ module Resque
 
         def self.call(index:, server_context:, queue: nil, **)
           record = adapter(server_context).failure(index, queue: queue)
-          backtrace, omitted = capped_backtrace(record[:backtrace])
+          backtrace, omitted = capped_backtrace(record.backtrace)
           success_response({
-            index: record[:index],
-            failed_at: record[:failed_at],
-            queue: record[:queue],
-            class: record[:class],
-            args: full_args(record[:args]),
-            exception: record[:exception],
-            error: record[:error],
+            index: record.index,
+            failed_at: record.failed_at,
+            queue: record.queue,
+            class: record.job.class_name,
+            args: full_args(record.job),
+            exception: record.exception,
+            error: record.error,
             backtrace: backtrace,
             backtrace_omitted: omitted,
-            worker: record[:worker],
-            retried_at: record[:retried_at]
+            worker: record.worker,
+            retried_at: record.retried_at
           }, server_context)
         rescue Adapter::FailureOutOfRangeError, Adapter::FailureQueueRequiredError, ArgumentError => e
           error_response(e.message)

data/lib/resque/mcp/tools/list_failures.rb

@@ -28,14 +28,14 @@ module Resque
           )
           failures = result[:records].map do |record|
             {
-              index: record[:index],
-              failed_at: record[:failed_at],
-              queue: record[:queue],
-              class: record[:class],
-              args_preview: args_preview(record[:args]),
-              exception: record[:exception],
-              error: truncated_error(record[:error]),
-              retried_at: record[:retried_at]
+              index: record.index,
+              failed_at: record.failed_at,
+              queue: record.queue,
+              class: record.job.class_name,
+              args_preview: args_preview(record.job),
+              exception: record.exception,
+              error: truncated_error(record.error),
+              retried_at: record.retried_at
             }
           end
           success_response({

data/lib/resque/mcp/tools/queue_stats.rb

@@ -32,7 +32,7 @@ module Resque
           clamped = clamp_limit(limit)
           result = adapter(server_context).peek(queue, offset: offset, limit: clamped)
           jobs = result[:jobs].map do |job|
-            {class: job["class"], args_preview: args_preview(job["args"])}
+            {class: job.class_name, args_preview: args_preview(job)}
           end
           success_response({
             queue: queue,

data/lib/resque/mcp/tools/worker_stats.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Resque
+  module Mcp
+    module Tools
+      class WorkerStats < Base
+        STATES = %w[all working idle].freeze
+
+        tool_name "worker_stats"
+        description "List registered workers: state (working/idle), current job, " \
+          "queues subscribed, per-worker processed/failed counts, start time. " \
+          "Flags workers with expired heartbeats (likely dead)."
+        input_schema(
+          properties: {
+            state: {type: "string", enum: ["working", "idle", "all"], default: "all"},
+            offset: {type: "integer", default: 0, minimum: 0},
+            limit: {type: "integer", default: 50, minimum: 1, maximum: 100}
+          },
+          required: []
+        )
+        annotations(read_only_hint: true)
+
+        def self.call(server_context:, state: "all", offset: 0, limit: 50, **)
+          unless STATES.include?(state)
+            return error_response("state must be one of: #{STATES.join(", ")}")
+          end
+
+          all = adapter(server_context).workers
+          counts = {
+            total: all.size,
+            working: all.count(&:working?),
+            idle: all.count(&:idle?),
+            heartbeat_expired: all.count(&:heartbeat_expired)
+          }
+          selected = (state == "all") ? all : all.select { |w| w.state == state }
+          clamped = clamp_limit(limit)
+          workers = (selected[offset, clamped] || []).map do |record|
+            job = record.current_job
+            record.to_h.merge(current_job: job && {
+              queue: job.queue,
+              class: job.class_name,
+              args_preview: args_preview(job),
+              run_at: job.run_at
+            })
+          end
+          success_response({
+            workers: workers,
+            counts: counts,
+            page: page_envelope(
+              total: selected.size, offset: offset, limit: clamped,
+              returned: workers.size, requested_limit: limit
+            )
+          }, server_context)
+        end
+      end
+    end
+  end
+end

data/lib/resque/mcp/version.rb

@@ -2,6 +2,6 @@
 
 module Resque
   module Mcp
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

data/lib/resque/mcp.rb

@@ -4,6 +4,7 @@ require "json"
 require "resque"
 require "mcp"
 require "zeitwerk"
+require "active_support/parameter_filter"
 
 require_relative "mcp/version"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: resque-mcp
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Josch Bockler
@@ -43,6 +43,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
 - !ruby/object:Gem::Dependency
   name: railties
   requirement: !ruby/object:Gem::Requirement
@@ -90,12 +104,16 @@ files:
 - lib/resque/mcp/adapter.rb
 - lib/resque/mcp/configuration.rb
 - lib/resque/mcp/engine.rb
+- lib/resque/mcp/models/failure.rb
+- lib/resque/mcp/models/job.rb
+- lib/resque/mcp/models/worker.rb
 - lib/resque/mcp/server_factory.rb
 - lib/resque/mcp/tools/base.rb
 - lib/resque/mcp/tools/get_failure.rb
 - lib/resque/mcp/tools/list_failures.rb
 - lib/resque/mcp/tools/overview.rb
 - lib/resque/mcp/tools/queue_stats.rb
+- lib/resque/mcp/tools/worker_stats.rb
 - lib/resque/mcp/version.rb
 - sig/resque/mcp.rbs
 homepage: https://github.com/jbockler/resque-mcp