Servidor MCP Inoyu Apache Unomi

Un servidor de protocolo de contexto de modelo que permite a Claude mantener el contexto del usuario a través de la gestión de perfiles Apache Unomi.

⚠️ Aviso de implementación anticipada

Esta es una implementación temprana destinada a fines de demostración:

• No validado para uso en producción
• Sujeto a cambios
• No (aún) oficialmente soportado
• Sólo para aprendizaje y experimentación.

Alcance actual

Esta implementación proporciona:

• Búsqueda y creación de perfiles mediante correo electrónico
• Gestión de propiedades de perfiles
• Manejo básico de sesiones
• Gestión del alcance para el aislamiento del contexto

Otras funciones de Unomi (eventos, segmentos, propiedades de sesión, etc.) no están implementadas actualmente. Agradecemos los comentarios de la comunidad sobre futuras prioridades de desarrollo.

Manifestación

Vea cómo el servidor MCP permite a Claude mantener el contexto y administrar los perfiles de usuario:

Instalación

Para utilizar con Claude Desktop, agregue la configuración del servidor y las variables de entorno:

En MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json En Windows: %APPDATA%/Claude/claude_desktop_config.json

La sección env de la configuración permite configurar las variables de entorno necesarias para el servidor. Reemplace los valores con los datos reales de su servidor Unomi.

Asegúrese de reiniciar Claude Desktop después de actualizar la configuración. Luego, puede hacer clic en el icono de herramientas en la esquina inferior derecha de la ventana de chat para comprobar que haya encontrado todas las herramientas proporcionadas por este servidor.

Características

Acceso al perfil

• Búsqueda de perfiles basada en correo electrónico con creación automática
• Acceso a propiedades de perfil, segmentos y puntuaciones
• Formato JSON para todo intercambio de datos
• Gestión automática de sesiones con identificaciones basadas en fechas

Herramientas

• get_my_profile - Obtenga su perfil usando variables de entorno
  • Utiliza UNOMI_PROFILE_ID del entorno o la búsqueda de correo electrónico
  • Genera automáticamente un ID de sesión basado en la fecha actual
  • Parámetros opcionales:
    • requireSegments: incluye información del segmento
    • requireScores: incluye información de puntuación
• update_my_profile - Actualiza las propiedades de tu perfil
  • Utiliza UNOMI_PROFILE_ID del entorno o la búsqueda de correo electrónico
  • Toma un objeto de propiedades con pares clave-valor para actualizar
  • Admite valores de cadena, número, booleano y nulo.
  • Ejemplo:
    { "properties": { "firstName": "John", "age": 30, "isSubscribed": true, "oldProperty": null } }
• get_profile - Recupera un perfil específico por ID
  • Toma profileId como parámetro obligatorio
  • Devuelve datos de perfil completos de Unomi
• search_profiles - Buscar perfiles
  • Toma una cadena de consulta y parámetros de límite/desplazamiento opcionales
  • Búsquedas en los campos de nombre, apellido y correo electrónico
• create_scope - Crea un nuevo ámbito Unomi
  • Toma el identificador de alcance y el nombre/descripción opcional
  • Necesario para el seguimiento de eventos y actualizaciones de perfil.
  • Ejemplo:
    { "scope": "my-app", "name": "My Application", "description": "Scope for my application events" }

Gestión del alcance

El servidor administra automáticamente los ámbitos para usted:

1. Alcance predeterminado:
   • Se utiliza un ámbito predeterminado claude-desktop para todas las operaciones
   • Creado automáticamente cuando es necesario
   • Se utiliza para actualizaciones de perfil y seguimiento de eventos.
2. Ámbitos personalizados:
   • Se puede crear utilizando la herramienta create_scope
   • Útil para separar diferentes aplicaciones o contextos.
   • Debe existir antes de usar en operaciones de perfil
3. Creación automática de alcance:
   • El servidor comprueba si existen los ámbitos requeridos
   • Los crea automáticamente si faltan
   • Utiliza valores predeterminados significativos para los metadatos del alcance

Nota : si bien los ámbitos se crean automáticamente cuando es necesario, también puedes crearlos manualmente con nombres y descripciones personalizados utilizando la herramienta create_scope .

