Inoyu Apache Unomi

Mantiene el contexto del usuario y gestiona perfiles utilizando la plataforma de datos del cliente Apache Unomi.

Documentación

Servidor MCP Inoyu Apache Unomi

Un servidor de Protocolo de Contexto de Modelo (MCP) que permite a Claude mantener el contexto del usuario mediante la gestión de perfiles de Apache Unomi.

⚠️ Aviso de Implementación Temprana

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

No validada para uso en producción

Sujeta a cambios

No soportada oficialmente (aún)

Solo 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 perfil
Manejo básico de sesiones
Gestión de ámbitos (scopes) para aislamiento de contexto

Otras características de Unomi (eventos, segmentos, propiedades de sesión, etc.) no están implementadas actualmente. Se agradecen comentarios de la comunidad sobre prioridades de desarrollo futuras.

Demo

Mira cómo el servidor MCP permite a Claude mantener contexto y gestionar perfiles de usuario:

Instalación

Para usar con Claude Desktop, añade 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

{
  "mcpServers": {
    "unomi-server": {
      "command": "npx",
      "args": ["@inoyu/mcp-unomi-server"],
      "env": {
        "UNOMI_BASE_URL": "http://your-unomi-server:8181",
        "UNOMI_VERSION": "3", // Use "2" for Unomi V2, "3" for Unomi V3 (default)
        "UNOMI_USERNAME": "your-username", // Required for V2, fallback for V3
        "UNOMI_PASSWORD": "your-password", // Required for V2, fallback for V3
        "UNOMI_PROFILE_ID": "your-profile-id",
        "UNOMI_KEY": "your-unomi-key", // Required for V2 only
        "UNOMI_EMAIL": "your-email@example.com",
        "UNOMI_SOURCE_ID": "claude-desktop",
        "UNOMI_TENANT_ID": "your-tenant-id", // Required for V3
        "UNOMI_PUBLIC_KEY": "your-public-key", // Required for V3
        "UNOMI_PRIVATE_KEY": "your-private-key" // Required for V3
      }
    }
  }
}

La sección env en la configuración te permite establecer las variables de entorno requeridas para el servidor. Reemplaza los valores con los detalles reales de tu servidor Unomi.

Asegúrate de reiniciar Claude Desktop después de actualizar la configuración. Luego puedes hacer clic en el icono de herramientas en la parte inferior derecha de la ventana de chat para verificar que ha encontrado todas las herramientas proporcionadas por este servidor.

Características

Acceso a Perfiles

Búsqueda de perfiles por correo electrónico con creación automática
Acceso a propiedades de perfil, segmentos y puntuaciones
Formato JSON para todo el intercambio de datos
Gestión automática de sesiones con IDs basados en fecha

Herramientas

get_my_profile - Obtén tu perfil usando variables de entorno
- Usa UNOMI_PROFILE_ID del entorno o búsqueda por correo electrónico
- Genera automáticamente un ID de sesión basado en la fecha actual
- Parámetros opcionales:
  - requireSegments: Incluir información de segmentos
  - requireScores: Incluir información de puntuaciones
update_my_profile - Actualiza propiedades de tu perfil
- Usa UNOMI_PROFILE_ID del entorno o búsqueda por correo electrónico
- Toma un objeto de propiedades con pares clave-valor para actualizar
- Soporta valores de tipo 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 requerido
- Devuelve los datos completos del perfil desde Unomi
search_profiles - Busca perfiles
- Toma una cadena de consulta y parámetros opcionales de límite/desplazamiento
- Busca en los campos firstName, lastName y email
create_scope - Crea un nuevo ámbito de Unomi
- Toma un identificador de ámbito y nombre/descripción opcionales
- Requerido para el seguimiento de eventos y actualizaciones de perfil
- Ejemplo:
```
{
  "scope": "my-app",
  "name": "My Application",
  "description": "Scope for my application events"
}
```
get_tenant_info - Obtiene información sobre el tenant actual (solo V3)
- Devuelve detalles del tenant, información de versión y estado clave
- Solo disponible cuando se usa Unomi V3
- No requiere parámetros

