Servidor MCP do banco comercial

banco_descrever_consulta

Mostra os detalhes de UMA consulta oficial do banco comercial. Retorna a pergunta que responde, os parâmetros esperados (com tipo e descrição), os filtros obrigatórios (sem os quais o número fica errado), o que a consulta retorna, os gotchas conhecidos e o SQL. Use antes de executar, para saber quais parâmetros passar. id_consulta vem de banco_listar_consultas.

banco_executar_consulta

Executa uma consulta oficial no banco comercial e devolve o número real. Esta é a fonte da verdade: o valor vem de um SELECT determinístico no banco, não de estimativa. Somente leitura (usuário read-only). Parâmetros: - id_consulta: id de banco_listar_consultas. - parametros_json: objeto JSON com os parâmetros da consulta, ex.: {"dt_ini": "2026-07-01", "dt_fim": "2026-07-31"}. Veja quais são obrigatórios em banco_descrever_consulta. JSON malformado é recusado. - limite: máximo de linhas por página (padrão 200, teto 1000). - offset: pula as primeiras N linhas — para paginar resultados grandes (ex.: limite=1000, offset=1000 traz a 2ª página). Padrão 0. Retorna {ok, colunas, linhas, num_linhas, offset, truncado, ...}. Se truncado for true, há MAIS linhas — pagine com offset ou, para extração inteira, use banco_exportar_consulta. Se algum parâmetro obrigatório faltar ou o banco não estiver acessível, retorna {ok: false, erro: ...} — trate o erro e ajuste, não invente o número.

banco_exportar_consulta

