resque-mcp 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f899cb2c9bb3c59a5185841550784e81dac79b0848da767f1cd5a81910efc84
-  data.tar.gz: 26775e429aa90ffcf60ed7b1517f74744d7786f137890376b9263392fd1d5719
+  metadata.gz: a7aaa6b78cc06fac6720e3b95b382f2bc32b69d9cb8abe72ce9b0ab35c82561f
+  data.tar.gz: 8b908e0fdb79b0daee88070b2dd8121dad22c251328353759be555b30adf866b
 SHA512:
-  metadata.gz: 4185dc24785f9425db9089136725a30ca45995d5dc35883dec9cbdfd0cdb2a47105037d376bc37315097f3136d90c22e2521487bd42351593593b86ea1446b0a
-  data.tar.gz: f2e8f0558eec1d6cd83589695eddd3dca1703d65130f71530a23596f81540e3c3a3a6611cb5360cac95c3cdf97fa95bced0177c197b12ef4a58d4a82d790ff31
+  metadata.gz: a977ac62ae2eb47fde93099cc1583967da2186e87dc8aaa8f4bc5b613b50f70c160eb13ffa65327ca639d9a9d050e5b8561a975e39a30d34da7f85b9e1141eff
+  data.tar.gz: aa95121a61ce913be0702d1be6ee2d40d5ff83fbe080a1d59e8f63c30ecdc91a3f4056c832810b8dcf5922ebbf6e3a164ce6410d86959303fdb8584f349b5b14

data/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [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

@@ -27,6 +27,7 @@ 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)
 end
 ```
@@ -44,7 +45,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 (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.
 
 ### `overview` — read-only
 
@@ -63,10 +64,64 @@ 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.
+
+### `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,46 @@ 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)
+        {size: @resque.size(queue), jobs: to_array(@resque.peek(queue, offset, limit))}
+      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
+
       # Resque.redis_id can embed user:password@; only this stripped form
       # may reach tool responses.
       def redis_identifier
@@ -31,6 +95,102 @@ 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_failure(index, item)
+        payload = item["payload"] || {}
+        {
+          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"]
+        }
+      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/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::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,50 @@ 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
+
+          def args_preview(args)
+            truncate_text(JSON.generate(args), ARGS_PREVIEW_MAX)
+          end
+
+          def full_args(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[:class],
+            args: full_args(record[:args]),
+            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[:class],
+              args_preview: args_preview(record[:args]),
+              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"], args_preview: args_preview(job["args"])}
+          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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: resque-mcp
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Josch Bockler
@@ -92,7 +92,10 @@ files:
 - lib/resque/mcp/engine.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/version.rb
 - sig/resque/mcp.rbs
 homepage: https://github.com/jbockler/resque-mcp