JinDaGe - sidekiq-mcp MCP Details

article

README

🚀 Sidekiq MCP

Sidekiq MCP 是一款 Sidekiq 插件，它提供了一个 MCP（模型上下文协议）服务器，使大语言模型（LLMs）能够通过标准化接口与 Sidekiq 队列、统计信息和失败任务进行交互，为任务管理和监控提供了便捷的途径。

🚀 快速开始

安装

将以下代码添加到你的应用程序的 Gemfile 中：

gem 'sidekiq-mcp'

然后执行以下命令：

bundle install

使用

Rails 集成

该 gem 会自动与 Rails 应用程序集成。你可以在初始化文件中进行配置：

# 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 # 启用服务器发送事件以实现实时更新
end

MCP 服务器将在配置的路径下可用（默认：/sidekiq-mcp）。

手动设置（非 Rails）

对于非 Rails 应用程序，将中间件添加到你的 Rack 堆栈中：

require 'sidekiq/mcp'

# 配置
Sidekiq::Mcp.configure do |config|
  config.auth_token = "your-secret-token"
end

# 添加到你的 config.ru 或中间件堆栈
use Sidekiq::Mcp::Middleware

身份验证

MCP 服务器支持两种身份验证方法：

Bearer Token：在请求头中包含 Authorization: Bearer your-token。
HTTP 基本身份验证：使用任意用户名，将令牌作为密码。

以下是不同 MCP 客户端的配置示例：

Claude Desktop

将以下内容添加到你的 claude_desktop_config.json 中：

{
  "mcpServers": {
    "sidekiq": {
      "command": "curl",
      "args": [
        "-X", "POST",
        "-H", "Content-Type: application/json",
        "-H", "Authorization: Bearer your-secret-token",
        "http://localhost:3000/sidekiq-mcp"
      ]
    }
  }
}

带有 Claude 扩展的 VS Code

在你的 VS Code 设置中进行配置：

{
  "claude.mcpServers": {
    "sidekiq": {
      "url": "http://localhost:3000/sidekiq-mcp",
      "headers": {
        "Authorization": "Bearer your-secret-token"
      }
    }
  }
}

Cursor

将以下内容添加到你的 Cursor 配置中：

{
  "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

通过命令行界面进行配置：

claude mcp add --transport http sidekiq-mcp-server http://localhost:3000/sidekiq-mcp

或者将以下内容添加到你的 MCP 配置中：

{
  "sidekiq-mcp": {
    "endpoint": "http://localhost:3000/sidekiq-mcp",
    "auth": {
      "type": "bearer",
      "token": "your-secret-token"
    }
  }
}

✨ 主要特性

可用工具

MCP 服务器提供了以下工具：

统计与监控

sidekiq_stats - 获取 Sidekiq 的常规统计信息（已处理、失败、忙碌、排队的任务数量）。
job_class_stats - 按任务类列出任务数量、重试次数和错误率。
workers_count - 显示正在运行和忙碌的工作进程数量。
queue_health - 评估队列是否积压或健康。

队列检查

list_queues - 列出所有队列及其大小和延迟。
queue_details - 获取特定队列的详细信息，包括任务。
busy_workers - 列出当前忙碌的工作进程及其任务详情。

任务管理

failed_jobs - 列出失败的任务及其错误详情。
list_retry_jobs - 列出重试集中的任务（失败但将重试的任务）。
list_scheduled_jobs - 列出调度集中的任务。
dead_jobs - 显示死亡集中的任务（已耗尽所有重试次数的任务）。
job_details - 按任务 ID（JID）显示任务的参数、错误消息和历史记录。

任务操作

retry_job - 按任务 ID（JID）重试失败的任务。
delete_failed_job - 按任务 ID（JID）删除失败的任务。
remove_job - 按任务 ID（JID）从任何集合（队列/调度/重试/死亡）中移除任务。
reschedule_job - 将调度集中的任务重新安排到新的时间。
kill_job - 将任务从重试/调度集移动到死亡集。
clear_queue - 清除特定队列中的所有任务（破坏性操作）。

实时监控

stream_stats - 开始流式传输实时 Sidekiq 统计信息（与服务器发送事件一起使用）。
process_set - 获取所有 Sidekiq 进程/工作进程的详细信息。

示例提示

配置完成后，你可以向大语言模型提问：

"Sidekiq 的当前状态如何？"
"显示失败的任务及其错误消息。"
"列出所有队列及其健康状态。"
"哪些任务类的错误率最高？"
"显示任务 abc123 的详细信息。"
"重试 JID 为 abc123 的任务。"
"当前正在运行哪些任务？"
"是否有队列积压或不健康？"
"目前有多少工作进程忙碌？"
"清除 'low_priority' 队列中的所有任务。"
"将任务 abc123 重新安排到明天上午 9 点运行。"
"将这个失败的任务移动到死亡集。"
"开始流式传输实时统计更新。"

🛠️ 开发

检出仓库后，运行 bin/setup 安装依赖项。然后，运行 rake test 运行测试。example/ 目录包含一个示例 Rails 应用程序，展示了集成方法。

🤝 贡献

欢迎在 GitHub（https://github.com/andrew/sidekiq-mcp）上提交错误报告和拉取请求。

📄 许可证

该 gem 以开源形式提供，遵循 MIT 许可证。

sidekiq-mcp