sidekiq-mcp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 28a6841ac7244a9e2dbbacec82c6d68c8b6aad63577cfc5b8708a37979563b94
+  data.tar.gz: ba2b4d0631956b7542c5c908889fd97c27c125fb6d22158935107b966cd88bf7
+SHA512:
+  metadata.gz: '04795cdcb429dc3e0bc3e6cf1f2871edbb7fe71358cabb0616bfc46734c8676bfcbd1ca2c7f600dc98f0d52080489ba422febe57864768559a4c8452f2945c60'
+  data.tar.gz: a86fe4850fb9ebc357ccdd07cc2c130f7570835a44e75dea40171254db0a909db53379a99be241b6cd8a7a7fc0775aeef04f65d4389c8f548383a553554e54cd

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-08-04
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/README.md

@@ -0,0 +1,207 @@
+# Sidekiq MCP
+
+A Sidekiq plugin that provides an MCP (Model Context Protocol) server, enabling LLMs to interact with Sidekiq queues, statistics, and failed jobs through a standardized interface.
+
+## Available Tools
+
+The MCP server provides the following tools:
+
+### Statistics & Monitoring
+- `sidekiq_stats` - Get general Sidekiq statistics (processed, failed, busy, enqueued counts)
+- `job_class_stats` - Breakdown of job counts, retries, and error rates by class
+- `workers_count` - Show how many workers are running and busy
+- `queue_health` - Heuristics on whether queues are backed up or healthy
+
+### Queue Inspection  
+- `list_queues` - List all queues with sizes and latency
+- `queue_details` - Get detailed info about a specific queue including jobs
+- `busy_workers` - List currently busy workers and their job details
+
+### Job Management
+- `failed_jobs` - List failed jobs with error details
+- `list_retry_jobs` - List jobs in the retry set (jobs that failed but will be retried)
+- `list_scheduled_jobs` - List jobs in the scheduled set
+- `dead_jobs` - Show jobs in the dead set (jobs that have exhausted all retries)
+- `job_details` - Show args, error message, and history for a job by JID
+
+### Job Actions
+- `retry_job` - Retry a failed job by JID
+- `delete_failed_job` - Delete a failed job by JID  
+- `remove_job` - Remove a job from any set (queue/schedule/retry/dead) by JID
+- `reschedule_job` - Reschedule a job in the scheduled set to a new time
+- `kill_job` - Move a job from retry/scheduled set to the dead set
+- `clear_queue` - Clear all jobs from a specific queue (destructive operation)
+
+### Real-time Monitoring
+- `stream_stats` - Start streaming real-time Sidekiq statistics (use with SSE)
+- `process_set` - Get detailed information about all Sidekiq processes/workers
+
+
+## Example Prompts
+
+Once configured, you can ask your LLM:
+
+- "What's the current status of Sidekiq?"
+- "Show me the failed jobs and their error messages"
+- "List all queues and their health status"
+- "Which job classes have the highest error rates?"
+- "Show me details for job abc123"
+- "Retry the job with JID abc123"
+- "What jobs are currently running?"
+- "Are any queues backed up or unhealthy?"
+- "How many workers are busy right now?"
+- "Clear all jobs from the 'low_priority' queue"
+- "Reschedule job abc123 to run tomorrow at 9 AM"
+- "Move this failed job to the dead set"
+- "Start streaming live stats updates"
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'sidekiq-mcp'
+```
+
+And then execute:
+```bash
+bundle install
+```
+
+## Usage
+
+### Rails Integration
+
+The gem automatically integrates with Rails applications. Configure it in an initializer:
+
+```ruby
+# config/initializers/sidekiq_mcp.rb
+Sidekiq::Mcp.configure do |config|
+  config.enabled = true
+  config.path = "/sidekiq-mcp"
+  config.auth_token = Rails.application.credentials.sidekiq_mcp_token
+  config.sse_enabled = true # Enable Server-Sent Events for real-time updates
+end
+```
+
+The MCP server will be available at the configured path (default: `/sidekiq-mcp`).
+
+### Manual Setup (Non-Rails)
+
+For non-Rails applications, add the middleware to your Rack stack:
+
+```ruby
+require 'sidekiq/mcp'
+
+# Configure
+Sidekiq::Mcp.configure do |config|
+  config.auth_token = "your-secret-token"
+end
+
+# Add to your config.ru or middleware stack
+use Sidekiq::Mcp::Middleware
+```
+
+### Authentication
+
+The MCP server supports two authentication methods:
+
+1. **Bearer Token**: Include `Authorization: Bearer your-token` header
+2. **HTTP Basic Auth**: Use any username with your token as the password
+
+Example configuration for different MCP clients:
+
+#### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "sidekiq": {
+      "command": "curl",
+      "args": [
+        "-X", "POST",
+        "-H", "Content-Type: application/json",
+        "-H", "Authorization: Bearer your-secret-token",
+        "http://localhost:3000/sidekiq-mcp"
+      ]
+    }
+  }
+}
+```
+
+#### VS Code with Claude Extension
+
+Configure in your VS Code settings:
+
+```json
+{
+  "claude.mcpServers": {
+    "sidekiq": {
+      "url": "http://localhost:3000/sidekiq-mcp",
+      "headers": {
+        "Authorization": "Bearer your-secret-token"
+      }
+    }
+  }
+}
+```
+
+#### Cursor
+
+Add to your Cursor configuration:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "sidekiq": {
+        "command": ["curl"],
+        "args": [
+          "-X", "POST",
+          "-H", "Content-Type: application/json", 
+          "-H", "Authorization: Bearer your-secret-token",
+          "http://localhost:3000/sidekiq-mcp"
+        ]
+      }
+    }
+  }
+}
+```
+
+#### Claude Code
+
+Configure via CLI:
+
+```bash
+claude mcp add --transport http sidekiq-mcp-server http://localhost:3000/sidekiq-mcp
+```
+
+Or add to your MCP configuration:
+
+```json
+{
+  "sidekiq-mcp": {
+    "endpoint": "http://localhost:3000/sidekiq-mcp",
+    "auth": {
+      "type": "bearer",
+      "token": "your-secret-token"
+    }
+  }
+}
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests.
+
+The `example/` directory contains a sample Rails application demonstrating the integration.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/andrew/sidekiq-mcp.
+
+## License
+
+The gem is available as open source under the terms of the MIT License.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+task default: :test

