Skip to main content
Glama
YouShop Radar MCP

YouShop Radar MCP

by Marcus-luz

YouShop Radar MCP

CI — YouShop Radar MCP

Protótipo funcional de um servidor MCP (Model Context Protocol, via SDK Python v2) somente leitura para apoiar gerentes de contas do Comercial na detecção preventiva de risco de churn de produtores — correlacionando falhas técnicas de webhook, queda de vendas contra baseline e tickets críticos abertos com isolamento de carteira fail-closed e minimização de dados via Allowlist.


Problema e Proposta de Valor

Sinais de risco de um produtor costumam ficar dispersos entre áreas diferentes: falhas de integração (Engenharia/Webhooks), queda de conversão (Vendas) e tickets críticos abertos (Suporte). Quando o Comercial descobre, o produtor já migrou sua operação ou comprometeu o lançamento dos seus creators.

O YouShop Radar MCP organiza esse fluxo em três pilares:

  1. Cálculo determinístico fora do LLM: o score de risco (0 a 100), a distinção entre erro crítico/desconhecido (alerta_tecnico_precoce) e erro estritamente auxiliar (falso_alarme_tecnico) e o tratamento de ausência de baseline são calculados em Python auditável.

  2. IA onde gera valor: correlacionar sinais de múltiplas áreas, explicar prioridades em linguagem acessível para times não técnicos e redigir rascunhos consultivos de contato — com verificador automático tipado auditando métricas e regras por cena antes de gravar o replay.

  3. Segurança e controle humano por padrão: servidor estritamente somente leitura, sessão fail-closed, resposta única anti-enumeração, sanitização de entradas e valores contra prompt injection e Human-in-the-Loop obrigatório (o agente nunca envia mensagens nem altera dados).


Related MCP server: Territory News MCP Server

Arquitetura em 3 Camadas

youshop-radar-mcp/
├── src/youshop_radar/
│   ├── config.py               # Pesos, limiares, janelas, listas fechadas e sessão fail-closed
│   ├── data/                   # Camada de Dados (SQLite readonly + seed=42)
│   │   ├── database.py
│   │   ├── seed.py
│   │   └── repository.py       # Busca por manager_id, janela semiaberta (>=, <) e tickets de qualquer idade
│   ├── domain/                 # Camada de Negócio e Segurança (Python puro)
│   │   ├── scoring.py          # Score 0–100 + alerta técnico precoce / falso alarme / sem_baseline
│   │   └── security.py         # Isolamento por carteira, anti-enumeração e sanitização Allowlist
│   └── mcp_server/             # Adaptador fino via MCP SDK Python v2 (stdio)
│       ├── playbooks.py        # Resource (guia de exemplo) + Prompt HITL com validação de canal e ref
│       └── server.py           # MCPServer com ToolError limpo expondo 3 Tools, 1 Resource e 1 Prompt
├── demo_client/
│   └── groq_client.py          # Cliente MCP desacoplado + verificador numérico tipado com bloqueio
├── docs/
│   ├── index.html              # Interface interativa de replay no GitHub Pages
│   └── replay_data.json        # Gravação real das 5 cenas + payloads MCP + auditoria tipada
├── tests/                      # 27 testes (domínio, segurança, E2E stdio e integridade do replay)
└── LICENSE                     # Licença MIT

Primitivas MCP Expostas

Tipo

Nome / URI

Descrição

Tool

list_at_risk_producers(min_score=50)

Lista produtores da carteira autenticada ordenados por score de risco.

Tool

get_producer_signals(producer_ref)

Detalha sinais dos últimos 7 dias vs. baseline de 21 dias (webhooks, vendas, tickets abertos de qualquer idade, creators).

Tool

get_signal_history(producer_ref, weeks=4)

Evolução semanal (1 a 4 semanas) para identificar o marco inicial da degradação.

Resource

youshop://playbooks/retention-guide

Guia de exemplo de boas práticas de retenção proativa do Comercial.

Prompt

draft_retention_outreach(producer_ref, channel)

