Umami Analytics

Acesse dados de análise de websites da sua instância Umami.

GitHub
9

Documentação

Servidor MCP Umami Analytics

Um servidor Model Context Protocol (MCP) que aprimora as capacidades do Claude, fornecendo acesso a dados de análise de websites do Umami. Este servidor permite que o Claude analise o comportamento do usuário, acompanhe o desempenho do website e forneça insights baseados em dados.

O código-fonte foi gerado do início ao fim usando Claude Sonnet 3.5 e Cursor.

alt text

O Que Ele Faz

Este servidor conecta o Claude à sua plataforma de análise Umami, permitindo que ele:

  • Analise jornadas do usuário e padrões de comportamento
  • Acompanhe métricas de desempenho do website
  • Monitore a atividade de visitantes em tempo real
  • Capture e analise o conteúdo de páginas web
  • Gere insights a partir de dados históricos de análise

Como Funciona

O servidor fornece as seguintes ferramentas ao Claude para analisar dados do website:

Ferramentas Disponíveis

  • get_websites: Recupere uma lista de websites e seus IDs na sua conta Umami
  • get_website_stats: Obtenha métricas principais como pageviews, visitantes, taxa de rejeição de um website
  • get_website_metrics: Analise métricas específicas como URLs, referenciadores, navegadores, países
  • get_pageview_series: Obtenha dados de pageviews em série temporal com intervalos personalizáveis
  • get_active_visitors: Monitore o número atual de visitantes ativos em um website
  • get_session_ids: Recupere IDs de sessão para eventos ou períodos de tempo específicos
  • get_tracking_data: Obtenha dados detalhados de atividade para um ID de sessão específico
  • get_docs: Realize busca semântica em muitas jornadas do usuário, retornando os trechos mais relevantes para uma determinada pergunta
  • get_screenshot: Capture instantâneos visuais de páginas web
  • get_html: Recupere e analise o código-fonte HTML de páginas web

Cada ferramenta tem uma descrição e uma lista de argumentos que podem ser passados a ela. Estes são usados para fornecer contexto e informações que permitem ao Claude selecionar efetivamente a(s) ferramenta(s) certa(s) para o trabalho e fornecer os parâmetros corretos.

A maioria dessas ferramentas puxa dados diretamente da API do Umami para o Claude Desktop; no entanto, o get_docs adiciona uma etapa de busca semântica para evitar problemas de janela de contexto com o Claude, além de economizar no uso de tokens. Todas as jornadas do usuário para um determinado evento são recuperadas usando a API do Umami e, em seguida, são divididas em seções menores e incorporadas usando um modelo de transformador de frases de código aberto do hugging face. Então, com base na pergunta, os trechos mais relevantes são recuperados e retornados ao Claude, permitindo a análise de ações e comportamentos específicos realizados pelos usuários no website, algo difícil de replicar com ferramentas tradicionais de visualização de dados. A implementação dessa incorporação e busca semântica está no arquivo src/analytics_service/embeddings.py.

Além disso, as ferramentas get_screenshot e get_html usam o rastreador web de código aberto Crawl4AI para recuperar o código-fonte HTML e a captura de tela de um determinado website. As capturas de tela precisam ser reduzidas para diminuir seu tamanho e evitar problemas de janela de contexto com o Claude. Isso permite fornecer contexto ao Claude sobre como o website é estruturado e como ele se parece, permitindo recomendações mais precisas e relevantes para melhorar o desempenho do site. A implementação do rastreador web está no arquivo src/analytics_service/crawler.py.

alt text

Guia de Configuração

