Guia do Usuário - Referência da Ferramenta MCP

O servidor UserGuiding MCP disponibiliza 58 ferramentas em nove áreas. Você nunca as seleciona manualmente: basta fazer uma pergunta em linguagem simples e seu assistente escolhe as ferramentas necessárias, muitas vezes combinando várias em uma única resposta. Esta página serve como um mapa, para que você saiba o que é possível e o que solicitar.

Cada entrada lista a permissão (escopo) que a ferramenta precisa em uma conexão OAuth. Consulte a seção "Configurando o servidor MCP do UserGuiding" para saber como os escopos são concedidos.

Como as ferramentas se encaixam

• Primeiro a descoberta. Os nomes de atributos, nomes de eventos, nomes de materiais e nomes de segmentos são específicos do projeto, portanto, o assistente geralmente começa com uma ferramenta de listagem ( list_attributes , list_events , list_materials , list_segments , list_kb_categories ) antes de filtrar qualquer coisa.
• Nomes ou IDs. As ferramentas de análise aceitam um material por nome (sem distinção entre maiúsculas e minúsculas) ou por ID. Se um nome corresponder a mais de um material, a ferramenta retorna os candidatos para que o assistente possa tentar novamente com o ID correto.
• As entidades excluídas são identificadas, não ocultadas. As linhas de análise cujo guia, item de lista de verificação, ponto de acesso ou botão não existem mais são sinalizadas como excluídas, com suas contagens históricas intactas.
• As datas são inclusivas e cada intervalo de análise é limitado a um ano.

Usuários e atributos

• get_user : perfil completo de um usuário, com atributos, empresa e histórico de interações agregado. (users:read)
• list_users : percorre as páginas de usuários com um cursor. Solicita campos específicos para manter as respostas curtas. (users:read)
• search_users : filtrar usuários por atributos ou por comportamento de evento, com equações por tipo (contém, mais_que, mais_que_dias_atrás, etc.). (users:read)
• get_user_count : conta os usuários que correspondem a um conjunto de filtros sem buscar nenhum deles. A maneira mais rápida de dimensionar um público. (users:read)
• list_attributes : todos os atributos filtráveis de usuários e empresas com seus respectivos tipos de dados. (users:read)
• get_user_activities : feed de atividades brutas para um usuário, do mais recente para o mais antigo, opcionalmente filtrado para visualizações de página, interações com o Material Design ou eventos personalizados. (users:read)
• list_users_by_event : quem realizou um determinado evento. Um atalho para a pergunta comum "quem fez X". (users:read)
• upsert_user : cria um usuário ou mescla atributos em um usuário existente, opcionalmente vinculando-os a uma empresa. (users:write)
• delete_user : exclui um usuário permanentemente. (users:write)
• reset_user_history : limpa o histórico de interações do usuário no UserGuiding, mantendo seus atributos personalizados, para que ele veja o conteúdo de boas-vindas novamente. (users:write)

Análise de eventos e produtos

• list_events : nome de cada evento rastreado com seu contexto (padrão, evento personalizado do usuário, evento personalizado acionado). (users:read)
• count_events : quantas vezes um evento foi disparado em um intervalo de datas. Volume puro. (users:read)
• get_event_timeseries : ocorrências e usuários únicos agrupados por dia, semana ou mês, com intervalos vazios incluídos para que as tendências não apresentem lacunas. (users:read)
• analyze_feature_adoption : profundidade de adoção para um evento: usuários que adotaram, taxa de adoção em relação à base total de usuários, eventos por usuário que adotou, dias ativos e fidelização. Use sempre que a questão for sobre pessoas em vez de volume bruto. (users:read)
• analyze_retention : matriz de retenção de coorte. Os usuários são agrupados por quando foram vistos pela primeira vez e, em seguida, rastreados progressivamente, com uma curva de média ponderada. Opcionalmente, o escopo pode ser definido para um segmento ou para um evento específico. (users:read)
• track_event : registra um evento personalizado para um usuário, opcionalmente com metadados. (events:write)

Segmentos

