sidekiq-mcp 0.1.0

data/lib/sidekiq/mcp/tools/queue_health_tool.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "../tool"
+require "sidekiq/api"
+
+module Sidekiq
+  module Mcp
+    module Tools
+      class QueueHealthTool < Tool
+        description "Heuristics on whether queues are backed up or healthy"
+
+        arguments do
+          optional(:latency_threshold).filled(:integer).value(gteq?: 1)
+          optional(:size_threshold).filled(:integer).value(gteq?: 1)
+        end
+
+        def perform(latency_threshold: 60, size_threshold: 100)
+          queues_health = Sidekiq::Queue.all.map do |queue|
+            latency = queue.latency
+            size = queue.size
+            
+            # Determine health status
+            health_issues = []
+            health_issues << "High latency (#{latency.round(2)}s)" if latency > latency_threshold
+            health_issues << "Large queue size (#{size} jobs)" if size > size_threshold
+            
+            health_status = health_issues.empty? ? "healthy" : "warning"
+            health_status = "critical" if health_issues.size > 1
+            
+            {
+              name: queue.name,
+              size: size,
+              latency: latency.round(2),
+              health_status: health_status,
+              issues: health_issues,
+              recommendations: generate_recommendations(health_issues, size, latency)
+            }
+          end
+          
+          overall_health = queues_health.any? { |q| q[:health_status] == "critical" } ? "critical" : 
+                          queues_health.any? { |q| q[:health_status] == "warning" } ? "warning" : "healthy"
+          
+          {
+            overall_health: overall_health,
+            thresholds: {
+              latency_threshold: latency_threshold,
+              size_threshold: size_threshold
+            },
+            queues: queues_health
+          }.to_json
+        end
+
+        private
+
+        def generate_recommendations(issues, size, latency)
+          recommendations = []
+          
+          if issues.any? { |i| i.include?("latency") }
+            recommendations << "Consider adding more workers or optimizing job performance"
+          end
+          
+          if issues.any? { |i| i.include?("size") }
+            recommendations << "Queue is backing up - check for worker issues or increase concurrency"
+          end
+          
+          if size > 1000
+            recommendations << "Very large queue - consider splitting into smaller queues or adding priority"
+          end
+          
+          if latency > 300
+            recommendations << "Extremely high latency - immediate attention required"
+          end
+          
+          recommendations
+        end
+      end
+    end
+  end
+end

data/lib/sidekiq/mcp/tools/remove_job_tool.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "../tool"
+require "sidekiq/api"
+
+module Sidekiq
+  module Mcp
+    module Tools
+      class RemoveJobTool < Tool
+        description "Remove a job from any set (queue/schedule/retry/dead) by JID"
+
+        arguments do
+          required(:jid).filled(:string)
+        end
+
+        def perform(jid:)
+          # Try to find and remove from retry set
+          retry_set = Sidekiq::RetrySet.new
+          if (job = retry_set.find_job(jid))
+            job.delete
+            return "Job #{jid} removed from retry set"
+          end
+          
+          # Try to find and remove from scheduled set
+          scheduled_set = Sidekiq::ScheduledSet.new
+          if (job = scheduled_set.find_job(jid))
+            job.delete
+            return "Job #{jid} removed from scheduled set"
+          end
+          
+          # Try to find and remove from dead set
+          dead_set = Sidekiq::DeadSet.new
+          if (job = dead_set.find_job(jid))
+            job.delete
+            return "Job #{jid} removed from dead set"
+          end
+          
+          # Try to find and remove from queues
+          Sidekiq::Queue.all.each do |queue|
+            if (job = queue.find_job(jid))
+              job.delete
+              return "Job #{jid} removed from queue '#{queue.name}'"
+            end
+          end
+          
+          "Job #{jid} not found in any queue or set"
+        end
+      end
+    end
+  end
+end

