Hangfire MCP

Servidor MCP para gerenciar jobs em segundo plano do Hangfire

Documentação

Servidor Hangfire MCP

Um servidor Model Context Protocol (MCP) para gerenciar trabalhos em segundo plano do Hangfire diretamente do VS Code Copilot e outros clientes compatíveis com MCP. Monitore filas de trabalhos, tente novamente trabalhos com falha, gerencie tarefas recorrentes e visualize estatísticas em tempo real — tudo sem sair do seu editor.

Recursos

Gerenciamento de Trabalhos: Liste, visualize, tente novamente, exclua e reenfileire trabalhos
Trabalhos Recorrentes: Liste, visualize, dispare, pause e retome trabalhos recorrentes
Estatísticas: Visualize estatísticas do servidor, filas e servidores ativos
Descoberta Automática: Encontra automaticamente strings de conexão do appsettings.json
Painel Web: Interface web integrada com estatísticas em tempo real e gerenciamento de trabalhos

Início Rápido (Configuração em Um Clique)

# Clone the repo
git clone https://github.com/inansen/hangfire-mcp.git
cd hangfire-mcp

# Run cross-platform setup (Windows, macOS, Linux)
python setup.py

O script de configuração irá:

Criar um ambiente virtual
Instalar todas as dependências (incluindo o painel)
Solicitar sua string de conexão do SQL Server (ou ler de .vscode/mcp.json)
Criar a configuração MCP do VS Code
Testar a conexão
Opcionalmente iniciar o painel

Instalação

pip install hangfire-mcp

Ou com uvx:

uvx hangfire-mcp

Configuração

VS Code (Configurações Globais)

Adicione às suas configurações do VS Code (settings.json):

{
  "mcp": {
    "servers": {
      "hangfire-mcp": {
        "command": "uvx",
        "args": ["hangfire-mcp", "--workspace", "${workspaceFolder}"]
      }
    }
  }
}

VS Code (Por Projeto)

Crie .vscode/mcp.json no seu projeto:

{
  "servers": {
    "hangfire-mcp": {
      "command": "uvx",
      "args": ["hangfire-mcp", "--workspace", "${workspaceFolder}"]
    }
  }
}

Com String de Conexão Explícita

Use strings de conexão no estilo ODBC:

{
  "servers": {
    "hangfire-mcp": {
      "command": "python",
      "args": ["-m", "hangfire_mcp", "--workspace", "${workspaceFolder}"],
      "env": {
        "HANGFIRE_CONNECTION_STRING": "Driver={ODBC Driver 17 for SQL Server};Server=localhost;Database=Hangfire;UID=sa;PWD=yourpassword;Encrypt=no;"
      }
    }
  }
}

Nota: Este projeto usa pyodbc e requer strings de conexão no formato ODBC, não no formato ADO.NET.

Descoberta de String de Conexão

O servidor encontra strings de conexão nesta ordem de prioridade:

Argumento de linha de comando --connection-string
Variável de ambiente HANGFIRE_CONNECTION_STRING
Descoberta automática de ${workspaceFolder}/**/appsettings*.json
Configuração do usuário em ~/.config/hangfire-mcp/connections.json (Linux/macOS) ou %APPDATA%\hangfire-mcp\connections.json (Windows)
Use a ferramenta configure para defini-la manualmente

Ferramentas Disponíveis

Ferramentas de Trabalhos

Ferramenta	Descrição
`list_jobs`	Liste trabalhos por estado (Enfileirado, Processando, Concluído, Falhou, etc.)
`get_job`	Obtenha informações detalhadas do trabalho, incluindo argumentos e detalhes de exceção
`get_job_history`	Obtenha o histórico de estados de um trabalho
`retry_job`	Tente novamente um trabalho com falha
`delete_job`	Exclua um trabalho
`requeue_job`	Mova um trabalho de volta para a fila

Ferramentas de Trabalhos Recorrentes

Ferramenta	Descrição
`list_recurring_jobs`	Liste todos os trabalhos recorrentes com agendamentos cron
`get_recurring_job`	Obtenha detalhes do trabalho recorrente
`trigger_recurring_job`	Execute um trabalho recorrente imediatamente
`pause_recurring_job`	Pause execuções agendadas
`resume_recurring_job`	Retome um trabalho pausado

Ferramentas de Estatísticas

Ferramenta	Descrição
`get_stats`	Estatísticas do servidor (contagens de concluídos, falhas, processamento)
`list_queues`	Liste filas com contagens de trabalhos pendentes
`list_servers`	Liste servidores Hangfire ativos

Ferramenta de Configuração

Ferramenta	Descrição
`configure`	Defina a string de conexão para o workspace atual

Exemplos de Uso

No VS Code Copilot Chat:

User: Show me failed jobs
Agent: [calls list_jobs(state="Failed")]
      Found 3 failed jobs:
      | ID | State | Job Type | Created | Reason |
      |----|-------|----------|---------|--------|
      | 123 | Failed | OrderSyncJob.Execute | 2026-03-17 10:30 | Connection timeout |
      | 124 | Failed | EmailJob.Send | 2026-03-17 10:45 | SMTP error |

User: Retry job 123
Agent: [calls retry_job(job_id=123)]
      Job 123 has been requeued to 'default' queue.

User: When did CacheRefreshJob last run?
Agent: [calls get_recurring_job(job_id="CacheRefreshJob")]
      Recurring Job: CacheRefreshJob
      - Cron: 0 */5 * * * (every 5 minutes)
      - Last Run: 2026-03-17 12:55:00
      - Queue: default

User: Trigger CacheRefreshJob now
Agent: [calls trigger_recurring_job(job_id="CacheRefreshJob")]
      CacheRefreshJob has been triggered. New job ID: 456

Painel Web

O pacote inclui um painel web integrado para gerenciamento visual de trabalhos.

Instalação

pip install hangfire-mcp[dashboard]

Executando o Painel

# Windows
.\scripts\run-dashboard.ps1

# macOS / Linux
chmod +x scripts/run-dashboard.sh
./scripts/run-dashboard.sh

# Or manually (any platform)
export HANGFIRE_CONNECTION_STRING="Driver={ODBC Driver 17 for SQL Server};Server=localhost;Database=Hangfire;..."
python -m uvicorn hangfire_mcp.dashboard:app --host 127.0.0.1 --port 8080

Abra http://127.0.0.1:8080 no seu navegador.

Recursos do Painel

Estatísticas em Tempo Real: Contagens de Concluídos, Falhas, Processando, Enfileirados, Agendados
Lista de Trabalhos: Visualize todos os trabalhos com filtro por estado
Ações de Trabalhos: Tente novamente, exclua, visualize detalhes com um clique
Trabalhos Recorrentes: Pause, retome, dispare trabalhos recorrentes
Status do Servidor: Status Online/Ocioso/Offline com base no heartbeat
Atualização Automática: Atualiza a cada 10 segundos

Requisitos

Python 3.11+
SQL Server com banco de dados Hangfire
ODBC Driver 17 para SQL Server (ou compatível)

Desenvolvimento

# Clone the repository
git clone https://github.com/inansen/hangfire-mcp.git
cd hangfire-mcp

# Install all dependencies
pip install -e ".[dev]"

# Run tests
pytest

Contribuindo

Faça um fork do repositório
Crie um branch de recurso (git checkout -b feature/my-feature)
Faça commit das suas alterações (git commit -am 'Add my feature')
Envie para o branch (git push origin feature/my-feature)
Abra um Pull Request

Licença

MIT