resque-mcp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1f899cb2c9bb3c59a5185841550784e81dac79b0848da767f1cd5a81910efc84
+  data.tar.gz: 26775e429aa90ffcf60ed7b1517f74744d7786f137890376b9263392fd1d5719
+SHA512:
+  metadata.gz: 4185dc24785f9425db9089136725a30ca45995d5dc35883dec9cbdfd0cdb2a47105037d376bc37315097f3136d90c22e2521487bd42351593593b86ea1446b0a
+  data.tar.gz: f2e8f0558eec1d6cd83589695eddd3dca1703d65130f71530a23596f81540e3c3a3a6611cb5360cac95c3cdf97fa95bced0177c197b12ef4a58d4a82d790ff31

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0]
+
+- Mountable Rails engine serving a stateless MCP Streamable HTTP endpoint (`POST` only; all other verbs answer 405).
+- `overview` tool: global Resque health snapshot (pending/processed/failed totals, queue count and sizes, worker counts) with an environment + Redis-target meta footer (Redis credentials stripped).
+- Mandatory bearer-token auth: `Resque::Mcp.configure { |c| c.auth_token = … }`; unauthenticated requests get 401 + `WWW-Authenticate: Bearer`, a blank configured token gets 503.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"resque-mcp" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["9265647+jbockler@users.noreply.github.com"](mailto:"9265647+jbockler@users.noreply.github.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Josch Bockler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,76 @@
+# 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
+
+- Ruby >= 3.2
+- Rails >= 7.2
+- Resque >= 2.7, < 4
+
+## Installation
+
+Not yet published to RubyGems. Until then, install from git:
+
+```ruby
+# Gemfile
+gem "resque-mcp", github: "jbockler/resque-mcp"
+```
+
+## Usage
+
+Mount the engine and configure the auth token:
+
+```ruby
+# config/routes.rb
+mount Resque::Mcp::Engine => "/resque-mcp"
+
+# config/initializers/resque_mcp.rb
+Resque::Mcp.configure do |c|
+  c.auth_token = Rails.application.credentials.dig(:resque_mcp, :token)
+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.
+
+Connect Claude Code:
+
+```sh
+claude mcp add --transport http resque https://your-app.example.com/resque-mcp \
+  --header "Authorization: Bearer <token>"
+```
+
+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.
+
+### `overview` — read-only
+
+Global Resque health snapshot; takes no parameters.
+
+```json
+{
+  "pending": 87, "processed": 1093421, "failed": 1342,
+  "queues": 6, "workers": 12, "working": 3,
+  "queue_sizes": { "default": 3, "mailers": 0, "imports": 84 },
+  "meta": { "environment": "production", "redis": "redis://prod-redis:6379/0/resque" }
+}
+```
+
+- `pending` and `queue_sizes` come from a single snapshot, so `pending` always equals the sum of `queue_sizes`.
+- `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.
+
+## 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.
+
+## 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).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "standard/rake"
+
+task default: %i[test standard]

data/app/controllers/resque/mcp/endpoint_controller.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Resque
+  module Mcp
+    class EndpointController < ActionController::API
+      before_action :require_auth_token, only: :handle
+
+      def handle
+        server = ServerFactory.build(environment: Rails.env.to_s)
+        transport = ::MCP::Server::Transports::StreamableHTTPTransport.new(
+          server, stateless: true, enable_json_response: true
+        )
+
+        status, headers, body = transport.handle_request(request)
+        headers.each { |key, value| response.set_header(key, value) }
+
+        payload = body.first
+        if payload
+          render json: payload, status: status
+        else
+          head status
+        end
+      end
+
+      def method_not_allowed
+        head :method_not_allowed
+      end
+
+      private
+
+      # No reliable boot-time hook exists (initializer ordering), so a
+      # missing token is caught per request: 503, never silently open.
+      def require_auth_token
+        configured = Resque::Mcp.config.auth_token
+        if configured.blank?
+          Rails.logger.error(
+            "resque-mcp: refusing to serve — Resque::Mcp.config.auth_token is not set. " \
+            "Set it in an initializer via Resque::Mcp.configure."
+          )
+          return head :service_unavailable
+        end
+
+        provided = request.authorization.to_s[/\ABearer (.+)\z/i, 1]
+        unless provided && ActiveSupport::SecurityUtils.secure_compare(provided, configured)
+          response.set_header("WWW-Authenticate", "Bearer")
+          head :unauthorized
+        end
+      end
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+Resque::Mcp::Engine.routes.draw do
+  post "/", to: "endpoint#handle"
+  match "/", to: "endpoint#method_not_allowed", via: :all
+end

data/lib/resque/mcp/adapter.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Resque
+  module Mcp
+    # The only code in the gem that talks to Resque. Rails-free.
+    class Adapter
+      def initialize(resque: ::Resque)
+        @resque = resque
+      end
+
+      # One queue_sizes snapshot, not Resque.info — info reruns the queue
+      # sweep, letting pending disagree with queue_sizes in one response.
+      def stats
+        queue_sizes = @resque.queue_sizes
+        {
+          pending: queue_sizes.values.sum,
+          processed: @resque::Stat[:processed],
+          failed: @resque::Failure.count,
+          queues: queue_sizes.size,
+          workers: @resque.workers.size,
+          working: @resque.working.size,
+          queue_sizes: queue_sizes
+        }
+      end
+
+      # Resque.redis_id can embed user:password@; only this stripped form
+      # may reach tool responses.
+      def redis_identifier
+        strip_userinfo(@resque.redis_id.to_s)
+      end
+
+      private
+
+      # Greedy to the last "@" — passwords may contain "@", "/", or spaces;
+      # over-stripping is acceptable, leaking is not.
+      def strip_userinfo(id)
+        id.sub(%r{\A(.*?://)?.*@}, '\1')
+      end
+    end
+  end
+end

data/lib/resque/mcp/configuration.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Resque
+  module Mcp
+    class Configuration
+      attr_accessor :auth_token
+    end
+  end
+end

data/lib/resque/mcp/engine.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module Resque
+  module Mcp
+    class Engine < ::Rails::Engine
+      isolate_namespace Resque::Mcp
+    end
+  end
+end

data/lib/resque/mcp/server_factory.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Resque
+  module Mcp
+    # Builds a fresh ::MCP::Server per request. The caller passes
+    # `environment` (the controller sends Rails.env); this file is Rails-free.
+    module ServerFactory
+      def self.build(environment: nil)
+        ::MCP::Server.new(
+          name: "resque-mcp",
+          version: Resque::Mcp::VERSION,
+          tools: [Tools::Overview],
+          server_context: {adapter: Adapter.new, environment: environment}
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Resque
+  module Mcp
+    module Tools
+      # Shared tool helpers: adapter access, response envelopes, meta footer.
+      class Base < ::MCP::Tool
+        class << self
+          private
+
+          def adapter(server_context)
+            server_context.fetch(:adapter)
+          end
+
+          def success_response(payload, server_context)
+            body = payload.merge(meta: meta_footer(server_context))
+            ::MCP::Tool::Response.new(
+              [{type: "text", text: JSON.generate(body)}],
+              structured_content: body
+            )
+          end
+
+          def error_response(message)
+            ::MCP::Tool::Response.new([{type: "text", text: message}], error: true)
+          end
+
+          def meta_footer(server_context)
+            {
+              environment: server_context[:environment],
+              redis: adapter(server_context).redis_identifier
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Resque
+  module Mcp
+    module Tools
+      class Overview < Base
+        tool_name "overview"
+        description "Global Resque health snapshot: pending/processed/failed totals, " \
+          "queue count, worker counts, Redis server, environment. Cheap; call this first."
+        input_schema(properties: {}, required: [])
+        annotations(read_only_hint: true)
+
+        # `**` tolerates unexpected client arguments, which would otherwise
+        # surface as opaque JSON-RPC internal errors.
+        def self.call(server_context:, **)
+          success_response(adapter(server_context).stats, server_context)
+        end
+      end
+    end
+  end
+end

data/lib/resque/mcp/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Resque
+  module Mcp
+    VERSION = "0.1.0"
+  end
+end

data/lib/resque/mcp.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "json"
+require "resque"
+require "mcp"
+require "zeitwerk"
+
+require_relative "mcp/version"
+
+module Resque
+  module Mcp
+    class Error < StandardError; end
+
+    class << self
+      def configure
+        yield config
+      end
+
+      def config
+        @config ||= Configuration.new
+      end
+
+      def reset_config!
+        @config = Configuration.new
+      end
+    end
+  end
+end
+
+loader = Zeitwerk::Loader.for_gem_extension(Resque)
+loader.ignore("#{__dir__}/mcp/version.rb")
+loader.ignore("#{__dir__}/mcp/engine.rb")
+loader.setup
+
+require_relative "mcp/engine" if defined?(Rails)

data/sig/resque/mcp.rbs

@@ -0,0 +1,5 @@
+module Resque
+  module Mcp
+    VERSION: String
+  end
+end

metadata

@@ -0,0 +1,124 @@
+--- !ruby/object:Gem::Specification
+name: resque-mcp
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Josch Bockler
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: resque
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: railties
+  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: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description: Exposes Resque queues, workers, and failed jobs to MCP clients via a
+  Streamable HTTP endpoint mounted in the host Rails app.
+email:
+- 9265647+jbockler@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/controllers/resque/mcp/endpoint_controller.rb
+- config/routes.rb
+- lib/resque/mcp.rb
+- lib/resque/mcp/adapter.rb
+- lib/resque/mcp/configuration.rb
+- lib/resque/mcp/engine.rb
+- lib/resque/mcp/server_factory.rb
+- lib/resque/mcp/tools/base.rb
+- lib/resque/mcp/tools/overview.rb
+- lib/resque/mcp/version.rb
+- sig/resque/mcp.rbs
+homepage: https://github.com/jbockler/resque-mcp
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/jbockler/resque-mcp
+  source_code_uri: https://github.com/jbockler/resque-mcp
+  changelog_uri: https://github.com/jbockler/resque-mcp/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: MCP server for Resque, mountable as a Rails engine.
+test_files: []