Metadata-Version: 2.5
Name: argonaut-mcp-server
Version: 0.2.1
Summary: Servidor MCP para descobrir, inspecionar e diagnosticar filas e tópicos (Redis Streams, Kafka, RabbitMQ, SQS, SNS).
Author: KauaLealz
License-Expression: MIT
License-File: LICENSE
Keywords: diagnostics,kafka,mcp,message-queue,model-context-protocol,observability,rabbitmq,redis-streams,sns,sqs
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.11
Requires-Dist: cryptography>=43.0
Requires-Dist: mcp<2,>=1.6
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: all
Requires-Dist: boto3>=1.34; extra == 'all'
Requires-Dist: confluent-kafka>=2.3; extra == 'all'
Requires-Dist: redis>=5.0; extra == 'all'
Requires-Dist: requests>=2.31; extra == 'all'
Provides-Extra: aws
Requires-Dist: boto3>=1.34; extra == 'aws'
Provides-Extra: dev
Requires-Dist: boto3>=1.34; extra == 'dev'
Requires-Dist: fakeredis>=2.21; extra == 'dev'
Requires-Dist: moto[cloudwatch,sns,sqs]>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: redis>=5.0; extra == 'dev'
Requires-Dist: requests>=2.31; extra == 'dev'
Provides-Extra: kafka
Requires-Dist: confluent-kafka>=2.3; extra == 'kafka'
Provides-Extra: rabbitmq
Requires-Dist: requests>=2.31; extra == 'rabbitmq'
Provides-Extra: redis
Requires-Dist: redis>=5.0; extra == 'redis'
Description-Content-Type: text/markdown

# argonaut-mcp-server

> Servidor [MCP](https://modelcontextprotocol.io) 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](https://github.com/KauaLealz/nautilus-mcp-server): 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.

| Tool | Modo | O que faz |
|------|------|-----------|
| `list_connections` | readonly | Conexões configuradas, com tipo e modo |
| `list_destinations` | readonly | Filas, tópicos e streams (filtro por glob) |
| `describe_destination` | readonly | Atributos nativos, DLQ e configuração |
| `get_stats` | readonly | Profundidade, em voo, idade da mais antiga, taxas |
| `list_consumer_groups` | readonly | Grupos, membros e estado |
| `get_consumer_lag` | readonly | Lag por grupo e partição |
| `get_topology` | readonly | Bindings do RabbitMQ e subscriptions do SNS |
| `peek_messages` | readonly¹ | Leitura sem consumir |
| `get_message` | readonly | Uma mensagem por posição (offset, id) |
| `publish_message` | operator | Publica uma mensagem |
| `redrive_dlq` | operator | Move mensagens da DLQ de volta à origem |
| `reset_offsets` | operator | Reposiciona um consumer group |
| `reclaim_pending` | operator | Reatribui mensagens pendentes travadas (Redis) |
| `purge` | admin | Esvazia um destino |
| `create_destination` / `delete_destination` | admin | Cria/remove destinos |
| `update_attributes` | admin | Altera retenção, visibility timeout, políticas |
| `delete_consumer_group` | admin | Remove um grupo inativo |

¹ `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

```bash
# 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)

```bash
argonaut-admin keygen        # imprime a chave; guarde-a e use como ARGONAUT_KEY
```

### 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):

```bash
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`](./argonaut.example.yaml)):

```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

As **únicas** variáveis de ambiente são `ARGONAUT_CONFIG` (caminho do YAML) e `ARGONAUT_KEY` (a mesma chave do `keygen`, que decifra as senhas):

```json
{
  "mcpServers": {
    "argonaut": {
      "command": "uvx",
      "args": ["--from", "argonaut-mcp-server[all]", "argonaut"],
      "env": {
        "ARGONAUT_CONFIG": "C:/caminho/para/argonaut.yaml",
        "ARGONAUT_KEY": "a-chave-gerada-por-argonaut-admin-keygen"
      }
    }
  }
}
```

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 só em `ARGONAUT_KEY`); payloads truncados e com dados sensíveis redigidos; conteúdo de mensagem marcado como `untrusted`; auditoria JSON lines de toda escrita (inclusive dry-runs).
