Umami Analytics

Accede a los datos de análisis web desde tu instancia de Umami.

GitHub
9

Documentación

Servidor MCP de Umami Analytics

Un servidor de Model Context Protocol (MCP) que mejora las capacidades de Claude al proporcionar acceso a datos de análisis web de Umami. Este servidor permite a Claude analizar el comportamiento de los usuarios, realizar un seguimiento del rendimiento del sitio web y proporcionar información basada en datos.

El código base ha sido generado de principio a fin utilizando Claude Sonnet 3.5 y Cursor.

alt text

Qué Hace

Este servidor conecta a Claude con tu plataforma de análisis de Umami, permitiéndole:

  • Analizar los recorridos de los usuarios y los patrones de comportamiento
  • Realizar un seguimiento de las métricas de rendimiento del sitio web
  • Monitorear la actividad de los visitantes en tiempo real
  • Capturar y analizar el contenido de las páginas web
  • Generar información a partir de datos históricos de análisis

Cómo Funciona

El servidor proporciona las siguientes herramientas a Claude para analizar datos del sitio web:

Herramientas Disponibles

  • get_websites: Recuperar una lista de sitios web y sus IDs en tu cuenta de Umami
  • get_website_stats: Obtener métricas clave como visitas a páginas, visitantes y tasa de rebote de un sitio web
  • get_website_metrics: Analizar métricas específicas como URLs, referentes, navegadores y países
  • get_pageview_series: Obtener datos de visitas a páginas en series temporales con intervalos personalizables
  • get_active_visitors: Monitorear el número actual de visitantes activos en un sitio web
  • get_session_ids: Recuperar IDs de sesión para eventos o períodos de tiempo específicos
  • get_tracking_data: Obtener datos detallados de actividad para un ID de sesión específico
  • get_docs: Realizar búsqueda semántica en muchos recorridos de usuarios, devolviendo los fragmentos más relevantes para una pregunta determinada
  • get_screenshot: Capturar instantáneas visuales de páginas web
  • get_html: Recuperar y analizar el código fuente HTML de páginas web

Cada herramienta tiene una descripción y una lista de argumentos que se le pueden pasar. Estos se utilizan para proporcionar contexto e información que permitan a Claude seleccionar eficazmente la(s) herramienta(s) adecuada(s) para el trabajo y proporcionar los parámetros correctos.

La mayoría de estas herramientas extraen datos directamente de la API de Umami a Claude Desktop; sin embargo, get_docs añade un paso de búsqueda semántica para evitar problemas de ventana de contexto con Claude, además de ahorrar en el uso de tokens. Todos los recorridos de usuarios para un evento determinado se recuperan mediante la API de Umami y luego se dividen en secciones más pequeñas y se incrustan utilizando un modelo de transformador de oraciones de código abierto de Hugging Face. Luego, según la pregunta, se recuperan y devuelven a Claude los fragmentos más relevantes, lo que permite analizar acciones y comportamientos específicos realizados por los usuarios en el sitio web, algo difícil de replicar con herramientas tradicionales de visualización de datos. La implementación de esta incrustación y búsqueda semántica se encuentra en el archivo src/analytics_service/embeddings.py.

Adicionalmente, las herramientas get_screenshot y get_html utilizan el rastreador web de código abierto Crawl4AI para recuperar el código fuente HTML y la captura de pantalla de un sitio web determinado. Las capturas de pantalla deben reducirse en tamaño para evitar problemas de ventana de contexto con Claude. Esto te permite proporcionar contexto a Claude sobre cómo está estructurado el sitio web y cómo se ve, lo que permite recomendaciones más precisas y relevantes para mejorar el rendimiento del sitio. La implementación del rastreador web se encuentra en el archivo src/analytics_service/crawler.py.

alt text

Guía de Configuración