Herramientas de Gestión de Consentimiento

update_consent - Actualiza el estado de consentimiento de un usuario usando el evento modifyConsent
- Usa la API de Consentimiento de Apache Unomi como se describe en la documentación oficial
- Parámetros requeridos:
  - consentId: Identificador único del consentimiento
  - status: Estado del consentimiento (GRANTED, DENIED o REVOKED)
- Parámetros opcionales:
  - typeIdentifier: Identificador de tipo del consentimiento
  - scope: Ámbito del consentimiento (por defecto claude-desktop)
  - metadata: Metadatos adicionales para el consentimiento
- Cumplimiento GDPR:
  - Los consentimientos GRANTED expiran después de 1 año (recomendación GDPR)
  - Los consentimientos DENIED/REVOKED expiran inmediatamente
- Ejemplo:
```
{
  "consentId": "marketing-consent",
  "status": "GRANTED",
  "typeIdentifier": "marketing",
  "scope": "claude-desktop",
  "metadata": {
    "source": "claude-desktop",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}
```
get_consent - Obtiene información específica de consentimiento para un perfil
- Toma consentId como parámetro requerido
- Devuelve detalles del consentimiento incluyendo estado, marca de tiempo y metadatos
- Usa tu perfil por defecto (desde el entorno o búsqueda por correo electrónico)
- Ejemplo:
```
{
  "consentId": "marketing-consent"
}
```
list_consents - Lista todos los consentimientos de un perfil con filtrado opcional
- Parámetros opcionales:
  - profileId: ID del perfil para listar consentimientos (usa tu perfil si no se proporciona)
  - status: Filtrar por estado de consentimiento (GRANTED, DENIED o REVOKED)
  - scope: Filtrar por ámbito
- Devuelve una lista filtrada de consentimientos con metadatos
- Ejemplo:
```
{
  "status": "GRANTED",
  "scope": "claude-desktop"
}
```

Gestión de Ámbitos

El servidor gestiona automáticamente los ámbitos por ti:

Ámbito Predeterminado:
- Se usa un ámbito predeterminado claude-desktop para todas las operaciones
- Se crea automáticamente cuando es necesario
- Se usa para actualizaciones de perfil y seguimiento de eventos
Ámbitos Personalizados:
- Se pueden crear usando la herramienta create_scope
- Útiles para separar diferentes aplicaciones o contextos
- Deben existir antes de usarse en operaciones de perfil
Creación Automática de Ámbitos:
- El servidor verifica si los ámbitos requeridos existen
- Los crea automáticamente si faltan
- Usa valores predeterminados significativos para los metadatos del ámbito

Nota: Aunque los ámbitos se crean automáticamente cuando es necesario, aún puedes crearlos manualmente con nombres y descripciones personalizados usando la herramienta create_scope.

Compatibilidad con Apache Unomi V2/V3

Este servidor MCP soporta tanto Apache Unomi V2 como V3 con detección automática de versión y métodos de autenticación apropiados.

Detección de Versión

El servidor detecta automáticamente la versión de Unomi basándose en la variable de entorno UNOMI_VERSION:

UNOMI_VERSION=2 - Usa autenticación V2 (administrador del sistema)
UNOMI_VERSION=3 - Usa autenticación V3 (basada en tenant) - Predeterminado

Autenticación V2 vs V3

V2 (Legado):

Usa autenticación de administrador del sistema (karaf/karaf por defecto)
Todas las operaciones usan el mismo método de autenticación
Requiere UNOMI_USERNAME, UNOMI_PASSWORD y UNOMI_KEY

V3 (Multi-tenant):

