Servidor MCP de Umami Analytics

Un servidor de Protocolo de Contexto de Modelo (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, monitorizar el rendimiento del sitio web y proporcionar información basada en datos.

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

Qué hace

Este servidor conecta a Claude a su plataforma de análisis Umami, lo que le permite:

• 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 la página web
• Generar información a partir de datos analíticos históricos

Cómo funciona

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

Herramientas disponibles

• get_websites : recupera una lista de sitios web y sus ID en tu cuenta Umami
• get_website_stats : Obtenga métricas clave como páginas vistas, visitantes y tasa de rebote de un sitio web
• get_website_metrics : analiza métricas específicas como URL, referentes, navegadores y países
• get_pageview_series : Obtenga datos de páginas vistas en series temporales con intervalos personalizables
• get_active_visitors : Monitorea el número actual de visitantes activos en un sitio web
• get_session_ids : recupera los ID de sesión para eventos o períodos de tiempo específicos
• get_tracking_data : obtiene datos detallados de la actividad para un ID de sesión específico
• get_docs : realiza una búsqueda semántica en muchos recorridos de usuario y devuelve los fragmentos más relevantes para una pregunta determinada
• get_screenshot : Captura instantáneas visuales de páginas web
• get_html : recupera y analiza el código fuente HTML de la página 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 permiten a Claude seleccionar eficazmente las herramientas adecuadas para el trabajo y proporcionar los parámetros correctos.

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

Además, 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. Es necesario reducir el tamaño de las capturas de pantalla para evitar problemas con la ventana de contexto de Claude. Esto permite contextualizar a Claude sobre la estructura y el aspecto del sitio web, lo que permite realizar recomendaciones más precisas y relevantes para mejorar su rendimiento. La implementación del rastreador web se encuentra en el archivo src/analytics_service/crawler.py .

Guía de configuración

Prerrequisitos

• instalar uv: pip install uv

1. Configuración del escritorio de ClaudeAgregue lo siguiente a su archivo de configuración de Claude Desktop:
   • MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Ventanas: %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" } } } }

   Reemplace /path/to/analytics_service con la ruta real a su directorio analytics_service.

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

2. Abriendo Claude Desktop

Al abrir Claude Desktop, se conectará automáticamente al servidor MCP de analytics_service. Espere unos minutos mientras el servidor se inicializa y se instalan los paquetes correctos. Cuando el servidor esté listo, verá 10 herramientas MCP disponibles en la esquina 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.

Además, si aún no lo ha hecho, le recomendamos encarecidamente que habilite la herramienta de análisis en la vista previa de funciones de Claude Desktop. Esto le permitirá a Claude crear paneles y otras visualizaciones para sus datos. Para ello, en el panel izquierdo, busque la pestaña "Vista previa de funciones" y, allí, habilite la herramienta de análisis. El renderizado LaTeX también se puede habilitar en la misma sección.

Cómo utilizar el servidor

Empezando

La forma más sencilla de empezar es usar la solicitud de creación de panel proporcionada por el servidor. Para ello, haga clic en el botón "Adjuntar desde MCP" en la parte inferior izquierda de la ventana de chat. A continuación, seleccione "Elegir implementación" y, a continuación, seleccione la solicitud de creación de panel.

Esto lo guiará a través del proceso de creación de un panel para su sitio web y le solicitará lo siguiente:

1. El nombre del sitio web que desea analizar
2. Las fechas de inicio y finalización del análisis
3. La zona horaria del sitio web

Una vez que hayas proporcionado esta información, el servidor generará un archivo .txt con instrucciones para que Claude cree el panel. Presiona Enter en la ventana de chat y Claude se encargará del resto. Después, puedes pedirle que realice cambios en el panel o añada otras visualizaciones.

Uso del lenguaje natural

Para una experiencia más personalizada, puedes hablar directamente con Claude y especificar tus necesidades, como los datos que quieres ver en el panel y las visualizaciones que quieres usar. Además, puedes analizar las experiencias de los usuarios para identificar problemas específicos y añadir capturas de pantalla de tu sitio web para darle a Claude más contexto.

Claude utilizará automáticamente las herramientas necesarias para completar tu solicitud. Simplemente realiza tu solicitud en lenguaje natural y Claude decidirá qué herramientas usar. Si quieres ver una lista de todas las herramientas disponibles, puedes pedirle a Claude que las enumere o hacer clic en el icono del martillo en la esquina inferior derecha del chat.

Crea tus propias indicaciones

También puedes crear tus propias indicaciones para los flujos de trabajo que utilizas habitualmente. Para ello, necesitarás:

1. Define la estructura de tu propuesta Crea una definición de propuesta que incluya:
   • name : Un identificador único para su mensaje
   • description : Una explicación clara de lo que hace el mensaje.
   • arguments : Lista de parámetros de entrada que necesita su solicitud

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

   Ejemplo de estructura:

   @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. Implementar el aviso Agregue su lógica de manejo del aviso 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 su mensaje, el campo role es crucial para estructurar la conversación:
   • Utilice "role": "user" para mensajes que simulen entradas o preguntas del usuario
   • Utilice "role": "assistant" para los mensajes que representan las respuestas o instrucciones de Claude.
   • Utilice "role": "system" para mensajes que establecen contexto o proporcionan instrucciones de alto nivel

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

   • "type": "text" - Para contenido de texto sin formato
   • "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 , el uso del tipo resource proporciona varios beneficios importantes:

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

   A continuación se muestra 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 las indicaciones, el tipo de texto con rol de usuario es más que suficiente y permite a Claude mayor control y creatividad en sus respuestas. Sin embargo, para flujos de trabajo más complejos, la posibilidad de usar varios mensajes con diferentes roles y tipos permite una conversación más estructurada y un mayor control del usuario sobre la respuesta.

3. Mejores prácticas para crear indicaciones
   • Haz que tus indicaciones sean enfocadas y específicas
   • Incluir requisitos de validación claros para los argumentos
   • Utilice nombres descriptivos para los parámetros
   • Incluir valores de ejemplo en las descripciones de los parámetros
   • Estructura la plantilla de indicaciones para guiar a Claude de manera eficaz
   • Considere el manejo de errores y casos extremos
   • Pruebe el mensaje con varias entradas