Mapcast MCP

Dados e limites

Fonte

Censo IBGE 2022 (Projeção Mapfry)

Versão

2025

Cobertura

200 municípios brasileiros (recorte ABF Top 200)

Os números retornados são estimativas para apoio à decisão, baseadas em médias censitárias e parâmetros informados pelo usuário. Não substituem pesquisa de campo nem análise de viabilidade específica do ponto.

================================================================================
PROMPT MESTRE: MAPCAST — RANKING BUILDER & PLANO DE EXPANSÃO (MVP)
================================================================================

Objetivo: Construir um web app completo de geomarketing que gera rankings de 
municípios brasileiros com potencial para abertura de unidades de varejo/franquias.

Stack Tecnológica:

- Framework: TanStack Start + React 19 + TypeScript
- Estilização: Tailwind CSS + shadcn/ui (Fonte: Inter, Visual: Sóbrio e corporativo)
- Estado Global: Zustand (com persistência no localStorage)
- Gráficos & Mapas: Recharts + MapLibre GL / react-map-gl (Estilo: OpenFreeMap Positron)
- Arquitetura de Dados: Base municipal embarcada em JSON no bundle (sem chamadas de API externa)

================================================================================

Você é um Engenheiro de Software Fullstack Senior e especialista em produtos de Geomarketing.

Sua tarefa é criar o aplicativo web "Mapcast — Ranking Builder" seguindo rigorosamente a especificação abaixo.

--------------------------------------------------------------------------------
BLOCO 1: DESIGN SYSTEM, UX & MOCK DE DADOS
--------------------------------------------------------------------------------

1. VISUAL E UX:

   - Apreciação estética: Design soberbo, limpo e focado em dados (estilo executivo/analytics).
   - Proibido usar gradientes roxos/neon genéricos. Use tokens semânticos neutros (slate/zinc/gray).
   - Responsividade: Menu hambúrguer para mobile e componentes adaptáveis.
   - UX Flow: Setup imediato em menos de 60 segundos, sem onboarding ou cadastro obrigatório.

2. ESTRUTURA DE DADOS EMBARCADA (JSON Mock dos Top Municípios IBGE / ABF):

   type Municipality = {
     ibgeCode: string;
     name: string;
     uf: string;
     region: string; // Região imediata / RGI
     lat: number;
     lng: number;
     // Domicílios
     totalHouseholds: number;
     households1Person: number;
     households2People: number;
     households3People: number;
     households4People: number;
     households5PlusPeople: number;
     // Tipologia Habitacional
     householdsHouses: number;
     householdsApartments: number;
     householdsVillageCondo: number;
     // População & Faixas Etárias
     totalPopulation: number;
     pop0to9: number;
     pop10to19: number;
     pop20to29: number;
     pop30to39: number;
     pop40to49: number;
     pop50to64: number;
     pop65Plus: number;
     // Classes Sociais (Quantidade de Domicílios)
     classE: number;
     classD: number;
     classC: number;
     classB: number;
     classA: number;
     classAA: number;
     // Indicadores Financeiros
     totalIncome: number;
     avgHouseholdIncome: number;
   };

--------------------------------------------------------------------------------
BLOCO 2: MÓDULO POTENCIAL COMERCIAL (/potential ou Aba 1)
--------------------------------------------------------------------------------

Purpose: Transformar uma meta de faturamento em população mínima necessária (minPop)
para sustentar 1 unidade do negócio.

// ENTRADAS (INPUTS):
// - Faturamento Mensal Esperado (R$)
// - Ticket Médio por Visita (R$)
// - Frequência Mensal por Cliente
// - Nível de Penetração: [0: Conservador 1%, 1: Cauteloso 2.5%, 2: Moderado 5% (Default), 3: Otimista 7.5%, 4: Agressivo 10%, 5: Muito Agressivo 15%]
// - Atributo-Base de Mercado (Escolha OBRIGATÓRIA do usuário sem default, ex: "pop20to29", "classB", "totalPopulation")

// FÓRMULAS E REGRAS:
// 1. visitas_necessarias = ceil(faturamento_esperado / ticket_medio)
// 2. clientes_necessarios = ceil(visitas_necessarias / frequencia_mensal)
// 3. publico_minimo (minPop) = ceil(clientes_necessarios / penetracao)
// Validação: Se ticket, frequência ou penetração <= 0, retorne todos os cálculos como 0.

// OUTPUTS & UX:
// - Exibir Memória de Cálculo detalhada passo a passo na tela.
// - Disparar Insights Automáticos com base nos limites:
//   * Penetração <= 2.5%: "Cenário conservador: exige mais população por unidade..."
//   * Penetração >= 10%: "Cenário agressivo: exige marca forte e alta tração..."
//   * Frequência >= 3: "Alta frequência: modelos com recorrência ou fidelização..."
//   * Ticket >= 100: "Ticket alto: modelo depende de renda e qualidade percebida..."
//   * Ticket <= 50: "Ticket baixo: conveniência e volume ganham peso..."

--------------------------------------------------------------------------------
BLOCO 3: MOTOR DE RANKING BUILDER (/ /setup /ranking)
--------------------------------------------------------------------------------

Purpose: Normalizar atributos, calcular o score e projetar o nº de unidades por município.