Usa autenticación basada en tenant con claves API
Diferente autenticación para diferentes tipos de endpoints:
- Endpoints públicos (/context.json): Usa el encabezado X-Unomi-Api-Key con clave pública
- Endpoints privados (perfiles, ámbitos): Usa autenticación de tenant (tenantId:privateKey)
- Operaciones del sistema: Recurre a la autenticación de administrador del sistema
Requiere UNOMI_TENANT_ID, UNOMI_PUBLIC_KEY y UNOMI_PRIVATE_KEY

Migración de V2 a V3

Actualiza las variables de entorno:

# Remove V2-specific variables
# UNOMI_KEY (no longer needed)

# Add V3-specific variables
UNOMI_VERSION=3
UNOMI_TENANT_ID=your-tenant-id
UNOMI_PUBLIC_KEY=your-public-key
UNOMI_PRIVATE_KEY=your-private-key

Beneficios de V3:
- Aislamiento completo de datos entre tenants
- Seguridad mejorada con claves API específicas de tenant
- Mejor escalabilidad para despliegues multi-tenant
- Cumplimiento mejorado con regulaciones de privacidad de datos

Resumen

Este servidor MCP permite a Claude mantener contexto sobre usuarios a través del sistema de gestión de perfiles de Apache Unomi. Esto es lo que puedes lograr con él:

Capacidades Clave

Reconocimiento de Usuarios:
- Identificar usuarios a través de conversaciones usando correo electrónico o ID de perfil
- Mantener contexto de usuario consistente entre sesiones
- Crear y gestionar perfiles de usuario automáticamente
Gestión de Contexto:
- Almacenar y recuperar preferencias de usuario
- Gestionar preferencias de consentimiento del usuario
- Rastrear estado e historial de consentimiento
Gestión de Consentimiento:
- Actualizar el estado de consentimiento del usuario usando la API de Consentimiento de Apache Unomi
- Recuperar información específica de consentimiento
- Listar y filtrar consentimientos por estado y ámbito
- Manejo automático de expiración de consentimientos (cumplimiento GDPR)
- Soporte para cumplimiento GDPR y privacidad
Características de Integración:
- Integración perfecta con Claude Desktop
- Gestión automática de sesiones
- Aislamiento de contexto basado en ámbitos

Lo Que Puedes Hacer

Hacer que Claude recuerde preferencias de usuario a través de conversaciones
Almacenar y recuperar información específica de usuario
Mantener contexto de usuario consistente
Gestionar múltiples usuarios mediante identificación por correo electrónico
Rastrear y gestionar preferencias de consentimiento del usuario
Cumplir con regulaciones de privacidad (GDPR, CCPA, etc.)
Actualizar el estado de consentimiento en tiempo real
Consultar historial y estado de consentimiento

Requisitos Previos

Servidor Apache Unomi en ejecución
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:

UNOMI_BASE_URL=http://your-unomi-server:8181
UNOMI_USERNAME=your-username
UNOMI_PASSWORD=your-password
UNOMI_PROFILE_ID=your-profile-id
UNOMI_SOURCE_ID=your-source-id
UNOMI_KEY=your-unomi-key
UNOMI_EMAIL=your-email

Resolución de Perfil

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

Búsqueda por Correo Electrónico (si UNOMI_EMAIL está configurado):
- Busca un perfil con el correo electrónico coincidente
- Si se encuentra, usa el ID de ese perfil
- Útil para mantener un perfil consistente entre sesiones
ID de Perfil de Respaldo:
- Si la búsqueda por correo electrónico falla o UNOMI_EMAIL no está configurado
- Usa el UNOMI_PROFILE_ID del entorno
- Asegura que siempre haya un perfil disponible

La respuesta indicará qué método se usó mediante el campo source:

"email_lookup": Perfil encontrado por correo electrónico
"environment": Usando ID de perfil de respaldo

Configuración del Servidor Unomi

Configura 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