data/lib/sidekiq/mcp/tools/reschedule_job_tool.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "../tool"
+require "sidekiq/api"
+
+module Sidekiq
+  module Mcp
+    module Tools
+      class RescheduleJobTool < Tool
+        description "Reschedule a job in the scheduled set to a new time"
+
+        arguments do
+          required(:jid).filled(:string)
+          required(:new_time).filled(:string) # ISO 8601 format
+        end
+
+        def perform(jid:, new_time:)
+          begin
+            new_timestamp = Time.parse(new_time)
+          rescue ArgumentError
+            return "Invalid time format. Please use ISO 8601 format (e.g., '2024-12-25T10:00:00Z')"
+          end
+          
+          scheduled_set = Sidekiq::ScheduledSet.new
+          job = scheduled_set.find_job(jid)
+          
+          if job
+            old_time = job.at
+            job.reschedule(new_timestamp)
+            "Job #{jid} rescheduled from #{old_time} to #{new_timestamp}"
+          else
+            "Job #{jid} not found in scheduled set"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sidekiq/mcp/tools/retry_job_tool.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "../tool"
+require "sidekiq/api"
+
+module Sidekiq
+  module Mcp
+    module Tools
+      class RetryJobTool < Tool
+        description "Retry a specific failed job by its JID"
+
+        arguments do
+          required(:jid).filled(:string)
+        end
+
+        def perform(jid:)
+          retry_set = Sidekiq::RetrySet.new
+          job = retry_set.find_job(jid)
+          
+          if job
+            job.retry
+            "Job #{jid} has been retried successfully"
+          else
+            "Job #{jid} not found in retry set"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sidekiq/mcp/tools/sidekiq_stats_tool.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "../tool"
+require "sidekiq/api"
+
+module Sidekiq
+  module Mcp
+    module Tools
+      class SidekiqStatsTool < Tool
+        description "Get general Sidekiq statistics including processed, failed, busy, enqueued counts"
+
+        arguments do
+          # No arguments needed for general stats
+        end
+
+        def perform
+          stats = Sidekiq::Stats.new
+          {
+            processed: stats.processed,
+            failed: stats.failed,
+            busy: stats.workers_size,
+            enqueued: stats.enqueued,
+            scheduled: stats.scheduled_size,
+            retry: stats.retry_size,
+            dead: stats.dead_size,
+            default_queue_latency: stats.default_queue_latency
+          }.to_json
+        end
+      end
+    end
+  end
+end

data/lib/sidekiq/mcp/tools/stream_stats_tool.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "../tool"
+require "sidekiq/api"
+
+module Sidekiq
+  module Mcp
+    module Tools
+      class StreamStatsTool < Tool
+        description "Start streaming real-time Sidekiq statistics (use with SSE)"
+
+        arguments do
+          optional(:interval).filled(:integer).value(gteq?: 1, lteq?: 300) # 1-300 seconds
+        end
+
+        def perform(interval: 5)
+          # This tool is designed to work with SSE streaming
+          # In a real implementation, this would start a background task
+          # For now, we'll return the current stats with streaming info
+          
+          stats = Sidekiq::Stats.new
+          current_stats = {
+            timestamp: Time.now.utc.iso8601,
+            processed: stats.processed,
+            failed: stats.failed,
+            busy: stats.workers_size,
+            enqueued: stats.enqueued,
+            scheduled: stats.scheduled_size,
+            retry: stats.retry_size,
+            dead: stats.dead_size,
+            processes: stats.processes_size,
+            default_queue_latency: stats.default_queue_latency
+          }
+          
+          {
+            message: "Stats streaming initiated with #{interval}s interval",
+            current_stats: current_stats,
+            sse_endpoint: "/sidekiq-mcp/sse",
+            note: "Connect to SSE endpoint to receive real-time updates"
+          }.to_json
+        end
+      end
+    end
+  end
+end

data/lib/sidekiq/mcp/tools/workers_count_tool.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "../tool"
+require "sidekiq/api"
+
+module Sidekiq
+  module Mcp
+    module Tools
+      class WorkersCountTool < Tool
+        description "Show how many workers are running and busy"
+
+        arguments do
+          # No arguments needed
+        end
+
+        def perform
+          processes = Sidekiq::ProcessSet.new
+          
+          total_workers = 0
+          busy_workers = 0
+          processes_info = []
+          
+          processes.each do |process|
+            process_workers = process["concurrency"] || 0
+            process_busy = process["busy"] || 0
+            
+            total_workers += process_workers
+            busy_workers += process_busy
+            
+            processes_info << {
+              hostname: process["hostname"],
+              pid: process["pid"],
+              concurrency: process_workers,
+              busy: process_busy,
+              utilization: process_workers > 0 ? ((process_busy.to_f / process_workers) * 100).round(2) : 0,
+              started_at: process["started_at"]
+            }
+          end
+          
+          {
+            total_processes: processes.size,
+            total_workers: total_workers,
+            busy_workers: busy_workers,
+            idle_workers: total_workers - busy_workers,
+            overall_utilization: total_workers > 0 ? ((busy_workers.to_f / total_workers) * 100).round(2) : 0,
+            processes: processes_info
+          }.to_json
+        end
+      end
+    end
+  end
+end

