resque-mcp 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f899cb2c9bb3c59a5185841550784e81dac79b0848da767f1cd5a81910efc84
-  data.tar.gz: 26775e429aa90ffcf60ed7b1517f74744d7786f137890376b9263392fd1d5719
+  metadata.gz: 890b5b8eb96c160226ce467a2a626861f25e774e5cd80402a4e8256a5aa361f1
+  data.tar.gz: fb3e64270e1d0dd2fca69d4ecedbd9c06b72ff146dd6160b5fc305420bc49117
 SHA512:
-  metadata.gz: 4185dc24785f9425db9089136725a30ca45995d5dc35883dec9cbdfd0cdb2a47105037d376bc37315097f3136d90c22e2521487bd42351593593b86ea1446b0a
-  data.tar.gz: f2e8f0558eec1d6cd83589695eddd3dca1703d65130f71530a23596f81540e3c3a3a6611cb5360cac95c3cdf97fa95bced0177c197b12ef4a58d4a82d790ff31
+  metadata.gz: d066b59609ab3e12a1c0e7458bbf9503751b94f548c858e51aeb5a1cd921aa0675f1643d6d64c2bf83cc524314961104f9d11b5c25ec874731e5726f29799edf
+  data.tar.gz: 5e84b9b0249ee94416e9c505abba4637f01d8669dec570bab97a4bedb556a6008497525b4d0f19233c5b002f9228aede5c2ee8ae5e1467ae7a5c17d14d458c32

data/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [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).
+- `get_failure` tool: full detail for one failed job by list index — complete args (capped at a few KB), exception, backtrace capped at 30 frames with `backtrace_omitted`, worker, retry stamp. Out-of-range indexes answer with the current failure count. On the redis_multi_queue backend both failure tools require an explicit `queue` and answer a dedicated error naming the failure queues when it is missing. Failures are addressed by `index`, not `id` — the position shifts when records are removed.
+- `queue_stats` tool: list all queues with sizes, or inspect one queue and page through its pending job payloads (`include_jobs: true`); paginated responses carry a `page` envelope (`total`/`offset`/`limit`/`returned`/`has_more`/`next_offset`), limits above 100 are clamped with an in-band note, and job args are shown as truncated previews.
+
 ## [0.1.0]
 
 - Mountable Rails engine serving a stateless MCP Streamable HTTP endpoint (`POST` only; all other verbs answer 405).

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:
@@ -27,12 +31,22 @@ mount Resque::Mcp::Engine => "/resque-mcp"
 
 # config/initializers/resque_mcp.rb
 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
@@ -44,7 +58,7 @@ Then ask, e.g., "How is my Resque doing?"
 
 ## Tools
 
-The tool surface is currently in progress. 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
 
@@ -63,10 +77,88 @@ Global Resque health snapshot; takes no parameters.
 - `processed` is Resque's lifetime counter; `failed` is the current number of records in the failed list.
 - `workers` counts registered workers, `working` those currently running a job.
 
+### `queue_stats` — read-only
+
+List all queues with sizes, or inspect a single queue. With `queue` and `include_jobs: true` it pages through the queue's pending job payloads:
+
+```json
+{
+  "queue": "imports", "size": 84,
+  "jobs": [
+    { "class": "ImportWorker", "args_preview": "[812, \"s3://bucket/batch-7.csv\"]" },
+    { "class": "ImportWorker", "args_preview": "[813, \"s3://bucket/batch-8.csv\"]" }
+  ],
+  "page": { "total": 84, "offset": 0, "limit": 2, "returned": 2, "has_more": true, "next_offset": 2 },
+  "meta": { "…": "…" }
+}
+```
+
+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`.
+
+```json
+{
+  "failures": [
+    {
+      "index": 1341, "failed_at": "2026/07/02 08:59:12 UTC",
+      "queue": "imports", "class": "ImportWorker",
+      "args_preview": "[812, \"s3://bucket/batch-7.csv\"]",
+      "exception": "PG::ConnectionBad",
+      "error": "could not connect to server: Connection refused… (truncated)",
+      "retried_at": null
+    }
+  ],
+  "page": { "total": 1342, "offset": 0, "limit": 20, "returned": 20, "has_more": true, "next_offset": 20 },
+  "meta": { "…": "…" }
+}
+```
+
+- A failure's `index` is its position in the failed list, deliberately not called an `id`: indexes shift when failures are removed, so re-list after any removal.
+- Under a `class_name` filter, `next_offset` is a raw scan cursor — continue paging with the returned value, never compute `offset + limit` yourself. Filtered totals cost a full-list scan and are marked `"total_note": "scan"`.
+
+### `get_failure` — read-only
+
+Full detail for one failed job by `index`: complete args, exception, full error, backtrace (capped at 30 frames, with `backtrace_omitted`), and the worker that failed it.
+
+All truncation anywhere in the tool surface is marked in-band (`"… (truncated)"`, `backtrace_omitted`), so a model always knows when it is seeing an excerpt.
+
+### Failure backends
+
+Both failure tools support Resque's `redis_multi_queue` failure backend: pass the failure-queue name as `queue`. On that backend the tools require it and answer with the list of failure queues when it is missing. On the default backend, `queue` can simply be omitted.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake` to run the tests and standardrb. You can also run `bin/console` for an interactive prompt.
 