Descripción general

Este servidor MCP permite a Claude mantener el contexto de los usuarios mediante el sistema de gestión de perfiles de Apache Unomi. Esto es lo que puede lograr con él:

Capacidades clave

1. Reconocimiento de usuario :
   • Identificar a los usuarios en las conversaciones mediante el correo electrónico o el ID del perfil
   • Mantener un contexto de usuario consistente entre sesiones
   • Crear y gestionar automáticamente perfiles de usuario
2. Gestión del contexto :
   • Almacenar y recuperar las preferencias del usuario
3. Características de integración :
   • Integración perfecta con Claude Desktop
   • Gestión automática de sesiones
   • Aislamiento de contexto basado en el alcance

Qué puedes hacer

• Haga que Claude recuerde las preferencias del usuario en todas las conversaciones
• Almacenar y recuperar información específica del usuario
• Mantener un contexto de usuario consistente
• Administrar múltiples usuarios a través de identificación por correo electrónico

Prerrequisitos

• Ejecución del servidor Apache Unomi
• Instalación de Claude Desktop
• Acceso de red al servidor Unomi
• Configuración de seguridad adecuada
• Variables de entorno requeridas

Configuración

Variables de entorno

El servidor requiere las siguientes variables de entorno:

Resolución de perfil

El servidor utiliza un proceso de dos pasos para resolver el ID del perfil:

1. Búsqueda de correo electrónico (si está configurado UNOMI_EMAIL ):
   • Busca un perfil con correo electrónico coincidente
   • Si se encuentra, utiliza el ID de ese perfil.
   • Útil para mantener un perfil consistente en todas las sesiones
2. ID de perfil de respaldo:
   • Si la búsqueda de correo electrónico falla o no se configura UNOMI_EMAIL
   • Utiliza el UNOMI_PROFILE_ID del entorno
   • Garantiza que un perfil esté siempre disponible

La respuesta indicará qué método se utilizó a través del campo source :

• "email_lookup" : Perfil encontrado por correo electrónico
• "environment" : uso del ID del perfil de respaldo

Configuración del servidor Unomi

1. Configurar eventos protegidos en etc/org.apache.unomi.cluster.cfg :
   # Required for protected events like property updates org.apache.unomi.cluster.authorization.key=your-unomi-key # Required to allow Claude Desktop to access Unomi # Replace your-claude-desktop-ip with your actual IP org.apache.unomi.ip.ranges=127.0.0.1,::1,your-claude-desktop-ip
2. Asegúrese de que su servidor Unomi tenga CORS configurado correctamente en etc/org.apache.unomi.cors.cfg :
   # Add your Claude Desktop origin if needed org.apache.unomi.cors.allowed.origins=http://localhost:*
3. Reinicie el servidor Unomi para aplicar los cambios

Importante : La clave Unomi debe coincidir exactamente entre la configuración de su servidor y la variable de entorno UNOMI_KEY en Claude Desktop.

Configuración

Variables de entorno

El servidor requiere las siguientes variables de entorno:

Resolución de perfil

El servidor utiliza un proceso de dos pasos para resolver el ID del perfil:

1. Búsqueda de correo electrónico (si está configurado UNOMI_EMAIL ):
   • Busca un perfil con correo electrónico coincidente
   • Si se encuentra, utiliza el ID de ese perfil.
   • Útil para mantener un perfil consistente en todas las sesiones
2. ID de perfil de respaldo:
   • Si la búsqueda de correo electrónico falla o no se configura UNOMI_EMAIL
   • Utiliza el UNOMI_PROFILE_ID del entorno
   • Garantiza que un perfil esté siempre disponible

La respuesta indicará qué método se utilizó a través del campo source :

• "email_lookup" : Perfil encontrado por correo electrónico
• "environment" : uso del ID del perfil de respaldo

Configuración del servidor Unomi

1. Configurar eventos protegidos en etc/org.apache.unomi.cluster.cfg :
   # Required for protected events like property updates org.apache.unomi.cluster.authorization.key=your-unomi-key # Required to allow Claude Desktop to access Unomi # Replace your-claude-desktop-ip with your actual IP org.apache.unomi.ip.ranges=127.0.0.1,::1,your-claude-desktop-ip