Pré-requisitos

  • instalar uv: pip install uv

  1. Configuração do Claude Desktop

    Adicione o seguinte ao arquivo de configuração do seu Claude Desktop:

    • MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%/Claude/claude_desktop_config.json
    {
  "mcpServers": {
    "analytics_service": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/analytics_service",
        "run",
        "analytics-service"
      ],
      "env": {
       "UMAMI_API_URL": "https://example.com",
       "UMAMI_USERNAME": "yourUmamiUsername",
       "UMAMI_PASSWORD": "yourUmamiPassword", 
       "UMAMI_TEAM_ID": "yourUmamiTeamId"
     }
    }
  }
}

    Substitua /path/to/analytics_service pelo caminho real para o diretório analytics_service.

    Para a UMAMI_API_URL, substitua https://example.com pela URL da versão do Umami que você está usando (auto-hospedada ou hospedada no Umami Cloud). Para o UMAMI_USERNAME e UMAMI_PASSWORD, substitua yourUmamiUsername e yourUmamiPassword pelas suas credenciais de conta Umami. Para o UMAMI_TEAM_ID, substitua yourUmamiTeamId pelo ID da equipe que você deseja analisar.

  2. Abrindo o Claude Desktop

Quando você abrir o Claude Desktop, ele começará automaticamente a se conectar ao servidor MCP analytics_service. Aguarde até alguns minutos, pois o servidor é inicializado e os pacotes corretos são instalados. Quando o servidor estiver pronto, você verá 10 ferramentas MCP disponíveis no canto inferior direito da janela de chat. Isso é indicado por um pequeno ícone de martelo com o número 10 ao lado.

alt text

Além disso, se você ainda não o fez, é fortemente recomendado habilitar a "Analysis tool" em Feature Preview no Claude Desktop. Isso permitirá que o Claude crie painéis e outras visualizações para seus dados. Para fazer isso, no painel do lado esquerdo, encontre a aba "Feature Preview" e, nela, habilite a "Analysis tool". A renderização LaTeX também pode ser habilitada na mesma seção.

alt text

Como Usar o Servidor

Começando

A maneira mais simples de começar é usar o Create Dashboard Prompt fornecido pelo servidor. Ele é selecionado clicando no botão de anexo "Attach from MCP" no canto inferior esquerdo da janela de chat. Em seguida, selecione "choose implementation" e depois o "Create Dashboard Prompt".

alt text

Isso o guiará pelo processo de criação de um painel para o seu website, solicitando:

  1. O nome do website que você deseja analisar
  2. As datas de início e fim para a análise
  3. O fuso horário do website

Depois de fornecer essas informações, o servidor gerará um arquivo txt instruindo o Claude sobre como construir o painel. Pressione enter na janela de chat e o Claude fará o resto. Você pode então pedir ao Claude para fazer alterações no painel ou adicionar outras visualizações.

alt text

Uso em Linguagem Natural

Para uma experiência mais personalizável, você pode falar diretamente com o Claude e especificar seus próprios requisitos, como quais dados deseja ver no painel e quais visualizações deseja usar. Além disso, você pode analisar jornadas do usuário para identificar pontos problemáticos específicos e adicionar capturas de tela do seu site para dar contexto extra ao Claude.

As ferramentas necessárias para concluir sua solicitação serão usadas automaticamente pelo Claude. Basta fazer sua solicitação em linguagem natural e o Claude decidirá quais ferramentas usar. Se quiser ver uma lista de todas as ferramentas disponíveis, você pode pedir ao Claude para listá-las ou clicar no ícone de martelo no canto inferior direito da janela de chat.

alt text

Crie seus próprios prompts

Você também pode criar seus próprios prompts para fluxos de trabalho que usa regularmente. Para isso, você precisará:

  1. Defina a Estrutura do Seu Prompt Crie uma definição de prompt que inclua:

    • name: Um identificador único para o seu prompt
    • description: Uma explicação clara do que o prompt faz
    • arguments: Lista de parâmetros de entrada que seu prompt precisa

    Adicione isso à função list_prompts() em src/analytics_service/server.py:

    Exemplo de estrutura:

    @app.list_prompts()
