rebelytics/peec-ai-mcp

Habilidade Companheira do Peec AI MCP

Guia de código aberto para agentes de IA que trabalham com o servidor Peec AI MCP. Agnóstico de agente, agnóstico de projeto, CC BY 4.0. Compartilhe e adapte livremente; mantenha a linha de atribuição.

Documento vivo. Se você descobrir um comportamento que contradiz este arquivo — ou uma nova funcionalidade do Peec que não está coberta — abra uma issue ou PR em github.com/rebelytics/peec-ai-mcp. Veja CONTRIBUTING.md para o fluxo de trabalho.

As observações de comportamento aqui são atuais em abril de 2026. O Peec itera; as coisas mudam.

---

1. O que é o Peec AI MCP (para o agente)

O Peec AI (peec.ai) monitora como as marcas aparecem nos motores de busca de IA (ChatGPT, AI Overviews, Perplexity, Gemini, Grok, Copilot, Claude, etc.) executando prompts rastreados diariamente e analisando as respostas. O servidor MCP expõe esses dados — e a capacidade de alterar a configuração subjacente — para qualquer agente compatível com MCP.

URL do servidor: https://api.peec.ai/mcp Transporte: HTTP Streamable Autenticação: OAuth 2.0 (consentimento do navegador, token persiste)

A superfície é maior do que a documentação oficial sugere: 27 ferramentas (15 somente leitura, 8 de escrita, 4 destrutivas), além de 7 "prompts" de comando de barra que agrupam análises pré-definidas. A página de documentação oficial /mcp/tools lista apenas 13 ferramentas de leitura e omite completamente a superfície de escrita/destrutiva (veja §7.11 e §7.25).

Glossário de termos centrais

Termos usados ao longo desta habilidade. Cada um carrega um significado específico e não óbvio no modelo de dados do Peec.

• Visibilidade — com que frequência uma marca aparece nas respostas de IA. menções ÷ total de chats rastreados, retornado como uma proporção de 0–1 (a IU mostra 0–100). Veja §7.3 / §7.37.
• Participação de Voz (SoV) — a participação de uma marca em todas as menções em todo o rol de marcas rastreadas. Proporção de 0–1 (a IU mostra 0–100). "Rastreadas" é significativo — veja posição.
• Sentimento — pontuação de 0–100, neutro em 50. Fórmula: 50 + (soma_sentimento / contagem_sentimento) × 50. Veja §7.3.
• Posição — classificação média entre marcas rastreadas, não geral. Menor = melhor. Veja §7.4.
• Marca própria — a linha is_own=true em list_brands. Cada outra linha é um concorrente rastreado.
• Menção — o nome da marca aparece no texto da resposta de IA, com ou sem uma busca na web.
• Recuperação — o mecanismo de IA buscou uma ou mais URLs ao responder. Contado em get_domain_report e get_url_report.
• Citação — uma URL recuperada que o modelo referencia explicitamente em sua resposta. Todas as citações são recuperações; nem todas as recuperações se tornam citações.
• Memória paramétrica — o modelo respondeu a partir de dados de treinamento sem buscar fontes da web. sources: [] em um payload de chat é o indicador.
• Fanout — quando um mecanismo de IA reescreve o prompt do usuário em subconsultas antes de pesquisar. Exposto via list_search_queries(chat_id=...).
• Variante scraper — um ID de modelo com sufixo -scraper (ex.: chatgpt-scraper). Reproduz prompts através do aplicativo real do consumidor; captura o que os usuários veem, não a saída bruta da API. Prefira para monitoramento de visibilidade. Veja §7.2.
• UGC — conteúdo gerado pelo usuário. Um dos 8 valores de domain_report.classification, cobrindo Reddit, YouTube, fóruns, etc. Veja §7.30.
• Idempotente — seguro de executar duas vezes. As exclusões suaves do Peec não são idempotentes — a segunda chamada retorna "não encontrado". Veja §7.34.
• Exclusão suave — remove a entidade de list_* e filtros, mas a preserva no servidor. A única forma que o Peec expõe. Veja §7.34.
• Prefixos de ID — or_ (projeto), kw_ (marca — nome legado das origens de rastreamento de palavras-chave do Peec), pr_ (prompt), tp_ (tópico), tg_ (tag), ch_ (chat). Marcadores de namespace opacos, não tipos semânticos (kw_ é uma marca, não uma palavra-chave).