+To release a new version, update the changelog and the version number in version.rb, commit it, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/jbockler/resque-mcp. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/jbockler/resque-mcp/blob/main/CODE_OF_CONDUCT.md).

data/lib/resque/mcp/adapter.rb

@@ -4,6 +4,30 @@ module Resque
   module Mcp
     # The only code in the gem that talks to Resque. Rails-free.
     class Adapter
+      class UnknownQueueError < StandardError
+        def initialize(queue, known_queues)
+          known = known_queues.empty? ? "(none)" : known_queues.sort.join(", ")
+          super("Unknown queue #{queue.inspect}. Known queues: #{known}")
+        end
+      end
+
+      class FailureOutOfRangeError < StandardError
+        def initialize(index, count)
+          super("No failure at index #{index}. Current failure count: #{count}" \
+            "#{" (valid indexes 0..#{count - 1})" if count > 0}.")
+        end
+      end
+
+      class FailureQueueRequiredError < StandardError
+        def initialize(known_queues)
+          super("The redis_multi_queue failure backend is active — pass `queue` " \
+            "with one of the failure queues: #{known_queues.sort.join(", ")}.")
+        end
+      end
+
+      # Chunk size for the tail-backwards scan under a class_name filter.
+      FILTER_SCAN_CHUNK = 100
+
       def initialize(resque: ::Resque)
         @resque = resque
       end
@@ -23,6 +47,59 @@ module Resque
         }
       end
 
+      def queues
+        @resque.queue_sizes
+      end
+
+      def queue_size(queue)
+        ensure_known_queue!(queue)
+        @resque.size(queue)
+      end
+
+      def peek(queue, offset:, limit:)
+        ensure_known_queue!(queue)
+        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
+      # list positions back from the newest record; returned indexes are raw
+      # list positions (what requeue/remove take). Failures are RPUSH'd so
+      # index 0 is the OLDEST record, and Failure.each's 'desc' only
+      # reverses within a fetched slice — the newest-first window has to be
+      # translated to raw indexes here.
+      def failures(offset:, limit:, class_name: nil, queue: nil)
+        ensure_failure_queue!(queue)
+        raw_total = @resque::Failure.count(queue)
+        if class_name.nil?
+          unfiltered_failures(offset, limit, raw_total, queue)
+        else
+          filtered_failures(offset, limit, raw_total, class_name, queue)
+        end
+      end
+
+      def failure(index, queue: nil)
+        ensure_failure_queue!(queue)
+        count = @resque::Failure.count(queue)
+        raise FailureOutOfRangeError.new(index, count) unless index >= 0 && index < count
+        item = to_array(@resque::Failure.all(index, 1, queue)).first
+        # The list can shrink between the count read and the fetch.
+        raise FailureOutOfRangeError.new(index, @resque::Failure.count(queue)) if item.nil?
+        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
@@ -31,6 +108,121 @@ module Resque
 
       private
 
+      def unfiltered_failures(offset, limit, raw_total, queue)
+        available = raw_total - offset
+        if available <= 0
+          return {records: [], total: raw_total, has_more: false, next_offset: nil}
+        end
+        count = [limit, available].min
+        raw_start = raw_total - offset - count
+        items = to_array(@resque::Failure.all(raw_start, count, queue))
+        records = items.each_with_index
+          .reject { |item, _i| item.nil? }
+          .map { |item, i| normalize_failure(raw_start + i, item) }
+          .reverse
+        has_more = offset + count < raw_total
+        {
+          records: records,
+          total: raw_total,
+          has_more: has_more,
+          next_offset: has_more ? offset + count : nil
+        }
+      end
+
+      # Scans the list tail-backwards in chunks collecting class_name
+      # matches. next_offset is a RAW cursor (raw positions consumed from
+      # the newest end), not a match count — page arithmetic on it is
+      # invalid, callers must pass it back verbatim.
+      def filtered_failures(offset, limit, raw_total, class_name, queue)
+        records = []
+        cursor_after_last = nil
+        has_more = false
+        pos = offset
+        while pos < raw_total && !has_more
+          chunk_size = [FILTER_SCAN_CHUNK, raw_total - pos].min
+          raw_start = raw_total - pos - chunk_size
+          items = to_array(@resque::Failure.all(raw_start, chunk_size, queue))
+          items.reverse_each do |item|
+            index = raw_total - pos - 1
+            pos += 1
+            next unless item && item.dig("payload", "class") == class_name
+            if records.size < limit
+              records << normalize_failure(index, item)
+              cursor_after_last = pos
+            else
+              has_more = true
+              break
+            end
+          end
+        end
+        {
+          records: records,
+          total: @resque::Failure.count(queue, class_name),
+          total_note: "scan",
+          has_more: has_more,
+          next_offset: has_more ? cursor_after_last : nil
+        }
+      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)
+        Models::Failure.new(
+          index: index,
+          failed_at: item["failed_at"],
+          queue: item["queue"],
+          exception: item["exception"],
+          error: item["error"],
+          backtrace: item["backtrace"],
+          worker: item["worker"],
+          retried_at: item["retried_at"],
+          job: build_job(item["payload"])
+        )
+      end
+
+      # Resque's list reads (Resque.peek, Failure.all) return a bare hash
+      # (or nil) instead of a list when asked for exactly one item.
+      def to_array(items)
+        items.is_a?(Array) ? items : [items].compact
+      end
+
+      # On redis_multi_queue, count(nil) sums ALL failure queues while
+      # all(..., nil) reads the empty default :failed list — pagination
+      # over that mismatch reports has_more forever without yielding a
+      # record, so a failure queue must be named explicitly.
+      def ensure_failure_queue!(queue)
+        return unless queue.nil? && multi_queue_failure_backend?
+        raise FailureQueueRequiredError.new(@resque::Failure.queues)
+      end
+
+      def multi_queue_failure_backend?
+        @resque::Failure.backend.name == "Resque::Failure::RedisMultiQueue"
+      end
+
+      def ensure_known_queue!(queue)
+        known = @resque.queues
+        raise UnknownQueueError.new(queue, known) unless known.include?(queue)
+      end
+
       # Greedy to the last "@" — passwords may contain "@", "/", or spaces;
       # over-stripping is acceptable, leaking is not.
       def strip_userinfo(id)

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: [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

@@ -3,8 +3,15 @@
 module Resque
   module Mcp
     module Tools
-      # Shared tool helpers: adapter access, response envelopes, meta footer.
+      # Shared tool helpers: adapter access, response envelopes, meta footer,
+      # pagination and size caps (size policy lives here, not in tools).
       class Base < ::MCP::Tool
+        LIMIT_MAX = 100
+        ARGS_PREVIEW_MAX = 200
+        ERROR_TRUNCATE_MAX = 200
+        BACKTRACE_MAX_FRAMES = 30
+        ARGS_FULL_MAX = 4096
+
         class << self
           private
 
@@ -12,6 +19,53 @@ module Resque
             server_context.fetch(:adapter)
           end
 
+          def clamp_limit(limit)
+            [limit, LIMIT_MAX].min
+          end
+
+          # has_more/next_offset default to offset arithmetic; tools whose
+          # adapter owns the cursor semantics (failures) pass them in.
+          def page_envelope(total:, offset:, limit:, returned:, requested_limit: limit,
+            has_more: nil, next_offset: :compute, total_note: nil)
+            has_more = offset + returned < total if has_more.nil?
+            next_offset = has_more ? offset + returned : nil if next_offset == :compute
+            page = {
+              total: total, offset: offset, limit: limit, returned: returned,
+              has_more: has_more, next_offset: next_offset
+            }
+            page[:note] = "limit clamped to #{LIMIT_MAX}" if requested_limit > limit
+            page[:total_note] = total_note if total_note
+            page
+          end
+
+          # 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(job)
+            args = job.filtered_args
+            json = JSON.generate(args)
+            (json.length <= ARGS_FULL_MAX) ? args : truncate_text(json, ARGS_FULL_MAX)
+          end
+
+          def truncated_error(error)
+            error.nil? ? nil : truncate_text(error, ERROR_TRUNCATE_MAX)
+          end
+
+          # => [frames, omitted_count]
+          def capped_backtrace(frames)
+            frames = frames.is_a?(Array) ? frames : []
+            omitted = [frames.size - BACKTRACE_MAX_FRAMES, 0].max
+            [frames.first(BACKTRACE_MAX_FRAMES), omitted]
+          end
+
+          def truncate_text(text, max)
+            return text if text.length <= max
+            "#{text[0, max]}… (truncated)"
+          end
+
           def success_response(payload, server_context)
             body = payload.merge(meta: meta_footer(server_context))
             ::MCP::Tool::Response.new(

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Resque
+  module Mcp
+    module Tools
+      class GetFailure < Base
+        tool_name "get_failure"
+        description "Full detail for one failed job by list index (as returned by " \
+          "list_failures — indexes shift when failures are removed): complete args, " \
+          "exception, backtrace (capped at 30 frames), worker that failed it."
+        input_schema(
+          properties: {
+            index: {type: "integer", minimum: 0},
+            queue: {type: "string", description: "Failure queue (only relevant with the redis_multi_queue backend; use the same value as in list_failures)"}
+          },
+          required: ["index"]
+        )
+        annotations(read_only_hint: true)
+
+        def self.call(index:, server_context:, queue: nil, **)
+          record = adapter(server_context).failure(index, queue: queue)
+          backtrace, omitted = capped_backtrace(record.backtrace)
+          success_response({
+            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
+          }, server_context)
+        rescue Adapter::FailureOutOfRangeError, Adapter::FailureQueueRequiredError, ArgumentError => e
+          error_response(e.message)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Resque
+  module Mcp
+    module Tools
+      class ListFailures < Base
+        tool_name "list_failures"
+        description "Page through failed jobs, newest first. Compact records without " \
+          "backtraces — use get_failure for full detail. Each record's `index` is its " \
+          "position in the failed list, not a stable id: indexes shift when failures " \
+          "are removed, so re-list after any removal. Continue paging with the " \
+          "returned page.next_offset — do not compute offsets yourself."
+        input_schema(
+          properties: {
+            offset: {type: "integer", default: 0, minimum: 0},
+            limit: {type: "integer", default: 20, minimum: 1, maximum: 100},
+            class_name: {type: "string", description: "Only failures of this job class"},
+            queue: {type: "string", description: "Failure queue (only relevant with the redis_multi_queue backend)"}
+          },
+          required: []
+        )
+        annotations(read_only_hint: true)
+
+        def self.call(server_context:, offset: 0, limit: 20, class_name: nil, queue: nil, **)
+          clamped = clamp_limit(limit)
+          result = adapter(server_context).failures(
+            offset: offset, limit: clamped, class_name: class_name, queue: queue
+          )
+          failures = result[:records].map do |record|
+            {
+              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({
+            failures: failures,
+            page: page_envelope(
+              total: result[:total], offset: offset, limit: clamped,
+              returned: failures.size, requested_limit: limit,
+              has_more: result[:has_more], next_offset: result[:next_offset],
+              total_note: result[:total_note]
+            )
+          }, server_context)
+        rescue Adapter::FailureQueueRequiredError, ArgumentError => e
+          error_response(e.message)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Resque
+  module Mcp
+    module Tools
+      class QueueStats < Base
+        tool_name "queue_stats"
+        description "List queues with sizes. Pass `queue` to inspect one queue and " \
+          "optionally page through its pending jobs (`include_jobs: true`)."
+        input_schema(
+          properties: {
+            queue: {type: "string", description: "Inspect a single queue by name"},
+            include_jobs: {type: "boolean", default: false, description: "Include pending job payloads (only with queue)"},
+            offset: {type: "integer", default: 0, minimum: 0},
+            limit: {type: "integer", default: 20, minimum: 1, maximum: 100}
+          },
+          required: []
+        )
+        annotations(read_only_hint: true)
+
+        def self.call(server_context:, queue: nil, include_jobs: false, offset: 0, limit: 20, **)
+          if queue.nil?
+            return error_response("include_jobs requires queue") if include_jobs
+            return success_response({queues: adapter(server_context).queues}, server_context)
+          end
+
+          unless include_jobs
+            size = adapter(server_context).queue_size(queue)
+            return success_response({queue: queue, size: size}, server_context)
+          end
+
+          clamped = clamp_limit(limit)
+          result = adapter(server_context).peek(queue, offset: offset, limit: clamped)
+          jobs = result[:jobs].map do |job|
+            {class: job.class_name, args_preview: args_preview(job)}
+          end
+          success_response({
+            queue: queue,
+            size: result[:size],
+            jobs: jobs,
+            page: page_envelope(
+              total: result[:size], offset: offset, limit: clamped,
+              returned: jobs.size, requested_limit: limit
+            )
+          }, server_context)
+        rescue Adapter::UnknownQueueError => e
+          error_response(e.message)
+        end
+      end
+    end
+  end
+end

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.1.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.1.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,9 +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