Asegúrate de que tu 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:*
```
Reinicia el servidor Unomi para aplicar los cambios

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

Configuración

Variables de Entorno

El servidor requiere las siguientes variables de entorno:

UNOMI_BASE_URL=http://your-unomi-server:8181
UNOMI_USERNAME=your-username
UNOMI_PASSWORD=your-password
UNOMI_PROFILE_ID=your-profile-id
UNOMI_SOURCE_ID=your-source-id
UNOMI_KEY=your-unomi-key
UNOMI_EMAIL=your-email

Resolución de Perfil

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

Búsqueda por Correo Electrónico (si UNOMI_EMAIL está configurado):
- Busca un perfil con el correo electrónico coincidente
- Si se encuentra, usa el ID de ese perfil
- Útil para mantener un perfil consistente entre sesiones
ID de Perfil de Respaldo:
- Si la búsqueda por correo electrónico falla o UNOMI_EMAIL no está configurado
- Usa el UNOMI_PROFILE_ID del entorno
- Asegura que siempre haya un perfil disponible

La respuesta indicará qué método se usó mediante el campo source:

"email_lookup": Perfil encontrado por correo electrónico
"environment": Usando ID de perfil de respaldo

Configuración del Servidor Unomi

Configura 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

Asegúrate de que tu 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:*
```
Reinicia el servidor Unomi para aplicar los cambios

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

Desarrollo

Instala las dependencias:

npm install

Compila el servidor:

npm run build

Para desarrollo con recompilación automática:

npm run watch

Depuración

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

npm run inspector

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

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

# Follow logs in real-time
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

Formato de ID de Sesión

Cuando se usa get_my_profile, el ID de sesión se genera automáticamente usando el formato:

[profileId]-YYYYMMDD

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

user123-20240315

Solución de Problemas

Problemas Comunes

Eventos Protegidos Fallando
- Verifica que la clave de Unomi coincida exactamente en ambas configuraciones
- Comprueba que la dirección IP esté correctamente en la lista blanca
- Asegúrate de que el ámbito exista antes de actualizar propiedades
- Verifica la configuración de CORS si es necesario
Perfil No Encontrado
- Comprueba si UNOMI_EMAIL está configurado correctamente
- Verifica que el formato del correo electrónico sea válido
- Asegúrate de que el perfil exista en Unomi
- Comprueba si el UNOMI_PROFILE_ID de respaldo es válido
Problemas de Sesión
- Recuerda que las sesiones se basan en la fecha
- Solo una sesión por perfil por día
- Comprueba que el formato del ID de sesión coincida con profileId-YYYYMMDD
- Verifica que el ámbito exista para la sesión
Problemas de Conexión
- Verifica que el servidor Unomi esté en ejecución
- Comprueba la conectividad de red
- Asegúrate de que UNOMI_BASE_URL sea correcto
- Verifica las credenciales de autenticación

Registros a Revisar

Registros de Claude Desktop:

# MacOS
~/Library/Logs/Claude/mcp*.log

# Windows
%APPDATA%\Claude\mcp*.log

Registros del Servidor Unomi:

# Usually in
$UNOMI_HOME/logs/karaf.log

Soluciones Rápidas

Restablecer estado:

# Stop Claude Desktop
# Clear logs
rm ~/Library/Logs/Claude/mcp*.log
# Restart Claude Desktop

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

Crea o edita tu configuración de Claude Desktop:
- MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%/Claude/claude_desktop_config.json

Añade 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: Usar NPX garantiza que siempre estés ejecutando la última versión publicada del servidor.

Alternativamente, si quieres usar una versión específica:

{
  "mcpServers": {
    "unomi-server": {
      "command": "npx",
      "args": ["@inoyu/mcp-unomi-server@0.1.0"],
      "env": {
        // ... environment variables ...
      }
    }
  }
}

Para desarrollo o instalaciones locales:

{
  "mcpServers": {
    "unomi-server": {
      "command": "node",
      "args": ["/path/to/local/mcp-unomi-server/build/index.js"],
      "env": {
        // ... environment variables ...
      }
    }
  }
}