data/lib/sidekiq/mcp/middleware.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "rack"
+require "base64"
+
+module Sidekiq
+  module Mcp
+    class Middleware
+      def initialize(app)
+        @app = app
+        @server = Server.new
+      end
+
+      def call(env)
+        request = Rack::Request.new(env)
+        
+        return @app.call(env) unless mcp_request?(request)
+        return unauthorized_response unless authorized?(request)
+        
+        if request.post?
+          handle_mcp_request(request)
+        else
+          method_not_allowed_response
+        end
+      end
+
+      private
+
+      def mcp_request?(request)
+        config = Sidekiq::Mcp.configuration || Sidekiq::Mcp::Configuration.new
+        request.path == config.path
+      end
+
+      def authorized?(request)
+        config = Sidekiq::Mcp.configuration || Sidekiq::Mcp::Configuration.new
+        
+        return true unless config.auth_token
+        
+        auth_header = request.env["HTTP_AUTHORIZATION"]
+        return false unless auth_header
+        
+        if auth_header.start_with?("Bearer ")
+          token = auth_header.split(" ", 2).last
+          token == config.auth_token
+        elsif auth_header.start_with?("Basic ")
+          # For Basic auth, expect username to be anything and password to be the token
+          encoded = auth_header.split(" ", 2).last
+          decoded = Base64.decode64(encoded)
+          _username, password = decoded.split(":", 2)
+          password == config.auth_token
+        else
+          false
+        end
+      end
+
+      def handle_mcp_request(request)
+        body = request.body.read
+        response = @server.handle_request(body)
+        
+        return no_content_response if response.nil?
+        
+        [
+          200,
+          {
+            "Content-Type" => "application/json",
+            "Access-Control-Allow-Origin" => "*",
+            "Access-Control-Allow-Methods" => "POST, OPTIONS",
+            "Access-Control-Allow-Headers" => "Content-Type, Authorization"
+          },
+          [response.to_json]
+        ]
+      rescue => e
+        error_response(e.message)
+      end
+
+      def unauthorized_response
+        [
+          401,
+          { "Content-Type" => "application/json" },
+          [{ error: "Unauthorized" }.to_json]
+        ]
+      end
+
+      def method_not_allowed_response
+        [
+          405,
+          { "Content-Type" => "application/json" },
+          [{ error: "Method not allowed" }.to_json]
+        ]
+      end
+
+      def no_content_response
+        [204, {}, []]
+      end
+
+      def error_response(message)
+        [
+          500,
+          { "Content-Type" => "application/json" },
+          [{ error: "Internal server error: #{message}" }.to_json]
+        ]
+      end
+    end
+  end
+end

