Inoyu Apache Unomi

Mantém o contexto do usuário e gerencia perfis usando a plataforma de dados do cliente Apache Unomi.

Documentação

Inoyu Apache Unomi MCP Server

Um servidor Model Context Protocol que permite ao Claude manter o contexto do usuário por meio do gerenciamento de perfis do Apache Unomi.

⚠️ Aviso de Implementação Inicial

Esta é uma implementação inicial destinada a fins de demonstração:

Não validada para uso em produção

Sujeita a alterações

Não suportada oficialmente (ainda)

Apenas para aprendizado e experimentação

Escopo Atual

Esta implementação fornece:

Consulta e criação de perfis usando e-mail
Gerenciamento de propriedades de perfil
Tratamento básico de sessões
Gerenciamento de escopo para isolamento de contexto

Outros recursos do Unomi (eventos, segmentos, propriedades de sessão, etc.) não estão implementados atualmente. O feedback da comunidade é bem-vindo sobre prioridades de desenvolvimento futuro.

Demonstração

Assista como o servidor MCP permite ao Claude manter o contexto e gerenciar perfis de usuários:

Instalação

Para usar com o Claude Desktop, adicione a configuração do servidor e as variáveis de ambiente:

No MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json No 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
      }
    }
  }
}

A seção env na configuração permite definir as variáveis de ambiente necessárias para o servidor. Substitua os valores pelos dados reais do seu servidor Unomi.

Certifique-se de reiniciar o Claude Desktop após atualizar a configuração. Você pode então clicar no ícone de ferramentas no canto inferior direito da janela de chat para confirmar que todas as ferramentas fornecidas por este servidor foram encontradas.

Recursos

Acesso ao Perfil

Consulta de perfil baseada em e-mail com criação automática
Acesso a propriedades de perfil, segmentos e pontuações
Formato JSON para todas as trocas de dados
Gerenciamento automático de sessão com IDs baseados em data

Ferramentas

get_my_profile - Obtenha seu perfil usando variáveis de ambiente
- Usa UNOMI_PROFILE_ID do ambiente ou consulta por e-mail
- Gera automaticamente um ID de sessão baseado na data atual
- Parâmetros opcionais:
  - requireSegments: Incluir informações de segmento
  - requireScores: Incluir informações de pontuação
update_my_profile - Atualize propriedades do seu perfil
- Usa UNOMI_PROFILE_ID do ambiente ou consulta por e-mail
- Aceita um objeto de propriedades com pares chave-valor para atualizar
- Suporta valores string, número, booleano e nulo
- Exemplo:
```
{
  "properties": {
    "firstName": "John",
    "age": 30,
    "isSubscribed": true,
    "oldProperty": null
  }
}
```
get_profile - Recupere um perfil específico por ID
- Aceita profileId como parâmetro obrigatório
- Retorna os dados completos do perfil do Unomi
search_profiles - Pesquise perfis
- Aceita string de consulta e parâmetros opcionais de limite/deslocamento
- Pesquisa nos campos firstName, lastName e email
create_scope - Crie um novo escopo no Unomi
- Aceita identificador de escopo e nome/descrição opcionais
- Necessário para rastreamento de eventos e atualizações de perfil
- Exemplo:
```
{
  "scope": "my-app",
  "name": "My Application",
  "description": "Scope for my application events"
}
```
get_tenant_info - Obtenha informações sobre o tenant atual (somente V3)
- Retorna detalhes do tenant, informações de versão e status da chave
- Disponível apenas ao usar Unomi V3
- Nenhum parâmetro necessário

Ferramentas de Gerenciamento de Consentimento

update_consent - Atualize o status de consentimento de um usuário usando o evento modifyConsent
- Usa a API de Consentimento do Apache Unomi conforme descrito na documentação oficial
- Parâmetros obrigatórios:
  - consentId: Identificador único do consentimento
  - status: Status do consentimento (GRANTED, DENIED ou REVOKED)
- Parâmetros opcionais:
  - typeIdentifier: Identificador do tipo de consentimento
  - scope: Escopo do consentimento (padrão: claude-desktop)
  - metadata: Metadados adicionais do consentimento
- Conformidade com GDPR:
  - Consentimentos GRANTED expiram após 1 ano (recomendação GDPR)
  - Consentimentos DENIED/REVOKED expiram imediatamente
- Exemplo:
```
{
  "consentId": "marketing-consent",
  "status": "GRANTED",
  "typeIdentifier": "marketing",
  "scope": "claude-desktop",
  "metadata": {
    "source": "claude-desktop",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}
```
get_consent - Obtenha informações específicas de consentimento para um perfil
- Aceita consentId como parâmetro obrigatório
- Retorna detalhes do consentimento, incluindo status, timestamp e metadados
- Usa seu perfil por padrão (do ambiente ou consulta por e-mail)
- Exemplo:
```
{
  "consentId": "marketing-consent"
}
```
list_consents - Liste todos os consentimentos de um perfil com filtragem opcional
- Parâmetros opcionais:
  - profileId: ID do perfil para listar consentimentos (usa seu perfil se não fornecido)
  - status: Filtrar por status de consentimento (GRANTED, DENIED ou REVOKED)
  - scope: Filtrar por escopo