data/lib/sidekiq/mcp/tools.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Sidekiq
+  module Mcp
+    module Tools
+    end
+    
+    class ToolsRegistry
+      def initialize
+        register_all_tools
+      end
+
+      def list
+        @tools.values
+      end
+
+      def call(tool_name, arguments)
+        tool_class = @tool_classes[tool_name]
+        return "Unknown tool: #{tool_name}" unless tool_class
+        
+        begin
+          tool_instance = tool_class.new
+          tool_instance.call(**arguments.transform_keys(&:to_sym))
+        rescue => e
+          "Error executing tool #{tool_name}: #{e.message}"
+        end
+      end
+
+      private
+
+      def register_all_tools
+        @tools = {}
+        @tool_classes = {}
+        
+        # Auto-discover all tool classes
+        tool_classes = [
+          Tools::SidekiqStatsTool,
+          Tools::QueueDetailsTool,
+          Tools::RetryJobTool,
+          Tools::FailedJobsTool,
+          Tools::JobClassStatsTool,
+          Tools::JobDetailsTool,
+          Tools::ListScheduledJobsTool,
+          Tools::ListRetryJobsTool,
+          Tools::DeadJobsTool,
+          Tools::WorkersCountTool,
+          Tools::QueueHealthTool,
+          Tools::RemoveJobTool,
+          Tools::ClearQueueTool,
+          Tools::RescheduleJobTool,
+          Tools::KillJobTool,
+          Tools::ProcessSetTool,
+          Tools::StreamStatsTool
+        ]
+        
+        # Also register original legacy tools
+        register_legacy_tools
+        
+        tool_classes.each do |tool_class|
+          tool_def = tool_class.to_tool_definition
+          @tools[tool_def[:name]] = tool_def
+          @tool_classes[tool_def[:name]] = tool_class
+        end
+      end
+      
+      def register_legacy_tools
+        # List queues tool
+        @tools["list_queues"] = {
+          name: "list_queues",
+          description: "List all Sidekiq queues with their sizes and latency information",
+          inputSchema: {
+            type: "object",
+            properties: {},
+            required: []
+          }
+        }
+        @tool_classes["list_queues"] = Class.new(Tool) do
+          def perform
+            queues = Sidekiq::Queue.all.map do |queue|
+              {
+                name: queue.name,
+                size: queue.size,
+                latency: queue.latency
+              }
+            end
+            queues.to_json
+          end
+        end
+        
+        # Busy workers tool  
+        @tools["busy_workers"] = {
+          name: "busy_workers",
+          description: "List currently busy workers and their job details",
+          inputSchema: {
+            type: "object",
+            properties: {},
+            required: []
+          }
+        }
+        @tool_classes["busy_workers"] = Class.new(Tool) do
+          def perform
+            workers = Sidekiq::Workers.new.map do |process_id, thread_id, work|
+              {
+                process_id: process_id,
+                thread_id: thread_id,
+                queue: work["queue"],
+                class: work["payload"]["class"],
+                args: work["payload"]["args"],
+                jid: work["payload"]["jid"],
+                run_at: work["run_at"]
+              }
+            end
+            workers.to_json
+          end
+        end
+
+        # Delete failed job tool
+        @tools["delete_failed_job"] = {
+          name: "delete_failed_job",
+          description: "Delete a specific failed job by its JID",
+          inputSchema: {
+            type: "object",
+            properties: {
+              jid: {
+                type: "string",
+                description: "Job ID of the failed job to delete"
+              }
+            },
+            required: ["jid"]
+          }
+        }
+        @tool_classes["delete_failed_job"] = Class.new(Tool) do
+          def perform(jid:)
+            retry_set = Sidekiq::RetrySet.new
+            job = retry_set.find_job(jid)
+            
+            if job
+              job.delete
+              "Job #{jid} has been deleted successfully"
+            else
+              "Job #{jid} not found in retry set"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sidekiq/mcp/version.rb

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