data/lib/sidekiq/mcp/railtie.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module Sidekiq
+  module Mcp
+    class Railtie < Rails::Railtie
+      railtie_name :sidekiq_mcp
+
+      config.after_initialize do
+        # Auto-configure if in Rails environment
+        Rails.application.config.middleware.use Sidekiq::Mcp::Middleware
+        
+        # Add SSE middleware if enabled
+        if Sidekiq::Mcp.configuration&.sse_enabled != false
+          Rails.application.config.middleware.use Sidekiq::Mcp::SseMiddleware
+        end
+      end
+    end
+  end
+end

data/lib/sidekiq/mcp/routes.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Sidekiq
+  module Mcp
+    class Routes
+      def self.mount(app, path: "/sidekiq-mcp")
+        # Configure the MCP path
+        Sidekiq::Mcp.configure do |config|
+          config.path = path
+        end
+        
+        # Add the middleware to the Rack stack
+        app.use Sidekiq::Mcp::Middleware
+      end
+    end
+  end
+end

data/lib/sidekiq/mcp/server.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Sidekiq
+  module Mcp
+    class Server
+      PROTOCOL_VERSION = "2025-06-18"
+
+      def initialize
+        @tools = ToolsRegistry.new
+      end
+
+      def handle_request(body)
+        request = JSON.parse(body)
+        
+        case request["method"]
+        when "initialize"
+          handle_initialize(request)
+        when "tools/list"
+          handle_tools_list(request)
+        when "tools/call"
+          handle_tools_call(request)
+        when "notifications/initialized"
+          handle_initialized(request)
+        else
+          error_response(request["id"], -32601, "Method not found")
+        end
+      rescue JSON::ParserError
+        error_response(nil, -32700, "Parse error")
+      rescue => e
+        error_response(request&.dig("id"), -32603, "Internal error: #{e.message}")
+      end
+
+      private
+
+      def handle_initialize(request)
+        {
+          jsonrpc: "2.0",
+          id: request["id"],
+          result: {
+            protocolVersion: PROTOCOL_VERSION,
+            capabilities: {
+              tools: {}
+            },
+            serverInfo: {
+              name: "sidekiq-mcp",
+              version: Sidekiq::Mcp::VERSION
+            }
+          }
+        }
+      end
+
+      def handle_tools_list(request)
+        {
+          jsonrpc: "2.0",
+          id: request["id"],
+          result: {
+            tools: @tools.list
+          }
+        }
+      end
+
+      def handle_tools_call(request)
+        tool_name = request.dig("params", "name")
+        arguments = request.dig("params", "arguments") || {}
+        
+        result = @tools.call(tool_name, arguments)
+        
+        {
+          jsonrpc: "2.0",
+          id: request["id"],
+          result: {
+            content: [
+              {
+                type: "text",
+                text: result
+              }
+            ]
+          }
+        }
+      end
+
+      def handle_initialized(request)
+        # No response needed for notifications
+        nil
+      end
+
+      def error_response(id, code, message)
+        {
+          jsonrpc: "2.0",
+          id: id,
+          error: {
+            code: code,
+            message: message
+          }
+        }
+      end
+    end
+  end
+end