Gera rascunho consultivo para whatsapp, email ou telefone com validação de entrada e aviso obrigatório de revisão humana.


Segurança, Privacidade e Uso Consciente da IA

  • Sessão Fail-Closed, Homônimos e Anti-Enumeração: nenhuma tool aceita manager_id vindo do modelo. O servidor exige SESSION_MANAGER_ID explícito no ambiente (retornando ToolError limpo se ausente), filtra buscas já pela carteira da sessão (suportando produtores homônimos entre gerentes) e devolve o mesmo erro (PRODUCER_UNAVAILABLE, sem ecoar entrada bruta) tanto para outra carteira quanto para nomes inexistentes.

  • Minimização de Dados via Allowlist e Anti-Prompt Injection: alinhado ao princípio da necessidade da LGPD (sem reivindicar conformidade jurídica plena), apenas métricas agregadas saem do servidor. Colunas sensíveis (owner_email, tax_id, webhook_secret, buyer_email) nunca cruzam a fronteira MCP, producer_ref e channel são validados na entrada e valores categóricos (top_webhook_error, webhook_errors_by_category, tickets_by_category) são validados contra listas fechadas antes de chegar ao modelo.

  • Distinção entre Erro Crítico e Falso Alarme Técnico: apenas quando 100% das falhas pertencem a endpoints auxiliares (endpoint_analytics_offline), com vendas estáveis e zero tickets críticos, o produtor é rebaixado para falso_alarme_tecnico. Erros críticos (assinatura_invalida, timeout_checkout_pix) ou categorias desconhecidas (por cautela) mantêm visibilidade via alerta_tecnico_precoce (ou risco medio/alto conforme tickets ou queda de vendas).

  • Verificador Numérico Tipado e Validação no CI: antes de gravar docs/replay_data.json, o cliente audita números em pools separados por tipo (percentuais, scores, receita, contagens e unidades de tempo) e regras editoriais por cena — bloqueando a gravação em caso de violação. A mesma auditoria roda automaticamente no CI (tests/test_replay_integrity.py).


Limites e Premissas

Este é um protótipo funcional desenhado para validação técnica e demonstração de arquitetura. Suas limitações declaradas são:

  • Dados simulados e escopo reduzido: base sintética (seed=42) com apenas 9 produtores em 2 carteiras e data de referência fixa (19/11/2026).

  • Pesos e limiares hipotéticos: os pesos (40% webhook, 40% vendas, 20% tickets) e todos os limiares centralizados em config.py são hipóteses iniciais a calibrar com histórico real.

  • Sazonalidade simulada: em uma janela sintética de 28 dias não há série histórica anual; o padrão sazonal é modelado por uma flag fixa por produtor (seasonal_pattern) apenas para demonstrar o comportamento da regra.

  • Identidade simulada por variável de ambiente: SESSION_MANAGER_ID substitui a camada de autenticação neste protótipo; em produção seria vinculada a OAuth2/JWT corporativo e RBAC.

  • Falibilidade da IA: mesmo com cálculo determinístico, prompt restritivo e verificador tipado, LLMs podem interpretar contexto de forma imprecisa — por isso o fluxo é somente leitura e exige revisão humana antes de qualquer contato.

  • Envio externo para API da Groq: no cliente de demonstração local, os retornos minimizados das tools MCP são enviados à API da Groq (servidores nos EUA). Antes de operar com dados reais de clientes, seria necessária avaliação jurídica/DPA ou migração para inferência em ambiente controlado.

  • Feedback de "alerta útil" fora do escopo do protótipo: o mecanismo de marcação de utilidade pelo gerente de contas ainda não foi implementado (o servidor atual é estritamente somente leitura) e está previsto para a fase de piloto.


Piloto e Como Mediríamos o Sucesso

Antes de liberar o Radar para toda a operação comercial, a validação ocorreria em um piloto controlado de 4 a 6 semanas com uma carteira real selecionada, medindo:

Métrica

Como seria medida

Objetivo no piloto

Taxa de "alerta útil" (métrica central)