• list_segments : os segmentos do projeto com seus IDs e contagens de membros, e se cada contagem é ao vivo ou um valor da janela de atividade. (users:read)
• get_segment_performance : contabiliza o engajamento de todos os materiais direcionados a um segmento, para todos os tipos de materiais, em uma única chamada. (users:read)
• get_segment_user_interactions : para um segmento baseado em atributos, quais membros interagiram com quais materiais em um intervalo de datas, discriminados por evento. Isso responde à pergunta "o que essas pessoas realmente fizeram", em oposição ao que foi direcionado a elas. (users:read)
• create_segment : cria um segmento salvo a partir de uma descrição em linguagem natural. Filtros de atributos, filtros de eventos e filtros de interação de materiais podem ser combinados, incluindo grupos AND/OR. (segments:write)
• update_segment : renomeia um segmento ou substitui seus filtros. Segmentos internos não podem ser editados. (segments:write)

Empresas

• get_company : uma empresa com seus atributos e IDs de usuários membros. (companies:read)
• list_companies : empresas com paginação, ordenação e filtros de atributos. (companies:read)
• get_company_engagement : saúde do engajamento para uma conta: membros ativos, taxa de membros ativos, total de interações, os mesmos números para o período anterior e quais materiais seus membros utilizaram. O bloco do período anterior é o sinal de declínio de uso para as equipes de Sucesso do Cliente. (companies:read)

Análise de materiais

• list_materials : todos os guias, pesquisas, listas de verificação, banners, grupos de tópicos em destaque, centros de recursos e publicações de atualizações de produtos com IDs e nomes. (users:read)
• get_material_performance : contabiliza o engajamento em um intervalo de datas, para um material específico ou para todos os materiais de um determinado tipo simultaneamente. O modo em lote permite obter respostas para as perguntas de classificação e das N principais respostas em uma única chamada. (users:read)
• get_project_overview : totais de todo o projeto por métrica, uma comparação de tendência entre as duas metades do intervalo e uma série diária. O melhor ponto de partida para "como estamos indo". (users:read)
• get_goal_performance : quantas vezes cada objetivo foi alcançado, incluindo objetivos que ninguém alcançou, de modo que "ninguém o alcançou" seja distinguível de "ele não existe". (users:read)
• get_guide_step_funnel : funil por etapa para um guia: usuários únicos que alcançaram cada etapa, além de reproduções e conclusões. É aqui que o abandono se manifesta. (users:read)
• get_user_guide_progress : progresso por usuário dentro de um guia, com a etapa mais avançada que cada usuário alcançou. (users:read)
• get_checklist_item_stats : interações por item e usuários únicos para uma lista de verificação, além de sua taxa geral de conclusão. (users:read)
• get_hotspot_stats : interações por ponto de acesso, cliques em botões, descartações e usuários únicos dentro de um grupo de pontos de acesso. (users:read)
• get_banner_click_stats : contagem de cliques por botão em um banner, com o total de cliques do banner para que as taxas por botão possam ser calculadas. (users:read)
• get_resource_center_tab_stats : visualizações e usuários únicos por guia da central de recursos, incluindo guias habilitadas com zero visualizações. (users:read)

Pesquisas

• get_survey_report : o relatório completo de uma pesquisa em uma única chamada: visualizações, respostas, taxa de resposta e todas as perguntas em ordem com sua distribuição de pontuação, contagem de escolhas ou contagem de feedback, além da taxa de abandono entre as perguntas. (users:read)
• list_survey_responses : envios individuais, do mais recente para o mais antigo, uma entrada por pergunta. Esta é a fonte de verdade para o histórico de respostas e a forma de ler as respostas em texto livre. (users:read)

Base de conhecimento