- Retorna lista filtrada de consentimentos com metadados
- Exemplo:
```
{
  "status": "GRANTED",
  "scope": "claude-desktop"
}
```

Gerenciamento de Escopo

O servidor gerencia escopos automaticamente para você:

Escopo Padrão:
- Um escopo padrão claude-desktop é usado para todas as operações
- Criado automaticamente quando necessário
- Usado para atualizações de perfil e rastreamento de eventos
Escopos Personalizados:
- Podem ser criados usando a ferramenta create_scope
- Úteis para separar diferentes aplicações ou contextos
- Devem existir antes de serem usados em operações de perfil
Criação Automática de Escopo:
- O servidor verifica se os escopos necessários existem
- Cria-os automaticamente se estiverem ausentes
- Usa padrões significativos para metadados de escopo

Nota: Embora os escopos sejam criados automaticamente quando necessário, você ainda pode criá-los manualmente com nomes e descrições personalizados usando a ferramenta create_scope.

Compatibilidade Apache Unomi V2/V3

Este servidor MCP suporta Apache Unomi V2 e V3 com detecção automática de versão e métodos de autenticação apropriados.

Detecção de Versão

O servidor detecta automaticamente a versão do Unomi com base na variável de ambiente UNOMI_VERSION:

UNOMI_VERSION=2 - Usa autenticação V2 (administrador do sistema)
UNOMI_VERSION=3 - Usa autenticação V3 (baseada em tenant) - Padrão

Autenticação V2 vs V3

V2 (Legado):

Usa autenticação de administrador do sistema (karaf/karaf por padrão)
Todas as operações usam o mesmo método de autenticação
Requer UNOMI_USERNAME, UNOMI_PASSWORD e UNOMI_KEY

V3 (Multi-tenant):

Usa autenticação baseada em tenant com chaves de API
Autenticação diferente para diferentes tipos de endpoint:
- Endpoints públicos (/context.json): Usa cabeçalho X-Unomi-Api-Key com chave pública
- Endpoints privados (perfis, escopos): Usa autenticação de tenant (tenantId:privateKey)
- Operações de sistema: Usa autenticação de administrador do sistema como fallback
Requer UNOMI_TENANT_ID, UNOMI_PUBLIC_KEY e UNOMI_PRIVATE_KEY

Migração de V2 para V3

Atualize as variáveis de ambiente:

# 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

Benefícios do V3:
- Isolamento completo de dados entre tenants
- Segurança aprimorada com chaves de API específicas por tenant
- Melhor escalabilidade para implantações multi-tenant
- Conformidade aprimorada com regulamentações de privacidade de dados

Visão Geral

Este servidor MCP permite ao Claude manter contexto sobre usuários por meio do sistema de gerenciamento de perfis do Apache Unomi. Aqui está o que você pode alcançar com ele:

Principais Capacidades

Reconhecimento de Usuário:
- Identifique usuários em conversas usando e-mail ou ID de perfil
- Mantenha contexto consistente do usuário entre sessões
- Crie e gerencie perfis de usuário automaticamente
Gerenciamento de Contexto:
- Armazene e recupere preferências do usuário
- Gerencie preferências de consentimento do usuário
- Acompanhe status e histórico de consentimento
Gerenciamento de Consentimento:
- Atualize o status de consentimento do usuário usando a API de Consentimento do Apache Unomi
- Recupere informações específicas de consentimento
- Liste e filtre consentimentos por status e escopo
- Tratamento automático de expiração de consentimento (conforme GDPR)
- Suporte para conformidade com GDPR e privacidade
Recursos de Integração:
- Integração perfeita com Claude Desktop
- Gerenciamento automático de sessão
- Isolamento de contexto baseado em escopo

O Que Você Pode Fazer

Fazer o Claude lembrar preferências do usuário entre conversas
Armazenar e recuperar informações específicas do usuário
Manter contexto consistente do usuário
Gerenciar múltiplos usuários por identificação por e-mail
Acompanhar e gerenciar preferências de consentimento do usuário
Cumprir regulamentações de privacidade (GDPR, CCPA, etc.)
Atualizar status de consentimento em tempo real
Consultar histórico e status de consentimento

Pré-requisitos

Servidor Apache Unomi em execução
Instalação do Claude Desktop
Acesso de rede ao servidor Unomi
Configuração de segurança adequada
Variáveis de ambiente necessárias

Configuração

Variáveis de Ambiente

O servidor requer as seguintes variáveis de ambiente:

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

Resolução de Perfil

O servidor usa um processo de duas etapas para resolver o ID do perfil:

Consulta por E-mail (se UNOMI_EMAIL estiver definido):
- Pesquisa um perfil com e-mail correspondente
- Se encontrado, usa o ID desse perfil
- Útil para manter perfil consistente entre sessões
ID de Perfil Alternativo:
- Se a consulta por e-mail falhar ou UNOMI_EMAIL não estiver definido
- Usa o UNOMI_PROFILE_ID do ambiente
- Garante que um perfil esteja sempre disponível

A resposta indicará qual método foi usado por meio do campo source:

"email_lookup": Perfil encontrado via e-mail
"environment": Usando ID de perfil alternativo

Configuração do Servidor Unomi

Configure eventos protegidos em 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

Certifique-se de que seu servidor Unomi tenha CORS configurado corretamente em etc/org.apache.unomi.cors.cfg:
```
# Add your Claude Desktop origin if needed
org.apache.unomi.cors.allowed.origins=http://localhost:*
```
Reinicie o servidor Unomi para aplicar as alterações

Importante: A chave Unomi deve corresponder exatamente entre a configuração do seu servidor e a variável de ambiente UNOMI_KEY no Claude Desktop.

Configuração

Variáveis de Ambiente

O servidor requer as seguintes variáveis de ambiente:

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

Resolução de Perfil

O servidor usa um processo de duas etapas para resolver o ID do perfil:

Consulta por E-mail (se UNOMI_EMAIL estiver definido):
- Pesquisa um perfil com e-mail correspondente
- Se encontrado, usa o ID desse perfil
- Útil para manter perfil consistente entre sessões
ID de Perfil Alternativo:
- Se a consulta por e-mail falhar ou UNOMI_EMAIL não estiver definido
- Usa o UNOMI_PROFILE_ID do ambiente
- Garante que um perfil esteja sempre disponível

A resposta indicará qual método foi usado por meio do campo source:

"email_lookup": Perfil encontrado via e-mail
"environment": Usando ID de perfil alternativo

Configuração do Servidor Unomi

Configure eventos protegidos em 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

Certifique-se de que seu servidor Unomi tenha CORS configurado corretamente em etc/org.apache.unomi.cors.cfg:
```
# Add your Claude Desktop origin if needed
org.apache.unomi.cors.allowed.origins=http://localhost:*
```
Reinicie o servidor Unomi para aplicar as alterações

Importante: A chave Unomi deve corresponder exatamente entre a configuração do seu servidor e a variável de ambiente UNOMI_KEY no Claude Desktop.

Desenvolvimento

Instale as dependências:

npm install

Compile o servidor:

npm run build

Para desenvolvimento com recompilação automática:

npm run watch

Depuração

Como os servidores MCP se comunicam via stdio, a depuração pode ser desafiadora. Recomendamos usar o MCP Inspector, que está disponível como script de pacote:

npm run inspector

O Inspector fornecerá uma URL para acessar ferramentas de depuração no seu navegador.

Você também pode acompanhar os logs do Claude Desktop para ver solicitações e respostas MCP:

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

Formato do ID de Sessão

Ao usar get_my_profile, o ID de sessão é gerado automaticamente usando o formato:

[profileId]-YYYYMMDD

Por exemplo, se seu ID de perfil for "user123" e hoje for 15 de março de 2024, o ID de sessão seria:

user123-20240315

Solução de Problemas

Problemas Comuns

Falha em Eventos Protegidos
- Verifique se a chave Unomi corresponde exatamente em ambas as configurações
- Verifique se o endereço IP está corretamente na lista de permissões
- Certifique-se de que o escopo exista antes de atualizar propriedades
- Verifique a configuração de CORS, se necessário
Perfil Não Encontrado
- Verifique se UNOMI_EMAIL está definido corretamente
- Verifique se o formato do e-mail é válido
- Certifique-se de que o perfil exista no Unomi
- Verifique se o UNOMI_PROFILE_ID alternativo é válido
Problemas de Sessão
- Lembre-se de que as sessões são baseadas em data
- Apenas uma sessão por perfil por dia
- Verifique se o formato do ID de sessão corresponde a profileId-YYYYMMDD
- Verifique se o escopo existe para a sessão
Problemas de Conexão
- Verifique se o servidor Unomi está em execução
- Verifique a conectividade de rede
- Certifique-se de que UNOMI_BASE_URL está correto
- Verifique as credenciais de autenticação

Logs para Verificar

Logs do Claude Desktop:

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

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

Logs do Servidor Unomi:

# Usually in
$UNOMI_HOME/logs/karaf.log

Correções Rápidas

Redefinir Estado:

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

Verificar Configuração:

# 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

Opções de configuração do Claude Desktop

Crie ou edite sua configuração do Claude Desktop:
- MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%/Claude/claude_desktop_config.json

Adicione a configuração do 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 garante que você esteja sempre executando a versão publicada mais recente do servidor.

Alternativamente, se você quiser usar uma versão específica:

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

Para instalações de desenvolvimento ou locais:

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