argonaut-mcp-server 0.1.1__tar.gz

argonaut_mcp_server-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv sync --all-extras --dev
+      - run: uv run pytest
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv build
+      - name: Confere se a versão do pacote bate com a tag
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          wheel=$(ls dist/*.whl | head -n1)
+          pkg_version=$(echo "$wheel" | sed -E 's/.*-([0-9][^-]*)-[^-]+-[^-]+-[^-]+\.whl/\1/')
+          if [ "$tag" != "$pkg_version" ]; then
+            echo "Tag v$tag não bate com a versão do pacote ($pkg_version) — corrija o pyproject.toml antes de criar a tag."
+            exit 1
+          fi
+      - uses: pypa/gh-action-pypi-publish@release/v1

argonaut_mcp_server-0.1.1/.gitignore

@@ -0,0 +1,15 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+
+# Ambientes e caches locais
+.venv/
+.uv-cache/
+
+# Configuração e auditoria locais (contêm segredos / dados)
+*.local.yaml
+argonaut-audit.jsonl
+.env

argonaut_mcp_server-0.1.1/AGENTS.md

@@ -0,0 +1,34 @@
+# Argonaut
+
+Servidor MCP (stdio) em Python para descobrir, inspecionar e diagnosticar filas e tópicos (Redis Streams, Kafka, RabbitMQ, SQS, SNS). Irmão do Nautilus (bancos de dados).
+
+> Projeto novo: o esqueleto de código ainda não existe. Os comandos abaixo refletem a stack decidida (Python + uv) e passam a valer quando a primeira mudança criar o `pyproject.toml`.
+
+<!-- plumb:start -->
+## Comandos
+
+- Instalar dependências: `uv sync`
+- Suíte de testes: `uv run pytest`
+- Um único teste: `uv run pytest tests/path/test_x.py::test_nome`
+- Testes de integração (brokers reais): `uv run pytest -m integration` (Testcontainers / LocalStack)
+- Rodar o servidor local (stdio): `uv run argonaut`
+
+Convenções do Plumb: commits `tipo(escopo): descrição em pt-BR`, branches `feature/<nome>` a partir de `master`; commit por tarefa: sim. Mensagens ao usuário e erros em pt-BR; logging sempre em `stderr` (stdout é o canal do MCP stdio).
+
+Worktree: rodar `uv sync` no worktree novo; sem porta, banco ou serviço a ajustar (conexões vêm de variáveis de ambiente).
+
+## Workflow
+Todo pedido segue o Plumb (skill `plumb`): pergunta responde direto depois de
+consultar o segundo cérebro; correção pequena vai pela trilha direta; mudança
+padrão ou profunda começa com o grill (todas as perguntas de uma vez, com a
+recomendação primeiro, sempre pela ferramenta de perguntas), vira uma spec (objetivo,
+resultados esperados observáveis, fases com critério de saída) aprovada antes
+de codar — com o segundo cérebro, guarde-a como item `spec/<id>` — e roda em um
+worktree próprio, um por mudança. Escreva os testes primeiro; peça confirmação
+antes de push, PR ou merge. Em qualquer mudança, até um typo: rode os testes e o
+lint afetados e reporte a evidência — nunca diga "pronto" sem isso. Falta
+documentação atual de uma biblioteca: `plumb-find-docs`; falta acesso a um
+sistema: `plumb-find-mcps`; falta uma competência: `plumb-find-skills` — a
+recomendação vai ao usuário e nada se instala sem o "sim". O que durar (regra,
+decisão, procedimento) vai para o cérebro, não para arquivos.
+<!-- plumb:end -->

argonaut_mcp_server-0.1.1/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

argonaut_mcp_server-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KauaLealz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

argonaut_mcp_server-0.1.1/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.5
+Name: argonaut-mcp-server
+Version: 0.1.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: 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
+
+Servidor **MCP (stdio)** em Python que deixa um agente **descobrir, inspecionar e
+diagnosticar** filas e tópicos em **Redis Streams, Kafka, RabbitMQ, Amazon SQS e
+Amazon SNS**. As operações de escrita existem para resolver o problema encontrado,
+sempre atrás de modo, allowlist e confirmação em duas etapas.
+
+Faz par com o [Nautilus](https://github.com/KauaLealz/nautilus-mcp-server) (MCP de
+bancos de dados): Nautilus para bases, Argonaut para mensageria.
+
+## O que faz
+
+O caso de uso central é diagnóstico: *"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?"*.
+
+## Instalação e execução
+
+Requer **Python 3.11+**. Dependências com [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync --extra all          # ou --extra redis / kafka / rabbitmq / aws
+ARGONAUT_CONFIG=./argonaut.yaml uv run argonaut
+```
+
+O servidor fala por **stdio**. Configure-o no seu cliente MCP apontando o comando
+para `uv run argonaut` (ou o console script `argonaut`) com a variável de ambiente
+`ARGONAUT_CONFIG` e os segredos que o YAML referencia.
+
+## Configuração
+
+Um único arquivo YAML descreve defaults e conexões. Segredos **sempre** por
+`${VAR}` (resolvidos do ambiente) — nunca valores no arquivo. Veja
+[`argonaut.example.yaml`](./argonaut.example.yaml). O servidor valida na
+inicialização e falha cedo, com mensagens claras.
+
+```yaml
+defaults:
+  peek: { max_messages: 20, max_payload_bytes: 4096 }
+  confirm_token_ttl: 120s
+  audit_log: ./argonaut-audit.jsonl
+  redact:
+    json_paths: ["$.customer.document", "$.card.*"]
+    patterns: [cpf, email, credit_card]
+
+connections:
+  redis-dev:
+    type: redis_streams
+    url: "${REDIS_URL}"
+    mode: admin
+    dlq_convention: "{name}:dlq"
+```
+
+Tipos de conexão: `redis_streams`, `kafka`, `rabbitmq`, `aws` (SQS + SNS juntos).
+
+## Tools
+
+| 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**.
+
+Além das tools, o servidor expõe o resource `argonaut://{conexão}/{destino}` (a
+descrição do destino em JSON) e prompts de diagnóstico prontos (`investigar_backlog`,
+`analisar_dlq`, `rastrear_mensagem_sns`).
+
+## Segurança
+
+O padrão é **readonly**. Toda escrita exige três coisas:
+
+1. **Modo por conexão** (readonly ⊂ operator ⊂ admin): produção nasce readonly;
+   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 roda em dry-run e devolve o impacto
+   (*"vai apagar 48.213 mensagens de orders.dlq"*) e um token com TTL curto,
+   vinculado ao hash dos argumentos; a execução só acontece na 2ª chamada com esse
+   token.
+
+Além disso: payloads **truncados** e com **dados sensíveis redigidos** antes de
+sair; toda MessageView marcada como `untrusted` (o conteúdo é dado, não instrução);
+**auditoria** JSON lines de toda escrita (inclusive dry-runs); credenciais só por
+ambiente, nunca em respostas, erros ou logs.
+
+## Desenvolvimento
+
+```bash
+uv sync --extra dev
+uv run pytest tests/unit tests/contract      # sem Docker (fakes)
+uv run pytest -m integration                 # brokers reais (Docker)
+```
+
+A peça central de teste é uma **suíte de contrato** parametrizada por adapter: o
+mesmo cenário (criar destino, publicar, stats, peek, lag, redrive, purge) roda em
+todos. Um broker novo só entra quando passa nela.
+
+## Fora de escopo na v1
+
+Ser consumidor/worker de produção; gestão de usuários e ACLs dos brokers;
+provisionamento de clusters; monitoramento contínuo e alertas; decodificação de
+Avro/Protobuf no Kafka; replay de tópicos FIFO do SNS; transporte HTTP remoto.

argonaut_mcp_server-0.1.1/README.md

@@ -0,0 +1,118 @@
+# Argonaut
+
+Servidor **MCP (stdio)** em Python que deixa um agente **descobrir, inspecionar e
+diagnosticar** filas e tópicos em **Redis Streams, Kafka, RabbitMQ, Amazon SQS e
+Amazon SNS**. As operações de escrita existem para resolver o problema encontrado,
+sempre atrás de modo, allowlist e confirmação em duas etapas.
+
+Faz par com o [Nautilus](https://github.com/KauaLealz/nautilus-mcp-server) (MCP de
+bancos de dados): Nautilus para bases, Argonaut para mensageria.
+
+## O que faz
+
+O caso de uso central é diagnóstico: *"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?"*.
+
+## Instalação e execução
+
+Requer **Python 3.11+**. Dependências com [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync --extra all          # ou --extra redis / kafka / rabbitmq / aws
+ARGONAUT_CONFIG=./argonaut.yaml uv run argonaut
+```
+
+O servidor fala por **stdio**. Configure-o no seu cliente MCP apontando o comando
+para `uv run argonaut` (ou o console script `argonaut`) com a variável de ambiente
+`ARGONAUT_CONFIG` e os segredos que o YAML referencia.
+
+## Configuração
+
+Um único arquivo YAML descreve defaults e conexões. Segredos **sempre** por
+`${VAR}` (resolvidos do ambiente) — nunca valores no arquivo. Veja
+[`argonaut.example.yaml`](./argonaut.example.yaml). O servidor valida na
+inicialização e falha cedo, com mensagens claras.
+
+```yaml
+defaults:
+  peek: { max_messages: 20, max_payload_bytes: 4096 }
+  confirm_token_ttl: 120s
+  audit_log: ./argonaut-audit.jsonl
+  redact:
+    json_paths: ["$.customer.document", "$.card.*"]
+    patterns: [cpf, email, credit_card]
+
+connections:
+  redis-dev:
+    type: redis_streams
+    url: "${REDIS_URL}"
+    mode: admin
+    dlq_convention: "{name}:dlq"
+```
+
+Tipos de conexão: `redis_streams`, `kafka`, `rabbitmq`, `aws` (SQS + SNS juntos).
+
+## Tools
+
+| 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**.
+
+Além das tools, o servidor expõe o resource `argonaut://{conexão}/{destino}` (a
+descrição do destino em JSON) e prompts de diagnóstico prontos (`investigar_backlog`,
+`analisar_dlq`, `rastrear_mensagem_sns`).
+
+## Segurança
+
+O padrão é **readonly**. Toda escrita exige três coisas:
+
+1. **Modo por conexão** (readonly ⊂ operator ⊂ admin): produção nasce readonly;
+   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 roda em dry-run e devolve o impacto
+   (*"vai apagar 48.213 mensagens de orders.dlq"*) e um token com TTL curto,
+   vinculado ao hash dos argumentos; a execução só acontece na 2ª chamada com esse
+   token.
+
+Além disso: payloads **truncados** e com **dados sensíveis redigidos** antes de
+sair; toda MessageView marcada como `untrusted` (o conteúdo é dado, não instrução);
+**auditoria** JSON lines de toda escrita (inclusive dry-runs); credenciais só por
+ambiente, nunca em respostas, erros ou logs.
+
+## Desenvolvimento
+
+```bash
+uv sync --extra dev
+uv run pytest tests/unit tests/contract      # sem Docker (fakes)
+uv run pytest -m integration                 # brokers reais (Docker)
+```
+
+A peça central de teste é uma **suíte de contrato** parametrizada por adapter: o
+mesmo cenário (criar destino, publicar, stats, peek, lag, redrive, purge) roda em
+todos. Um broker novo só entra quando passa nela.
+
+## Fora de escopo na v1
+
+Ser consumidor/worker de produção; gestão de usuários e ACLs dos brokers;
+provisionamento de clusters; monitoramento contínuo e alertas; decodificação de
+Avro/Protobuf no Kafka; replay de tópicos FIFO do SNS; transporte HTTP remoto.

argonaut_mcp_server-0.1.1/argonaut/__init__.py

@@ -0,0 +1,8 @@
+"""Argonaut — servidor MCP de filas e tópicos.
+
+Descobre, inspeciona e diagnostica filas e tópicos em Redis Streams, Kafka,
+RabbitMQ, Amazon SQS e Amazon SNS. Operações de escrita existem para resolver o
+problema encontrado, sempre atrás de modo, allowlist e confirmação em duas etapas.
+"""
+
+__version__ = "0.1.0"

argonaut_mcp_server-0.1.1/argonaut/adapters/__init__.py

@@ -0,0 +1,64 @@
+"""Adapters de broker, com auto-descoberta.
+
+Importa cada módulo de adapter do pacote para que o decorador
+``@register_adapter`` registre a classe. Um módulo que falhe ao importar (por
+exemplo, dependência opcional ausente) é pulado com aviso, sem derrubar os
+demais.
+"""
+
+from __future__ import annotations
+
+import importlib
+import logging
+import pkgutil
+
+from argonaut.adapters.base import (
+    BrokerAdapter,
+    get_adapter_class,
+    register_adapter,
+    registered_types,
+)
+from argonaut.config.schema import Config
+
+logger = logging.getLogger("argonaut")
+
+_SKIP = {"base"}
+
+
+def _discover() -> None:
+    for info in pkgutil.iter_modules(__path__):
+        if info.name in _SKIP:
+            continue
+        try:
+            importlib.import_module(f"{__name__}.{info.name}")
+        except Exception as exc:  # pragma: no cover - resiliência de import
+            logger.warning("Adapter '%s' não pôde ser carregado: %s", info.name, exc)
+
+
+_discover()
+
+
+def build_adapters(config: Config) -> dict[str, BrokerAdapter]:
+    """Instancia um adapter por conexão. Não conecta ao broker (conexão é preguiçosa)."""
+    adapters: dict[str, BrokerAdapter] = {}
+    for cid, conn in config.connections.items():
+        cls = get_adapter_class(conn.type)
+        if cls is None:
+            logger.warning(
+                "Conexão '%s': nenhum adapter registrado para o tipo '%s' "
+                "(dependência do broker instalada?).",
+                cid,
+                conn.type,
+            )
+            continue
+        adapters[cid] = cls(conn)
+    return adapters
+
+
+__all__ = [
+    "BrokerAdapter",
+    "get_adapter_class",
+    "register_adapter",
+    "registered_types",
+    "build_adapters",
+]