Requisitos Previos

  • instalar uv: pip install uv

  1. Configuración de Claude Desktop

    Añade lo siguiente a tu archivo de configuración de 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"
     }
    }
  }
}

    Reemplaza /path/to/analytics_service con la ruta real a tu directorio de analytics_service.

    Para UMAMI_API_URL, reemplaza https://example.com con la URL de la versión de Umami que estés utilizando (ya sea autoalojada o alojada en Umami Cloud). Para UMAMI_USERNAME y UMAMI_PASSWORD, reemplaza yourUmamiUsername y yourUmamiPassword con las credenciales de tu cuenta de Umami. Para UMAMI_TEAM_ID, reemplaza yourUmamiTeamId con el ID del equipo que deseas analizar.

  2. Abrir Claude Desktop

    Cuando abras Claude Desktop, comenzará automáticamente a conectarse al servidor MCP de analytics_service. Espera hasta unos minutos mientras el servidor se inicializa y se instalan los paquetes correctos. Cuando el servidor esté listo, verás 10 herramientas MCP disponibles en la parte inferior derecha de la ventana de chat. Esto se indica con un pequeño icono de martillo y el número 10 junto a él.

    alt text

    Además, si aún no lo has hecho, se recomienda encarecidamente que habilites la "herramienta de Análisis" en Vista Previa de Funciones dentro de Claude Desktop. Esto permitirá a Claude crear paneles de control y otras visualizaciones para tus datos. Para hacer esto, en el panel lateral izquierdo, busca la pestaña "Vista Previa de Funciones" y, dentro de ella, habilita la "herramienta de Análisis". El Renderizado de LaTeX también se puede habilitar en la misma sección.

    alt text

    Cómo Usar el Servidor

    Primeros Pasos

    La forma más sencilla de comenzar es usar el Prompt de Creación de Panel de Control proporcionado por el servidor. Esto se selecciona haciendo clic en el botón de adjuntar "Adjuntar desde MCP" en la parte inferior izquierda de la ventana de chat. Luego selecciona elegir implementación y después el Prompt de Creación de Panel de Control.

    alt text

    Esto te guiará a través del proceso de creación de un panel de control para tu sitio web, solicitando:

    1. El nombre del sitio web que deseas analizar
    2. Las fechas de inicio y fin para el análisis
    3. La zona horaria del sitio web

    Una vez que hayas proporcionado esta información, el servidor generará un archivo txt que instruye a Claude sobre cómo construir el panel de control. Pulsa enter en la ventana de chat y Claude hará el resto. Luego puedes pedirle a Claude que haga cualquier cambio en el panel de control o que añada otras visualizaciones.

    alt text

    Uso en Lenguaje Natural

    Para una experiencia más personalizable, puedes hablar directamente con Claude y especificar tus propios requisitos, como qué datos deseas ver en el panel de control y qué visualizaciones deseas utilizar. Además, puedes analizar los recorridos de los usuarios para identificar puntos de fricción específicos y añadir capturas de pantalla de tu sitio para darle a Claude contexto adicional.

    Las herramientas necesarias para completar tu solicitud serán utilizadas por Claude automáticamente. Simplemente haz tu solicitud en lenguaje natural y Claude decidirá qué herramientas usar. Si deseas ver una lista de todas las herramientas disponibles, puedes pedirle a Claude que las liste o hacer clic en el icono de martillo en la parte inferior derecha de la ventana de chat.

    alt text

    Crea tus propios prompts

    También puedes crear tus propios prompts para flujos de trabajo que utilices regularmente. Para hacer esto, necesitarás:

  3. Define la Estructura de tu Prompt Crea una definición de prompt que incluya:

    • name: Un identificador único para tu prompt
    • description: Una explicación clara de lo que hace el prompt
    • arguments: Lista de parámetros de entrada que necesita tu prompt

    Añade esto a la función list_prompts() en src/analytics_service/server.py:

    Estructura de ejemplo:

    @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
                }
            ]
        }
    ]

  4. Implementa el Prompt Añade tu lógica de manejo del prompt en la función get_prompt() en 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']}"
                    }
                }
            ]
        }

    Al definir mensajes en tu prompt, el campo role es crucial para estructurar la conversación:

    • Usa "role": "user" para mensajes que simulan entrada o preguntas del usuario
    • Usa "role": "assistant" para mensajes que representan respuestas o instrucciones de Claude
    • Usa "role": "system" para mensajes que establecen contexto o proporcionan instrucciones de alto nivel

    El campo content en cada mensaje debe especificar un type. Los tipos disponibles son:

    • "type": "text" - Para contenido de texto plano
    • "type": "resource" - Para incluir recursos externos como archivos, registros u otros datos. Debe incluir un objeto resource con:
      • uri: El identificador del recurso
      • text: El contenido real
      • mimeType: El tipo MIME del contenido (por ejemplo, "text/plain", "text/x-python")

    Si bien los recursos incluyen su contenido en el campo text, usar el tipo resource proporciona varios beneficios importantes:

    1. Conocimiento del Tipo de Contenido: El campo mimeType le dice a Claude cómo interpretar el contenido (por ejemplo, como código Python, texto plano u otros formatos)
    2. Seguimiento de la Fuente: El campo uri mantiene una referencia de dónde proviene el contenido, lo que puede ser útil para:
      • Realizar un seguimiento del origen de los datos
      • Permitir actualizaciones si la fuente cambia
      • Proporcionar contexto sobre la ubicación y el propósito del recurso
    3. Manejo de Datos Estructurados: El formato de recurso permite un manejo consistente de diferentes tipos de contenido mientras se mantienen metadatos sobre cada recurso

    Aquí hay un ejemplo que muestra diferentes roles y tipos de contenido:

    "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 la mayoría de los prompts, el tipo de texto con rol de usuario es más que suficiente y le da a Claude más control y creatividad en sus respuestas. Sin embargo, para flujos de trabajo más complejos, múltiples mensajes con diferentes roles y tipos permiten un flujo de conversación más estructurado y más control del usuario sobre la respuesta.

  5. Mejores Prácticas para Crear Prompts

    • Haz que tus prompts sean enfocados y específicos
    • Incluye requisitos claros de validación para los argumentos
    • Usa nombres descriptivos para los parámetros
    • Incluye valores de ejemplo en las descripciones de los parámetros
    • Estructura la plantilla del prompt para guiar a Claude de manera efectiva
    • Considera el manejo de errores y los casos límite
    • Prueba el prompt con varias entradas