Botão de feedback rápido (útil / ruído) registrado pelo gerente de contas após cada alerta sinalizado.

Validar se os alertas geram ação real (hipótese inicial de referência para calibração no piloto, a definir com o time comercial) e recalibrar pesos/limiares de config.py.

Taxa de falso alarme comercial

Proporção de alertas de risco médio/alto que não correspondiam a degradação técnica ou queda real.

Reduzir fadiga de alertas no Comercial.

Tempo médio até detecção técnica

Intervalo entre o início de falhas críticas de webhook/checkout e o primeiro contato ou abertura de suporte.

Antecipar a ação antes que o problema vire churn ou prejuízo em lançamento de creators.

Retenção / recuperação pós-abordagem

Estabilização de webhooks e retorno da receita ao baseline em 14 dias após contato consultivo.

Medir impacto prático na receita retida.


Como Rodar Localmente

Pré-requisitos: Python 3.11+ e uv.

# 1. Instalar dependências no ambiente virtual isolado
uv sync

# 2. Gerar o banco SQLite simulado determinístico (seed=42)
uv run python -m youshop_radar.data.seed

# 3. Conferir a tabela determinística de scores dos 9 produtores
uv run python -m youshop_radar.domain.scoring

# 4. Rodar lint e suíte de 27 testes automatizados (inclui E2E stdio e auditoria do replay)
uv run ruff check src tests demo_client
uv run pytest -v

Rodar o agente MCP ao vivo (Groq API)

  1. Copie .env.example para .env, defina SESSION_MANAGER_ID=mgr_ana e informe sua GROQ_API_KEY gratuita (console.groq.com).

  2. Execute o roteiro completo (ou abra o modo interativo):

# Regravar a sessão completa de 5 cenas com auditoria tipada (atualiza docs/replay_data.json)
uv run python demo_client/groq_client.py --record

# Conversar livremente no terminal com o servidor MCP via stdio
uv run python demo_client/groq_client.py --interactive

# Visualizar a interface web de replay localmente ([http://127.0.0.1:8000](http://127.0.0.1:8000))
uv run python -m http.server 8000 --bind 127.0.0.1 --directory docs

Cenários Demonstrados (Sessão mgr_ana)

  1. Priorização da carteira: destaca Aurora Cosméticos (93, alto), NutriMax Suplementos (83, alto) e VitaPulse Saúde (56, alerta_tecnico_precoce), separando-os de casos estáveis e falsos alarmes.

  2. Diagnóstico + evolução semanal: cruza o salto de falhas assinatura_invalida (32,1%) com a queda de -40,1% nas vendas na semana de 13–19 nov, usando linguagem de hipótese ("pode indicar").

  3. Rascunho de abordagem (HITL): dispara o MCP Prompt + Resource e redige mensagem consultiva de WhatsApp sem expor score, jargão interno ou classificação de risco ao cliente.

  4. Segurança (carteira alheia): bloqueia consulta à BellaSuplementos (mgr_carlos) via PRODUCER_UNAVAILABLE (mesmo erro de produtor inexistente) sem sugerir contornos.

  5. Falso alarme técnico: explica por que CodeMaster Cursos (28,6% de erro em endpoint_analytics_offline, vendas +7,5% e 0 tickets) não exige ligação urgente de churn.


Licença

Distribuído sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to query customer churn risk, MRR at risk, and customer health profiles from Retain, and take actions like adding notes and marking alerts contacted.
      8
      37 npm
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides real-time account intelligence, deal signals, and strategic openers to AI agents and MCP-compatible orchestrators, enabling automated sales workflows such as pre-call battlecards, deal reactivation, and territory monitoring.
      12
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables AI sales agents to interact with a CRM via event-sourced actions, identity resolution, guard checks, and an approval inbox, managing communications and tasks while adhering to compliance rules.
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to read local business data and request database mutations, while requiring human approval before updates or deletions are executed. It provides read-only tools, approval workflows, and audit logging to prevent autonomous destructive changes.
      -