1.1 Modelo de dados — marcas, prompts, tópicos, tags são ortogonais

A parte mais mal interpretada da superfície do Peec. Prompts não "pertencem a" marcas — nenhuma chave estrangeira brand_id existe, e update_prompt não pode mover um prompt entre marcas.

Entidades:

• Projeto (or_…) — contêiner raiz; todo o resto depende de um projeto.
• Marca (kw_…) — um padrão de detecção aplicado ao texto da resposta de IA. Campos: name, aliases, regex, domains, is_own. Nenhum vínculo com prompts, tópicos ou tags.
• Tópico (tp_…) — agrupamento semelhante a pasta para prompts. Um prompt tem zero ou um tópico.
• Tag (tg_…) — rótulo anexado a prompts. Um prompt carrega zero ou mais tags.
• Prompt (pr_…) — uma pergunta rastreada diariamente. Campos: text, country_code, topic_id, tag_ids. Nenhum campo brand_id.
• Chat (ch_…) — uma resposta de mecanismo de IA para um prompt em um dia. O texto do chat é verificado contra o padrão de detecção de cada marca, produzindo contagens de menções e relatórios de marca.

A relação marca ↔ prompt é somente leitura e indireta. Prompts geram chats; chats contêm texto de resposta; a detecção de marca é executada nesse texto na ingestão. Nenhum caminho de escrita vincula um prompt a uma marca. "Atribuir" ou "mover" prompts entre marcas é um erro de categoria — marcas não são contêineres, são padrões de detecção.

Implicações práticas:

• update_prompt altera apenas topic_id e tag_ids — não text, nem qualquer suposto brand_id. Veja §7.13.
• update_brand altera padrões de detecção (name, aliases, regex, domains). Nenhum faz referência a prompts.
• Para "quais prompts mencionaram a Marca X", execute list_chats(brand_id=…) e inspecione a coluna prompt_id.
• create_brand padrão is_own=false — sempre cria um concorrente. A eleição de marca própria não é exposta via MCP.
• A lista de TLDs da marca própria é importante para classificação. Se domains=["exemplo.de"] mas a empresa também opera exemplo.com.br, o relatório de domínio classifica exemplo.com.br como CORPORATIVO, não PRÓPRIO. Veja §7.10.

---

Primeiros Passos — Primeiro Relatório em 3 Minutos

Pressupõe uma conta Peec AI (peec.ai) com pelo menos um projeto e um cliente compatível com MCP (Claude Desktop usado no exemplo abaixo). O Peec publica instruções oficiais de configuração por cliente em docs.peec.ai/mcp/introduction; siga-as e volte aqui depois que o conector estiver ativo.

1. Conecte. Configurações → Conectores → Adicionar conector personalizado → URL https://api.peec.ai/mcp → Salvar → clique em "Conectar" no cartão do conector → autorize no navegador. O clique em "Conectar" após salvar é fácil de perder.
2. Verifique. Pergunte ao agente: "Liste meus projetos do Peec AI." Espere pelo menos um ID de projeto or_… em uma tabela JSON colunar (§4).
3. Extraia um primeiro relatório de marca. Pergunte: "Para o projeto <id>, mostre a visibilidade, menções, SoV, sentimento e posição da minha própria marca nos últimos 30 dias, divididos por modelo de IA." O agente encadeará list_brands (encontrar is_own=true) → get_brand_report (filtrar nesse brand_id, dimensão model_id, janela padrão de 30 dias).
4. Três regras de interpretação antes de relatar qualquer número:
   • As escalas são misturadas na mesma linha. visibility e share_of_voice vêm como proporções de 0–1 (multiplique por 100 para porcentagem). sentiment já é 0–100 (neutro = 50). position começa em 1 e menor é melhor. Não trate todos os quatro como uma escala. Detalhes em §7.37.
   • Posição é classificação entre marcas rastreadas, não geral. Uma posição de 1,6 significa "1,6º no rol de concorrentes que você configurou", não "2º geral na resposta completa do ChatGPT". §7.4.
   • Menções incluem respostas paramétricas. A visibilidade conta cada resposta onde o nome da marca aparece no texto, incluindo respostas onde o mecanismo não buscou uma única URL. Recuperações e citações contam apenas buscas reais na web. §7.5.