data/lib/sidekiq/mcp.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "mcp/version"
+require_relative "mcp/tool"
+require_relative "mcp/server"
+require_relative "mcp/tools"
+require_relative "mcp/middleware"
+require_relative "mcp/sse_middleware"
+require_relative "mcp/routes"
+
+# Load all tool classes
+Dir[File.join(__dir__, "mcp/tools/*.rb")].each { |file| require file }
+
+if defined?(Rails)
+  require_relative "mcp/railtie"
+end
+
+module Sidekiq
+  module Mcp
+    class Error < StandardError; end
+    
+    class << self
+      attr_accessor :configuration
+    end
+
+    def self.configure
+      self.configuration ||= Configuration.new
+      yield(configuration)
+    end
+
+    class Configuration
+      attr_accessor :enabled, :path, :auth_token, :sse_enabled
+
+      def initialize
+        @enabled = true
+        @path = "/sidekiq-mcp"
+        @auth_token = nil
+        @sse_enabled = true
+      end
+    end
+  end
+end

data/sig/sidekiq/mcp.rbs

@@ -0,0 +1,6 @@
+module Sidekiq
+  module Mcp
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,144 @@
+--- !ruby/object:Gem::Specification
+name: sidekiq-mcp
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Andrew Nesbitt
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sidekiq
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: dry-schema
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A Sidekiq plugin that provides an MCP (Model Context Protocol) server
+  for LLMs to interact with Sidekiq queues, stats, and failed jobs
+email:
+- andrewnez@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- README.md
+- Rakefile
+- lib/sidekiq/mcp.rb
+- lib/sidekiq/mcp/middleware.rb
+- lib/sidekiq/mcp/railtie.rb
+- lib/sidekiq/mcp/routes.rb
+- lib/sidekiq/mcp/server.rb
+- lib/sidekiq/mcp/sse_middleware.rb
+- lib/sidekiq/mcp/tool.rb
+- lib/sidekiq/mcp/tools.rb
+- lib/sidekiq/mcp/tools/clear_queue_tool.rb
+- lib/sidekiq/mcp/tools/dead_jobs_tool.rb
+- lib/sidekiq/mcp/tools/failed_jobs_tool.rb
+- lib/sidekiq/mcp/tools/job_class_stats_tool.rb
+- lib/sidekiq/mcp/tools/job_details_tool.rb
+- lib/sidekiq/mcp/tools/kill_job_tool.rb
+- lib/sidekiq/mcp/tools/list_retry_jobs_tool.rb
+- lib/sidekiq/mcp/tools/list_scheduled_jobs_tool.rb
+- lib/sidekiq/mcp/tools/process_set_tool.rb
+- lib/sidekiq/mcp/tools/queue_details_tool.rb
+- lib/sidekiq/mcp/tools/queue_health_tool.rb
+- lib/sidekiq/mcp/tools/remove_job_tool.rb
+- lib/sidekiq/mcp/tools/reschedule_job_tool.rb
+- lib/sidekiq/mcp/tools/retry_job_tool.rb
+- lib/sidekiq/mcp/tools/sidekiq_stats_tool.rb
+- lib/sidekiq/mcp/tools/stream_stats_tool.rb
+- lib/sidekiq/mcp/tools/workers_count_tool.rb
+- lib/sidekiq/mcp/version.rb
+- sig/sidekiq/mcp.rbs
+homepage: https://github.com/andrew/sidekiq-mcp
+licenses: []
+metadata:
+  homepage_uri: https://github.com/andrew/sidekiq-mcp
+  source_code_uri: https://github.com/andrew/sidekiq-mcp
+  changelog_uri: https://github.com/andrew/sidekiq-mcp/blob/main/CHANGELOG.md
+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: 3.6.9
+specification_version: 4
+summary: Sidekiq MCP server plugin for LLM integration
+test_files: []