Exporta uma consulta INTEIRA como CSV, sem o teto de linhas da execução de tela. Para extrações grandes — ex.: a venda do atacado por cliente/cidade/vendedor de um período inteiro. Devolve o arquivo todo numa resposta só; resultados grandes são gravados automaticamente em arquivo pelo cliente MCP, e aí você processa tudo com código, sem corte. Diferente de banco_executar_consulta (teto de 1.000, para telas), esta não tem teto (só um limite de segurança alto). - id_consulta: id de uma consulta marcada como EXPORTÁVEL no catálogo (as demais são recusadas). Descubra em banco_listar_consultas. - parametros_json: objeto JSON com os parâmetros, ex.: {"dt_ini": "2026-01-01", "dt_fim": "2026-09-30"}. Retorna {ok, id, num_linhas, sha256, total, truncado, csv}. O csv traz cabeçalho + linhas (separador ';', decimal com ponto, UTF-8) e uma última linha comentada (#) repetindo num_linhas, sha256 e o total da coluna de valor — confira o total contra o número oficial. Erro previsível vira {ok: false, erro}.

banco_listar_consultas

Lista as consultas OFICIAIS disponíveis sobre o banco comercial (ERP). O banco comercial guarda os dados reais da empresa (faturamento, metas, clientes, financeiro/DRE, produtos, estoque…). Você NÃO escreve SQL: escolhe uma consulta pronta e validada e passa parâmetros. Use esta ferramenta para descobrir qual consulta responde à pergunta do usuário. - texto: filtro livre (casa em id, pergunta e domínio; ex.: "faturamento", "inadimplência", "meta"). - dominio: filtra por área (ex.: "Financeiro", "Metas", "Clientes"). Cada item traz id, domínio, pergunta que responde, parâmetros e se já foi validada ao vivo. Depois, use banco_descrever_consulta para ver os detalhes e banco_executar_consulta para obter o número oficial. O filtro é por palavra: tente 2 ou 3 termos diferentes. Se NENHUMA consulta responder à pergunta, use banco_perguntar_exploratorio: o servidor monta a consulta sozinho a partir da pergunta em português (resultado exploratório).

banco_perguntar_exploratorio

Liberada para os conectores OAuth do claude.ai autorizados pela T.I. e o token interno da T.I.. Os demais tokens recebem recusa.

Responde uma pergunta sobre o banco comercial quando NENHUMA consulta oficial serve: o servidor monta a consulta sozinho a partir da pergunta em português, valida e roda. Ninguém escreve SQL. Use SÓ DEPOIS de procurar em banco_listar_consultas (2 ou 3 termos) sem achar consulta que responda. Consulta oficial, quando existe, é sempre melhor: o número é certificado. - pergunta: completa e autocontida — período (datas), canal, filtros e TUDO o que a resposta precisa (totais, percentuais, médias, agrupamentos), para o cálculo sair pronto do banco. Ex.: "faturamento do atacado em agosto de 2026 por tipo de pedido, com o total e o % de cada tipo". Retorna {ok, exploratorio: true, aviso, colunas, linhas, num_linhas, truncado, datas_no_filtro}. O número é EXPLORATÓRIO (montado na hora, não certificado; a T.I. revisa a consulta): diga isso ao usuário. A consulta em si não é devolvida. Até 50 linhas — para lista grande, peça o agregado. Leva de 10 segundos a 2 minutos. Se vier {ok: false, erro}, NÃO invente o número: reformule a pergunta ou diga que não foi possível. Disponível só para os acessos liberados pela T.I. (conectores OAuth e token interno); tokens de parceiro recebem recusa.

x1_meta_territorio

Insumo de meta da METODOLOGIA X1: linhas cruas da tabela meta_regional, por cidade/UF. NÃO é a meta de venda oficial e NÃO serve para somar: não tem a meta por BAIRRO (~21% da meta do atacado e ~23% do varejo estão nos bairros das cidades grandes), mistura os dois canais e corta em limite linhas (teto 500). Para a meta de venda inteira por cidade e bairro use banco_exportar_consulta com a consulta meta_venda_por_cidade_bairro; para o total do canal, meta_oficial_por_canal_periodo. Filtros opcionais: ano, mes, estado (UF, ex.: "SP"), cidade (busca parcial), tipo_meta (ex.: "mensal"/"anual"), limite (padrão 100, teto 500). Cada linha traz tipo_meta, canal, ano/mês, macro_regiao, estado, cidade, valor_meta (base), percentual, perc_maturidade e valor_meta_maturidade. A resposta traz um aviso com esta ressalva.

x1_nota

Nota OFICIAL do X1 de um vendedor (ou vários), com a quebra dos 7 critérios. Esta é a fonte da verdade da avaliação do vendedor: valores calculados e persistidos pelo GESTOR na tabela x1_nota (a plataforma não recalcula). Parâmetros (todos opcionais): - cod_rep: código do vendedor/representante; omita para listar vários. - ano_mes: competência "AAAA-MM" (ex.: "2026-08"); omitido, usa o período mais recente. - canal: "ATACADO" ou "VAREJO". - limite: máximo de linhas (padrão 50, teto 500). Cada linha traz cod_rep, nome, canal, cod_supervisor, ano_mes, as notas por critério (nota_c1..nota_c5, bonus_c6, penal_c7), base, nota final, farol e flags (critérios sem dado). Ordenado por nota (maior primeiro).

x1_ranking

Ranking do X1 por nota. nivel = "vendedor" (por representante) ou "gestor". Ranqueia pela nota oficial (x1_nota). Parâmetros: ano_mes ("AAAA-MM"; omitido = período mais recente), canal ("ATACADO"/"VAREJO"), nivel ("vendedor" ranqueia por cod_rep; "gestor" agrega a MÉDIA das notas da equipe por supervisor — o método atual do GESTOR; a decisão média×ponderada segue com o CEO), limite (padrão 20, teto 200). Cada linha traz a posição e a nota; no nível vendedor, também o farol.

x1_recortes

Os 8 RECORTES do X1 — o "painel" do agente PLACAR X1 (AG-PLX). Para cada canal, a MÉDIA ARITMÉTICA dos 20% de vendedores que melhor performam, em cada um dos 7 critérios (C1..C7) + a nota final — a referência de "quão longe está do topo" que o agente do vendedor consome. Regras: - Consome a nota OFICIAL (x1_nota) e NÃO recalcula (fonte única). - Um critério AUSENTE (marcado nos flags do X1, ex.: sem app de roteirização) NÃO entra como zero — é excluído e a ausência é declarada (regra REG-AUS-003). Recorte com menos de 5 medidos é recusado por cobertura insuficiente. - Também CONFERE a folha (base = C1..C5; nota = base + C6 − |C7|) e a soma dos pesos da régua (deveria fechar 100). Opcionais: canal ("ATACADO"/"VAREJO"); ano_mes ("AAAA-MM"; padrão = mais recente). Cada recorte traz estado (MEDIDO/AUSENTE), valor, quantos medidos/ausentes e o corte.

x1_regua_vigente

Régua CANÔNICA do X1 vigente hoje: pesos, réguas por canal, níveis e faróis. O X1 dá ao vendedor uma nota mensal 0..110 em 7 critérios (C1 maturidade = peso 40; C2..C5 variam por canal; C6 bônus; C7 penalização). Esta é a régua oficial da campanha vigente, lida das tabelas x1_* do banco comercial — a mesma que a tela /x1/parametros do GESTOR mostra. Passe canal ("ATACADO" ou "VAREJO") para uma só; omita para os dois. Retorna a fórmula, os pesos (C1..C7), as réguas melhor/pior por critério, os níveis do varejo (C4) e os cortes de farol (VERDE/AMARELA/VERMELHA).