async def list_prompts():
    return [
        # ... existing prompts ...
        {
            "name": "Your Prompt Name",
            "description": "Your prompt description",
            "arguments": [
                {
                    "name": "Parameter Name 1",
                    "description": "Parameter description",
                    "required": True/False
                },
                {
                    "name": "Parameter Name 2",
                    "description": "Parameter description",
                    "required": True/False
                }
            ]
        }
    ]

  2. Implemente o Prompt Adicione sua lógica de tratamento do prompt na função get_prompt() em src/analytics_service/server.py:

    @app.get_prompt()
async def get_prompt(name: str, arguments: Any):
 # ... existing prompts ...
    if name == "Your Prompt Name":
        return {
            "messages": [
                {
                    "role": "user",
                    "content": {
                        "type": "text",
                        "text": f"Your prompt template with {arguments['Parameter Name']}"
                    }
                }
            ]
        }

    Ao definir mensagens no seu prompt, o campo role é crucial para estruturar a conversa:

    • Use "role": "user" para mensagens que simulam entrada ou perguntas do usuário
    • Use "role": "assistant" para mensagens que representam respostas ou instruções do Claude
    • Use "role": "system" para mensagens que definem contexto ou fornecem instruções de alto nível

    O campo content em cada mensagem deve especificar um type. Os tipos disponíveis são:

    • "type": "text" - Para conteúdo de texto simples
    • "type": "resource" - Para incluir recursos externos como arquivos, logs ou outros dados. Deve incluir um objeto resource com:
      • uri: O identificador do recurso
      • text: O conteúdo real
      • mimeType: O tipo MIME do conteúdo (por exemplo, "text/plain", "text/x-python")

    Embora os recursos incluam seu conteúdo no campo text, usar o tipo resource fornece vários benefícios importantes:

    1. Consciência do Tipo de Conteúdo: O campo mimeType informa ao Claude como interpretar o conteúdo (por exemplo, como código Python, texto simples ou outros formatos)
    2. Rastreamento de Origem: O campo uri mantém uma referência de onde o conteúdo veio, o que pode ser útil para:
      • Rastrear a origem dos dados
      • Permitir atualizações se a fonte mudar
      • Fornecer contexto sobre a localização e o propósito do recurso
    3. Manipulação de Dados Estruturados: O formato de recurso permite o tratamento consistente de diferentes tipos de conteúdo, mantendo metadados sobre cada recurso

    Aqui está um exemplo mostrando diferentes papéis e tipos de conteúdo:

    "messages": [
    {
        "role": "system",
        "content": {
            "type": "text",
            "text": "Analyze the following log file and code for potential issues."
        }
    },
    {
        "role": "user",
        "content": {
            "type": "resource",
            "resource": {
                "uri": "logs://recent",
                "text": "[2024-03-14 15:32:11] ERROR: Connection timeout",
                "mimeType": "text/plain"
            }
        }
    },
    {
        "role": "assistant",
        "content": {
            "type": "text",
            "text": "I notice a connection timeout error. Let me examine the related code."
        }
    },
    {
        "role": "user",
        "content": {
            "type": "resource",
            "resource": {
                "uri": "file:///code.py",
                "text": "def example():\n    pass",
                "mimeType": "text/x-python"
            }
        }
    }
]

    Para a maioria dos prompts, o tipo texto com papel de usuário é mais que suficiente e dá ao Claude mais controle e criatividade em suas respostas. Para fluxos de trabalho mais complexos, no entanto, múltiplas mensagens com diferentes papéis e tipos permitem um fluxo de conversa mais estruturado e mais controle do usuário sobre a resposta.

  3. Melhores Práticas para Criar Prompts

    • Torne seus prompts focados e específicos
    • Inclua requisitos claros de validação para argumentos
    • Use nomes descritivos para parâmetros
    • Inclua valores de exemplo nas descrições dos parâmetros
    • Estruture o modelo de prompt para guiar o Claude efetivamente
    • Considere tratamento de erros e casos extremos
    • Teste o prompt com várias entradas