// REGRAS DE CÁLCULO DO MOTOR:
// 1. Seleção e Pesos: Atributos com peso bruto (0 a 100). Normalizar para somar 100:
//    peso_normalizado_i = (peso_bruto_i / sum(pesos_brutos)) * 100
// 2. Normalização Min-Max por Atributo no recorte filtrado:
//    norm_i = (valor - min) / (max - min) | Se max == min -> norm_i = 0
// 3. Score do Município (0 a 100):
//    municipality_score = sum(norm_i * peso_normalizado_i)
// 4. Aderência (Fit):
//    fit = min(1.0, municipality_score / 100) | Se sem atributos -> fit = 1.0
// 5. Unidades Estimadas (estimated_units):
//    - Com Potencial configurado: floor((atributo_base / minPop) * fit) [Sem teto]
//    - Modo Legado (sem potencial): floor(municipality_score / threshold)
// 6. Corte de Exibição: Manter no ranking apenas quem tem estimated_units >= 1.

// ORDENAÇÃO DO RANKING (CRITÉRIOS DE DESEMPATE):
// 1º estimated_units (DESC)
// 2º municipality_score (DESC)
// 3º Volume bruto do Atributo-Base / População Relevante (DESC)
// 4º Renda Total (DESC)

// COMPONENTE DE CENÁRIOS SAVED:
// Permitir salvar, carregar e alternar entre diferentes cenários (ex: "Farmácia Premium", "Academia Popular").

--------------------------------------------------------------------------------
BLOCO 4: VISUALIZAÇÃO EM MAPA (/map ou Aba Mapa)
--------------------------------------------------------------------------------

Purpose: Exibir a distribuição espacial dos municípios qualificados (1+ unidades).

// COMPORTAMENTO E BIBLIOTECAS:
// - Usar MapLibre GL com estilo OpenFreeMap Positron (sem necessidade de API Key).
// - Exibir Clusters em zoom baixo e Pontos Individuais em zoom alto.
// - Tamanho do marcador proporcional a `estimated_units`:
//   1 un = pequeno | 2-3 un = médio | 4-5 un = grande | 6+ un = destacado
// - Popups interativos ao clicar em um município (mostrando posição, unidades, score e top drivers).
// - Popup de Cluster agregando a soma de unidades e o Top 5 municípios do cluster.

--------------------------------------------------------------------------------
BLOCO 5: DETALHES DO MUNICÍPIO (/municipality/$ibge)
--------------------------------------------------------------------------------

Purpose: Exibir a ficha técnica profunda do município selecionado.

// CONTEÚDO DA TELA:
// - Comparação tripla de indicadores: Município vs. Média da UF vs. Média da RGI.
// - Renda média domiciliar e Renda Total.
// - Gráficos com Recharts: Pirâmide etária e distribuição de Classes Sociais (ordem invertida: AA no topo, E na base).
// - Lista dos atributos do cenário ativo que mais contribuíram para o Score (Top Drivers).

--------------------------------------------------------------------------------
BLOCO 6: ESTIMATIVA DE DESEMPENHO DO PONTO (/performance)
--------------------------------------------------------------------------------

Purpose: Fazer o caminho inverso — estimar faturamento a partir de um público de área de influência.

// ENTRADAS (INPUTS):
// - Público disponível na área de influência (ex: raio de 0.5km, 1.0km, 1.5km)
// - Fator da Rua/Acessibilidade: [Na mão (1.0), Fora de mão (0.7), Contramão (0.4)]
// - Parâmetros herdados do Módulo Potencial (Ticket, Frequência, Penetração) — permite ajuste local.

// CÁLCULOS DO PONTO:
// 1. publico_ajustado = publico_disponivel * fator_ponto
// 2. clientes_potenciais = floor(publico_ajustado * penetracao)
// 3. visitas_mensais = clientes_potenciais * frequencia
// 4. faturamento_estimado = visitas_mensais * ticket_medio

// COMPARAÇÃO COM O POTENCIAL:
// Compare `publico_ajustado` com o `minPop` do módulo de Potencial Comercial:
// - Se publico_ajustado >= 1.5 * minPop -> Status: FOLGA (🟢)
// - Se publico_ajustado >= minPop     -> Status: SUFICIENTE (🟡)
// - Se publico_ajustado < minPop      -> Status: ABAIXO DO MÍNIMO (🔴)

--------------------------------------------------------------------------------
BLOCO 7: PROTOCOLO MCP & INTERFACE (/mcp e /conectar)
--------------------------------------------------------------------------------

Purpose: Expor as regras e dados do sistema via Model Context Protocol para LLMs.

// 1. Rota `/mcp`: Servidor MCP público e sem autenticação com as 4 ferramentas:
//    - list_municipalities
//    - get_municipality
//    - compute_commercial_potential
//    - compute_performance_estimate
//    (Ler dados do JSON embarcado, incluir tratamento de erro com log interno).

// 2. Rota `/conectar`: Página humana documentando a URL do MCP, exemplos de prompts para ChatGPT/Claude/Cursor, botão "Copiar Endpoint" e disclaimers sobre dados do IBGE.

--------------------------------------------------------------------------------
DIRETRIZ DE FINALIZAÇÃO DA IA:
--------------------------------------------------------------------------------

Gere os componentes modulares em arquivos limpos, tipados com TypeScript, com tratamento para estados de Empty State, Loading e No Results ("Nenhum município atingiu o mínimo de 1 unidade").

================================================================================