• search_kb_articles : pesquisa de texto completo em seus artigos, classificados por relevância. (knowledge_base:read)
• get_kb_article : conteúdo completo de um artigo, incluindo o status de publicação e todos os idiomas. (knowledge_base:read)
• list_kb_categories : a estrutura completa da central de ajuda, categorias e subcategorias com seus IDs e títulos por idioma. Um título vazio significa que o idioma ainda não possui tradução. (knowledge_base:read)
• detect_kb_platform : detecta qual plataforma de central de ajuda (HubSpot, Zendesk, Intercom, Freshdesk, Help Scout, GitBook) hospeda um domínio. O primeiro passo de uma migração, para que o assistente saiba como o conteúdo de origem está estruturado. (knowledge_base:read)
• create_kb_article : cria um artigo com título, corpo e descrição opcional, arquivado em uma categoria ou subcategoria. (knowledge_base:write)
• update_kb_article : altera o título, o corpo, a descrição ou o arquivamento de um artigo. (knowledge_base:write)
• delete_kb_article : exclui permanentemente um artigo. (knowledge_base:write)
• create_kb_category : cria uma categoria de nível superior. Ela é criada em todos os idiomas, mas apenas o idioma em que você escreve recebe um título, portanto, os outros precisam ser preenchidos. (knowledge_base:write)
• update_kb_category : renomeie ou redefina o estilo de uma categoria, um idioma por vez. (knowledge_base:write)
• create_kb_sub_category : cria uma subcategoria dentro de uma categoria. As bases de conhecimento têm exatamente dois níveis de profundidade. (knowledge_base:write)
• update_kb_sub_category : renomeia uma subcategoria ou a move para uma categoria diferente. Movê-la reclassifica todos os artigos dentro dela. (knowledge_base:write)
• assign_kb_articles : arquiva até 50 artigos existentes em uma categoria ou subcategoria em uma única chamada. Os artigos são movidos, não copiados. (knowledge_base:write)

Os artigos escritos através do MCP são salvos como rascunhos. Alguém com permissão de publicação ainda precisa clicar em "Publicar" no painel, portanto, um assistente nunca poderá publicar conteúdo na sua central de ajuda por conta própria.

Atualizações de produtos

• list_product_updates_posts : posts existentes, do mais recente para o mais antigo, com seu conteúdo, etiquetas e status de publicação por idioma. Vale a pena chamar antes de escrever um novo para que o tom e a estrutura sejam consistentes. (product_updates:read)
• create_product_updates_post : cria uma publicação a partir de HTML. Ela é salva como rascunho para que você possa publicá-la no painel. (product_updates:write)
• update_product_updates_post : editar uma publicação. As alterações feitas em uma publicação já publicada são armazenadas como rascunho pendente. (product_updates:write)
• delete_product_updates_post : exclui permanentemente uma publicação e todas as suas traduções. (product_updates:write)

Roteiro e solicitações de recursos

• get_roadmap_overview : conta por estado de moderação, além das colunas de status e categorias do roadmap, em uma única chamada. O ponto de partida. (roadmap:read)
• list_feature_requests : solicitações filtradas por estado: pendentes (aba Novas/Caixa de Entrada), aprovadas (backlog aceito) e rejeitadas (spam). Contagem de votos e comentários em tempo real. (roadmap:read)
• get_feature_request : uma solicitação completa, incluindo suas traduções. (roadmap:read)
• list_roadmap_items : as solicitações publicadas no quadro público do roadmap, na ordem de suas colunas. (roadmap:read)
• approve_feature_request : move uma solicitação pendente para a lista de pendências aprovadas e para o roteiro público. (roadmap:write)
• reject_feature_request : move uma solicitação para a aba Spam e a mantém fora do roadmap público. (roadmap:write)

Ferramentas que alteram ou removem dados

Quatro ferramentas são irreversíveis: delete_user , reset_user_history , delete_kb_article e delete_product_updates_post . Elas estão marcadas como destrutivas no catálogo de ferramentas, portanto, assistentes bem-comportados solicitam confirmação antes de executá-las. Manter as permissões de escrita fora de uma conexão usada apenas para análise é a proteção mais robusta.

Artigos relacionados

• Guia do Usuário do Servidor MCP
• Configurando o servidor UserGuiding MCP
• Guia do Usuário: Casos de Uso e Exemplos de Instruções do MCP