2. Asegúrese de que su servidor Unomi tenga CORS configurado correctamente en etc/org.apache.unomi.cors.cfg :
   # Add your Claude Desktop origin if needed org.apache.unomi.cors.allowed.origins=http://localhost:*
3. Reinicie el servidor Unomi para aplicar los cambios

Importante : La clave Unomi debe coincidir exactamente entre la configuración de su servidor y la variable de entorno UNOMI_KEY en Claude Desktop.

Desarrollo

Instalar dependencias:

Construir el servidor:

Para desarrollo con reconstrucción automática:

Depuración

Dado que los servidores MCP se comunican a través de stdio, la depuración puede ser complicada. Recomendamos usar el Inspector MCP , disponible como script de paquete:

El Inspector proporcionará una URL para acceder a las herramientas de depuración en su navegador.

También puedes seguir los registros de Claude Desktop para ver las solicitudes y respuestas de MCP:

Formato de ID de sesión

Al utilizar get_my_profile , el ID de sesión se genera automáticamente utilizando el formato:

Por ejemplo, si su ID de perfil es "usuario123" y hoy es 15 de marzo de 2024, el ID de sesión sería:

Solución de problemas

Problemas comunes

1. Eventos protegidos fallidos
   • Verificar que la clave Unomi coincida exactamente en ambas configuraciones
   • Compruebe que la dirección IP esté correctamente incluida en la lista blanca
   • Asegúrese de que exista alcance antes de actualizar las propiedades
   • Verifique la configuración de CORS si es necesario
2. Perfil no encontrado
   • Compruebe si UNOMI_EMAIL está configurado correctamente
   • Verificar que el formato del correo electrónico sea válido
   • Asegúrese de que el perfil exista en Unomi
   • Compruebe si el UNOMI_PROFILE_ID de respaldo es válido
3. Problemas de sesión
   • Recuerde que las sesiones se basan en fechas.
   • Sólo una sesión por perfil por día
   • Verificar que el formato del ID de sesión coincida con profileId-YYYYMMDD
   • Verificar que exista alcance para la sesión
4. Problemas de conexión
   • Verificar que el servidor Unomi esté en ejecución
   • Comprobar la conectividad de la red
   • Asegúrese de que UNOMI_BASE_URL sea correcto
   • Verificar credenciales de autenticación

Registros para comprobar

1. Registros del escritorio de Claude :
   # MacOS ~/Library/Logs/Claude/mcp*.log # Windows %APPDATA%\Claude\mcp*.log
2. Registros del servidor Unomi :
   # Usually in $UNOMI_HOME/logs/karaf.log

Soluciones rápidas

1. Estado de reinicio :
   # Stop Claude Desktop # Clear logs rm ~/Library/Logs/Claude/mcp*.log # Restart Claude Desktop
2. Verificar configuración :
   # Check Unomi connection curl -u username:password http://your-unomi-server:8181/cxs/cluster # Test scope exists curl -u username:password http://your-unomi-server:8181/cxs/scopes/claude-desktop

Opciones de configuración de Claude Desktop

1. Crea o edita tu configuración de Claude Desktop:
   • MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Ventanas: %APPDATA%/Claude/claude_desktop_config.json
2. Agregue la configuración del servidor usando NPX:
   { "mcpServers": { "unomi-server": { "command": "npx", "args": ["@inoyu/mcp-unomi-server"], "env": { "UNOMI_BASE_URL": "http://your-unomi-server:8181", "UNOMI_USERNAME": "your-username", "UNOMI_PASSWORD": "your-password", "UNOMI_PROFILE_ID": "your-profile-id", "UNOMI_KEY": "your-unomi-key", "UNOMI_EMAIL": "your-email@example.com", "UNOMI_SOURCE_ID": "claude-desktop" } } } }

Nota : el uso de NPX garantiza que siempre esté ejecutando la última versión publicada del servidor.

Alternativamente, si desea utilizar una versión específica:

Para desarrollo o instalaciones locales: