YouShop Radar MCP
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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.
Demo Interativa (Replay Real com Raio-X JSON e Auditoria Numérica): https://marcus-luz.github.io/youshop-radar-mcp/
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:
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.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.
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 MITPrimitivas MCP Expostas
Tipo | Nome / URI | Descrição |
Tool |
| Lista produtores da carteira autenticada ordenados por score de risco. |
Tool |
| Detalha sinais dos últimos 7 dias vs. baseline de 21 dias (webhooks, vendas, tickets abertos de qualquer idade, creators). |
Tool |
| Evolução semanal (1 a 4 semanas) para identificar o marco inicial da degradação. |
Resource |
| Guia de exemplo de boas práticas de retenção proativa do Comercial. |
Prompt |
| Gera rascunho consultivo para |
Segurança, Privacidade e Uso Consciente da IA
Sessão Fail-Closed, Homônimos e Anti-Enumeração: nenhuma tool aceita
manager_idvindo do modelo. O servidor exigeSESSION_MANAGER_IDexplícito no ambiente (retornandoToolErrorlimpo 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_refechannelsã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 parafalso_alarme_tecnico. Erros críticos (assinatura_invalida,timeout_checkout_pix) ou categorias desconhecidas (por cautela) mantêm visibilidade viaalerta_tecnico_precoce(ou riscomedio/altoconforme 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 emconfig.pysã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_IDsubstitui 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 ( | 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 |
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 -vRodar o agente MCP ao vivo (Groq API)
Copie
.env.examplepara.env, definaSESSION_MANAGER_ID=mgr_anae informe suaGROQ_API_KEYgratuita (console.groq.com).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 docsCenários Demonstrados (Sessão mgr_ana)
Priorização da carteira: destaca
Aurora Cosméticos(93,alto),NutriMax Suplementos(83,alto) eVitaPulse Saúde(56,alerta_tecnico_precoce), separando-os de casos estáveis e falsos alarmes.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").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.
Segurança (carteira alheia): bloqueia consulta à
BellaSuplementos(mgr_carlos) viaPRODUCER_UNAVAILABLE(mesmo erro de produtor inexistente) sem sugerir contornos.Falso alarme técnico: explica por que
CodeMaster Cursos(28,6% de erro emendpoint_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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Read-only account intelligence for Customer Success and Account Management teams.
Retention and marketing tools for one workspace. Writes are filed for a person's approval.
Agent-native CRM. 25 tools — contacts, deals, sequences, enrichment waterfall, audit log.
See who replied and where your pipeline is stuck, from your own AI. Insurance agents. $55/30 days.
Related MCP Servers
AlicenseAqualityCmaintenanceEnables 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.837 npm1MIT- AlicenseAqualityDmaintenanceProvides 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.12MIT
- FlicenseNot gradedqualityBmaintenanceEnables 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.-
- FlicenseNot gradedqualityCmaintenanceEnables 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.-