5. Dados vazios ≠ ferramenta quebrada. Mecanismos que retornam zeros geralmente estão inativos no seu plano (§7.1). Cinco causas distintas de resultados vazios estão catalogadas em §7.8 — verifique essa lista antes de concluir "a ferramenta está quebrada".

Esse é o loop mínimo útil. Para o mapa de recursos completo, continue lendo — §8 coleta as sete receitas que cobrem os casos de uso primários publicados do Peec.

---

Lista de verificação de pré-voo — antes de relatar qualquer número

Execute esta verificação de oito itens antes de colocar números do Peec na frente de um humano.

1. Tipo de métrica identificado para cada coluna. Classifique cada coluna numérica como Proporção (0–1, multiplique por 100), Pontuação (0–100, neutro em 50 para sentimento), Classificação (1+, menor é melhor), Taxa (pode exceder 1,0) ou Contagem (inteiro). Veja §7.37. Se você não puder nomear o tipo, não exiba o número.
2. Escala normalizada para o que o humano espera. Proporções renderizadas como porcentagens (0,33 → 33%, não 0,33%). Sentimento deixado como 0–100 com 50 = neutro explícito. Posição deixada como uma classificação com "menor é melhor" destacado. Taxa mantida como está, com anomalias (retrieval_rate=1,8) explicadas em vez de reescritas. Veja §7.3 / §7.37.
3. Posição lida como classificação-entre-marcas-rastreadas, não geral. Qualquer figura de posição vem com o qualificador "entre concorrentes rastreados". Veja §7.4.
4. Dimensões e filtros validados contra o esquema da ferramenta, não adivinhados. Dimensões válidas de get_brand_report: prompt_id, model_id, model_channel_id, tag_id, topic_id, date, country_code, chat_id. brand_id é apenas filtro, nunca uma dimensão. Veja §7.15 / §8.1.
5. Nomes de colunas confirmados contra o payload de resposta real. Não presuma que uma coluna existe porque uma receita diz para ordenar por ela. get_domain_report padrão sem dimensão retorna retrieved_percentage, retrieval_rate, citation_rate — não retrieval_count. Veja §7.39 / §8.10.
6. Mecanismos inativos sinalizados, não relatados como visibilidade zero. Verifique list_models(is_active=true) antes de afirmar que uma marca está invisível no Perplexity/Claude/Gemini. Veja §7.1 / §7.8.
7. Resultados vazios diagnosticados contra a lista de cinco causas em §7.8 antes de concluir que algo está quebrado. Marcas com exclusão suave, mecanismos inativos, respostas paramétricas, limites do plano e incompatibilidade de filtro parecem todos iguais na superfície.
8. IDs kw_… não resolvidos sinalizados como com exclusão suave, não como bugs. Veja §7.38.

Se algum item falhar, pare e corrija antes de relatar. Passagens parciais produzem confiança parcial.

---

2. Configuração

Parâmetros de conexão (os mesmos para todos os clientes):

• URL: https://api.peec.ai/mcp
• Transporte: HTTP Streamable
• Autenticação: OAuth 2.0 (consentimento do navegador, token persiste)
• Escopo: leitura + gravação (apesar da documentação oficial afirmar somente leitura — veja §7.11)

