argonaut-mcp-server

Servidor MCP para descobrir, inspecionar e diagnosticar filas e tópicos — Redis Streams, Kafka, RabbitMQ, Amazon SQS e SNS — com senhas cifradas e escrita protegida por modo, allowlist e confirmação em duas etapas.

Faz par com o Nautilus: Nautilus para bancos, Argonaut para mensageria.

O que faz

Responde perguntas de diagnóstico de mensageria — "por que essa fila está crescendo?", "qual consumer group está atrasado?", "o que tem na DLQ?", "por que a mensagem publicada no SNS não chegou na fila X?" — e, quando preciso, resolve (redrive, purge, reset) sempre atrás de proteções.

¹ peek_messages com accept_side_effects=true (leitura que altera estado, como em SQS e filas clássicas do RabbitMQ) exige modo operator. Há ainda o resource argonaut://{conexão}/{destino} e prompts de diagnóstico (investigar_backlog, analisar_dlq, rastrear_mensagem_sns).

Requisitos

• Python 3.11+.
• Drivers por broker são extras opcionais: redis, kafka, rabbitmq, aws (ou all). Instale os que for usar.

Instalação

# Executar direto (todos os brokers), via uv:
uvx --from "argonaut-mcp-server[all]" argonaut

# Ou instalar servidor + CLI `argonaut-admin` no sistema (só os brokers que usa):
uv tool install "argonaut-mcp-server[redis,kafka]"
# (alternativa: pip install "argonaut-mcp-server[all]")

Configuração

1. Gere a chave de criptografia (uma vez)

argonaut-admin keygen        # gera e salva a chave em ~/.argonaut/key

Servidor e CLI leem a chave desse arquivo — não precisa setar nada no ambiente. (Em CI/containers, ARGONAUT_KEY no ambiente tem precedência sobre o arquivo.)

2. Cadastre as conexões pela CLI

Toda adição/alteração/remoção passa pela CLI argonaut-admin, que edita o YAML e cifra a senha ao salvar (incluindo sasl.password do Kafka):

argonaut-admin add redis-dev   # pergunta os campos conforme o tipo de broker (senha oculta)
argonaut-admin list            # lista as conexões (nunca mostra a senha)
argonaut-admin edit redis-dev  # altera campos; senha em branco mantém a atual
argonaut-admin remove redis-dev

O arquivo resultante (veja argonaut.example.yaml):

defaults:
  peek: { max_messages: 20, max_payload_bytes: 4096 }
  confirm_token_ttl: 120s
  audit_log: ./argonaut-audit.jsonl
  redact:
    patterns: [cpf, email, credit_card]
connections:
  redis-dev:
    type: redis_streams       # redis_streams | kafka | rabbitmq | aws (SQS+SNS)
    url: "redis://localhost:6379/0"
    mode: admin               # readonly | operator | admin
    dlq_convention: "{name}:dlq"

• Sem ${VAR}: todos os valores vão literais no YAML; só a senha é cifrada.

3. Aponte o cliente MCP para o servidor

Nenhuma variável de ambiente é necessária. Por padrão, o servidor lê o YAML de ~/.argonaut/argonaut.yaml e a chave de ~/.argonaut/key — ambos criados pelos passos acima:

{
  "mcpServers": {
    "argonaut": {
      "command": "uvx",
      "args": ["--from", "argonaut-mcp-server[all]", "argonaut"],
      "env": {}
    }
  }
}

Caminhos personalizados (opcional): ARGONAUT_CONFIG aponta o YAML para outro lugar; ARGONAUT_KEY (ou ARGONAUT_KEY_FILE) define a chave para CI/containers. Sem eles, usa-se o padrão em ~/.argonaut/.

O mesmo bloco vale para Cursor, Claude Desktop, Claude Code e outras IDEs com MCP por stdio.

Segurança

O padrão é readonly. Toda escrita exige:

1. Modo por conexão (readonly ⊂ operator ⊂ admin) — promover é mudança de config, nunca de runtime.
2. Allowlist/denylist por glob — destino negado não aparece nem na listagem.
3. Confirmação em duas etapas — a 1ª chamada é dry-run e devolve o impacto ("vai apagar 48.213 mensagens de orders.dlq") + um token de TTL curto vinculado ao hash dos argumentos; a execução só ocorre na 2ª chamada com esse token.

Além disso: senha sempre cifrada (enc:, chave em ~/.argonaut/key ou ARGONAUT_KEY, fora do YAML — não compartilhe o arquivo de chave); payloads truncados e com dados sensíveis redigidos; conteúdo de mensagem marcado como untrusted; auditoria JSON lines de toda escrita (inclusive dry-runs).