Inoyu Apache Unomi MCP Server

A Model Context Protocol server enabling Claude to maintain user context through Apache Unomi profile management.

> ⚠️ Early Implementation Notice

>

> This is an early implementation intended for demonstration purposes:

> - Not validated for production use

> - Subject to changes

> - Not (yet) officially supported

> - For learning and experimentation only

Current Scope

This implementation provides:

• Profile lookup and creation using email
• Profile property management
• Basic session handling
• Scope management for context isolation

Other Unomi features (events, segments, session properties, etc.) are not currently implemented. Community feedback welcome on future development priorities.

Demo

Watch how the MCP server enables Claude to maintain context and manage user profiles:

Installation

To use with Claude Desktop, add the server config and environment variables:

On MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

On 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
      }
    }
  }
}

The `env` section in the configuration allows you to set the required environment variables for the server. Replace the values with your actual Unomi server details.

Make sure to restart Claude Desktop after updating the configuration. You can then click on the tools icon on the lower right of the chat window to make sure it has found all the tools provided by this server.

Features

Profile Access

• Email-based profile lookup with automatic creation
• Profile properties, segments, and scores access
• JSON format for all data exchange
• Automatic session management with date-based IDs

Tools

• `get_my_profile` - Get your profile using environment variables
  • Uses UNOMI_PROFILE_ID from environment or email lookup
  • Automatically generates a session ID based on the current date
  • Optional parameters:
    • requireSegments: Include segment information
    • requireScores: Include scoring information
• `update_my_profile` - Update properties of your profile
  • Uses UNOMI_PROFILE_ID from environment or email lookup
  • Takes a properties object with key-value pairs to update
  • Supports string, number, boolean, and null values
  • Example:

{
      "properties": {
        "firstName": "John",
        "age": 30,
        "isSubscribed": true,
        "oldProperty": null
      }
    }

• `get_profile` - Retrieve a specific profile by ID
  • Takes profileId as required parameter
  • Returns full profile data from Unomi
• `search_profiles` - Search for profiles
  • Takes query string and optional limit/offset parameters
  • Searches across firstName, lastName, and email fields
• `create_scope` - Create a new Unomi scope
  • Takes scope identifier and optional name/description
  • Required for event tracking and profile updates
  • Example:

{
      "scope": "my-app",
      "name": "My Application",
      "description": "Scope for my application events"
    }

• `get_tenant_info` - Get information about the current tenant (V3 only)
  • Returns tenant details, version information, and key status
  • Only available when using Unomi V3
  • No parameters required

Consent Management Tools

• `update_consent` - Update a user's consent status using the modifyConsent event
  • Uses the Apache Unomi Consent API as described in the official documentation
  • Required parameters:
    • consentId: Unique identifier for the consent
    • status: Consent status (GRANTED, DENIED, or REVOKED)
  • Optional parameters:
    • typeIdentifier: Type identifier of the consent
    • scope: Scope for the consent (defaults to claude-desktop)
    • metadata: Additional metadata for the consent
  • GDPR Compliance:
    • GRANTED consents expire after 1 year (GDPR recommendation)
    • DENIED/REVOKED consents expire immediately
  • Example:

{
      "consentId": "marketing-consent",
      "status": "GRANTED",
      "typeIdentifier": "marketing",
      "scope": "claude-desktop",
      "metadata": {
        "source": "claude-desktop",
        "timestamp": "2024-01-15T10:30:00Z"
      }
    }

• `get_consent` - Get specific consent information for a profile
  • Takes consentId as required parameter
  • Returns consent details including status, timestamp, and metadata
  • Uses your profile by default (from environment or email lookup)
  • Example:

{
      "consentId": "marketing-consent"
    }

• `list_consents` - List all consents for a profile with optional filtering
  • Optional parameters:
    • profileId: Profile ID to list consents for (uses your profile if not provided)
    • status: Filter by consent status (GRANTED, DENIED, or REVOKED)
    • scope: Filter by scope
  • Returns filtered list of consents with metadata
  • Example:

{
      "status": "GRANTED",
      "scope": "claude-desktop"
    }

Scope Management

The server automatically manages scopes for you:

1. Default Scope:

2. Custom Scopes:

3. Automatic Scope Creation:

> Note: While scopes are created automatically when needed, you can still create them manually with custom names and descriptions using the `create_scope` tool.

Apache Unomi V2/V3 Compatibility

This MCP server supports both Apache Unomi V2 and V3 with automatic version detection and appropriate authentication methods.

Version Detection

The server automatically detects the Unomi version based on the `UNOMI_VERSION` environment variable:

• `UNOMI_VERSION=2` - Uses V2 authentication (system administrator)
• `UNOMI_VERSION=3` - Uses V3 authentication (tenant-based) - Default

V2 vs V3 Authentication

V2 (Legacy):

• Uses system administrator authentication (`karaf/karaf` by default)
• All operations use the same authentication method
• Requires `UNOMI_USERNAME`, `UNOMI_PASSWORD`, and `UNOMI_KEY`

V3 (Multi-tenant):

• Uses tenant-based authentication with API keys
• Different authentication for different endpoint types:
  • Public endpoints (`/context.json`): Uses `X-Unomi-Api-Key` header with public key
  • Private endpoints (profiles, scopes): Uses tenant authentication (`tenantId:privateKey`)
  • System operations: Falls back to system administrator authentication
• Requires `UNOMI_TENANT_ID`, `UNOMI_PUBLIC_KEY`, and `UNOMI_PRIVATE_KEY`

Migration from V2 to V3

1. Update environment variables:

# 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

2. Benefits of V3:

Overview

This MCP server enables Claude to maintain context about users through Apache Unomi's profile management system. Here's what you can achieve with it:

Key Capabilities

1. User Recognition:

2. Context Management:

3. Consent Management:

4. Integration Features:

What You Can Do

• Have Claude remember user preferences across conversations
• Store and retrieve user-specific information
• Maintain consistent user context
• Manage multiple users through email identification
• Track and manage user consent preferences
• Comply with privacy regulations (GDPR, CCPA, etc.)
• Update consent status in real-time
• Query consent history and status

Prerequisites

• Running Apache Unomi server
• Claude Desktop installation
• Network access to Unomi server
• Proper security configuration
• Required environment variables

Configuration

Environment Variables

The server requires the following environment variables:

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

Profile Resolution

The server uses a two-step process to resolve the profile ID:

1. Email Lookup (if `UNOMI_EMAIL` is set):

2. Fallback Profile ID:

The response will indicate which method was used via the `source` field:

• `"email_lookup"`: Profile found via email
• `"environment"`: Using fallback profile ID

Unomi Server Configuration

1. Configure protected events in `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. Ensure your Unomi server has CORS properly configured in `etc/org.apache.unomi.cors.cfg`:

# Add your Claude Desktop origin if needed
   org.apache.unomi.cors.allowed.origins=http://localhost:*

3. Restart Unomi server to apply changes

> Important: The Unomi key must match exactly between your server configuration and the UNOMI_KEY environment variable in Claude Desktop.

Configuration

Environment Variables

The server requires the following environment variables:

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

Profile Resolution

The server uses a two-step process to resolve the profile ID:

1. Email Lookup (if `UNOMI_EMAIL` is set):

2. Fallback Profile ID:

The response will indicate which method was used via the `source` field:

• `"email_lookup"`: Profile found via email
• `"environment"`: Using fallback profile ID

Unomi Server Configuration

1. Configure protected events in `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. Ensure your Unomi server has CORS properly configured in `etc/org.apache.unomi.cors.cfg`:

# Add your Claude Desktop origin if needed
   org.apache.unomi.cors.allowed.origins=http://localhost:*

3. Restart Unomi server to apply changes

> Important: The Unomi key must match exactly between your server configuration and the UNOMI_KEY environment variable in Claude Desktop.

Development

Install dependencies:

npm install

Build the server:

npm run build

For development with auto-rebuild:

npm run watch

Debugging

Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the MCP Inspector, which is available as a package script:

npm run inspector

The Inspector will provide a URL to access debugging tools in your browser.

You can also tail the Claude Desktop logs to see MCP requests and responses:

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

Session ID Format

When using `get_my_profile`, the session ID is automatically generated using the format:

[profileId]-YYYYMMDD

For example, if your profile ID is "user123" and today is March 15, 2024, the session ID would be:

user123-20240315

Troubleshooting

Common Issues

1. Protected Events Failing

2. Profile Not Found

3. Session Issues

4. Connection Problems

Logs to Check

1. Claude Desktop Logs:

# MacOS
   ~/Library/Logs/Claude/mcp*.log
   
   # Windows
   %APPDATA%\Claude\mcp*.log

2. Unomi Server Logs:

# Usually in
   $UNOMI_HOME/logs/karaf.log

Quick Fixes

1. Reset State:

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

2. Verify Configuration:

# 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

Claude Desktop Configuration options

1. Create or edit your Claude Desktop configuration:

2. Add the server configuration using 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"
         }
       }
     }
   }

> Note: Using NPX ensures you're always running the latest published version of the server.

Alternatively, if you want to use a specific version:

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

For development or local installations:

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