Para instruções de instalação por cliente, siga a documentação oficial de configuração do Peec em docs.peec.ai/mcp/introduction. O Peec mantém a lista atualizada de clientes suportados e seus fluxos de conexão passo a passo; esta habilidade deliberadamente não duplica esse conteúdo porque depende do ambiente e fica desatualizado rapidamente.

Isolamento de rede: Se você estiver executando dentro de um ambiente de agente em sandbox (Cowork, certos IDEs em nuvem, proxies corporativos), certifique-se de que api.peec.ai está na lista de permissões de saída. Uma solicitação bloqueada aparece como um erro genérico de conexão / 403 sem nenhum sinalizador dentro da habilidade de que é um problema de camada de rede e não um bug do Peec.

Verifique sua configuração com: "Liste meus projetos do Peec AI, depois mostre as marcas e tópicos rastreados no primeiro." Esperado: duas chamadas de ferramenta sequenciais (list_projects → list_brands + list_topics), ambas retornando JSON colunar com pelo menos uma linha cada. Se o agente disser que não tem integração com o Peec, o conector não está conectado — revise a documentação oficial do Peec e confirme se o consentimento OAuth foi concluído.

Antes de conectar, certifique-se de que o usuário tenha uma conta Peec AI (peec.ai) com pelo menos um projeto e esteja logado no mesmo navegador que usará para OAuth. O OAuth "conclui silenciosamente" se a sessão do navegador já estiver autenticada — portanto, a ausência de uma tela de consentimento não significa que o conector está quebrado.

---

3. As 27 ferramentas de relance

Somente leitura (15)

Ferramenta	Propósito
list_projects	Todos os projetos acessíveis ao usuário autenticado
list_brands	Marcas rastreadas em um projeto (própria + concorrentes)
list_topics	Tópicos (agrupamentos semelhantes a pastas de prompts)
list_prompts	Prompts, filtráveis por topic_id ou tag_id
list_tags	Rótulos transversais aplicados a prompts
list_models	Catálogo de mecanismos de IA (veja §7: o filtro is_active é crítico)
list_chats	Respostas individuais de IA, filtráveis por marca/prompt/modelo
get_chat	Payload completo do chat (mensagens, fontes, produtos, marcas_ mencionadas)
list_search_queries	Subconsultas que o mecanismo de IA espalhou
list_shopping_queries	Consultas de modo de compra + listagens de produtos
get_brand_report	Agregados de visibilidade, SoV, sentimento, posição
get_domain_report	Taxas de recuperação + citação de domínio de origem
get_url_report	Taxas de recuperação + citação de URL de origem + classificação de página
get_url_content	Markdown raspado de qualquer URL de origem indexada
get_actions	Recomendações pontuadas por oportunidade (quebrado em abril de 2026 — veja §7.12)

Gravação / alteração (8)

Ferramenta	Propósito
create_brand	Rastrear um novo concorrente (aceita domains, aliases, regex)
update_brand	Renomear / ajustar uma marca (aciona recálculo em segundo plano — veja §7.19)
create_topic	Adicionar um tópico (country_code opcional; name.maxLength=64)
update_topic	Renomear um tópico
create_prompt	Adicionar um prompt rastreado (requer country_code; text.maxLength=200)
update_prompt	Alterar topic_id / tag_ids (não text — veja §7.13)
create_tag	Adicionar uma tag com uma das 22 cores (veja abaixo)
update_tag	Renomear ou recolorir uma tag

Enumeração de cores de tag (22 valores): gray, red, orange, yellow, lime, green, cyan, blue, purple, fuchsia, pink, emerald, amber, violet, indigo, teal, sky, rose, slate, zinc, neutral, stone. O esquema JSON da ferramenta é a fonte oficial se o Peec adicionar cores depois; esta lista corresponde ao esquema em abril de 2026.

Destrutivas (4)

Ferramenta	Propósito
delete_brand	Exclusão suave de marca
delete_topic	Exclusão suave de tópico (desanexa prompts, não em cascata)
delete_prompt	Exclusão suave de prompt (em cascata para chats)
…	…