Bridging the Gap: Apache Unomi MCP Server for Seamless LLM Context Management

Empower your Large Language Models (LLMs) with persistent user context using the Inoyu Apache Unomi MCP Server. This open-source implementation leverages the Model Context Protocol (MCP) to connect LLMs like Claude with the robust profile management capabilities of Apache Unomi.

Important Considerations: Early Stage Implementation

Please be aware that this is a pre-production implementation intended for demonstration, learning, and experimentation. It is:

• Not Validated for Production: Rigorous testing and hardening are required before deployment in production environments.
• Subject to Change: The API and functionality may evolve as the project matures.
• Unofficially Supported: Community support is available, but formal support channels are not yet established.

Current Functionality

This initial implementation focuses on core profile management features:

• Profile Lookup & Creation: Identify users by email and automatically create profiles if they don't exist.
• Profile Property Management: Store and update user attributes to personalize LLM interactions.
• Basic Session Handling: Track user sessions for context persistence across interactions.
• Scope Management: Isolate context for different applications or use cases.

Note: Advanced Unomi features such as event tracking, segmentation, and scoring are not yet implemented. We encourage community feedback to prioritize future development efforts.

Interactive Demo

See the MCP server in action, enabling Claude to maintain context and manage user profiles:

Quick Start: Installation Guide

Integrate the MCP server with Claude Desktop by modifying the configuration file and setting environment variables:

• MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 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_USERNAME": "your-username", // Default Unomi username: karaf
        "UNOMI_PASSWORD": "your-password", // Default Unomi password: karaf
        "UNOMI_PROFILE_ID": "your-profile-id",
        "UNOMI_KEY": "your-unomi-key", // Default Unomi key: 670c26d1cc413346c3b2fd9ce65dab41
        "UNOMI_EMAIL": "[email protected]",
        "UNOMI_SOURCE_ID": "claude-desktop"
      }
    }
  }
}

Important: Replace the placeholder values with your actual Unomi server credentials and restart Claude Desktop. Verify the server's tools are available by clicking the tools icon in the chat window.

Core Features

Profile Management

• Email-Driven Profile Access: Look up profiles using email addresses, creating new profiles automatically when necessary.
• Comprehensive Profile Data: Access profile properties, segments, and scores in a standardized JSON format.
• Automated Session Management: Simplify session handling with date-based session IDs.

Available Tools

• get_my_profile: Retrieve your profile using environment variables.
  • Leverages UNOMI_PROFILE_ID or email lookup for identification.
  • Generates a session ID based on the current date.
  • Optional parameters: requireSegments and requireScores.
• update_my_profile: Modify profile properties.
  • Identifies the profile using UNOMI_PROFILE_ID or email lookup.
  • Accepts a JSON object containing key-value pairs for updates.
  • 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.
  • Requires the profileId parameter.
  • Returns the complete profile data from Unomi.
• search_profiles: Search for profiles based on various criteria.
  • Accepts a query string and optional limit and offset parameters.
  • Searches across firstName, lastName, and email fields.
• create_scope: Create a new Unomi scope.
  • Requires a scope identifier and optional name and description.
  • Essential for event tracking and profile updates.
  • Example:

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

Streamlined Scope Management

The server automates scope management for ease of use:

1. Default Scope:

   • A default scope named claude-desktop is used for all operations.
   • Created automatically if it doesn't exist.
   • Used for profile updates and event tracking.

2. Custom Scopes:

   • Create custom scopes using the create_scope tool.
   • Ideal for isolating context between different applications.
   • Must exist before being used in profile operations.

3. Automatic Scope Creation:

   • The server proactively checks for required scopes.
   • Creates them automatically with sensible default metadata if missing.

Note: While automatic scope creation simplifies setup, you can still use the create_scope tool to define scopes with custom names and descriptions.

Deep Dive: Understanding the MCP Server

This MCP server empowers Claude to maintain user context by leveraging Apache Unomi's profile management system.

Key Benefits

1. Persistent User Recognition:

   • Identify users across conversations using email or profile ID.
   • Maintain consistent user context between sessions.
   • Automate user profile creation and management.

2. Contextual Awareness:

   • Store and retrieve user preferences and attributes.
   • Personalize LLM interactions based on user context.

3. Seamless Integration:

   • Designed for easy integration with Claude Desktop.
   • Automated session management.
   • Scope-based context isolation.

Use Cases

• Enable Claude to remember user preferences across conversations.
• Store and retrieve user-specific information for personalized responses.
• Maintain consistent user context for more engaging interactions.
• Manage multiple users through email-based identification.

Prerequisites

• A running Apache Unomi server.
• Claude Desktop installation.
• Network connectivity between Claude Desktop and the Unomi server.
• Proper security configuration for Unomi.
• Correctly configured environment variables.

Detailed Configuration

Environment Variables

The server relies on 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 Logic

The server employs a two-step process to determine the profile ID:

1. Email Lookup (if UNOMI_EMAIL is set):

   • Searches for a profile matching the provided email address.
   • If found, uses the profile's ID.
   • Ensures consistent profile association across sessions.

2. Fallback Profile ID:

   • If email lookup fails or UNOMI_EMAIL is not set.
   • Uses the UNOMI_PROFILE_ID from the environment.
   • Guarantees a profile is always available.

The source field in the response indicates the method used:

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

Unomi Server Hardening

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 Proper CORS Configuration 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: Apply the configuration changes.

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

Development Workflow

1. Install Dependencies:

   npm install

2. Build the Server:

   npm run build

3. Development with Auto-Rebuild:

   npm run watch

Debugging Techniques

Debugging MCP servers can be challenging due to stdio communication. We recommend using the MCP Inspector:

npm run inspector

The Inspector provides a browser-based debugging interface.

You can also monitor Claude Desktop logs for MCP requests and responses:

# Real-time log monitoring
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

Session ID Format

The get_my_profile tool automatically generates session IDs using the following format:

[profileId]-YYYYMMDD

Example: For profile ID "user123" on March 15, 2024, the session ID would be:

user123-20240315

Troubleshooting Guide

Common Issues and Solutions

1. Protected Events Failing:

   • Verify the Unomi key matches in all configurations.
   • Ensure the IP address is correctly whitelisted in Unomi.
   • Confirm the scope exists before updating properties.
   • Check CORS configuration if necessary.

2. Profile Not Found:

   • Verify UNOMI_EMAIL is correctly set.
   • Ensure the email format is valid.
   • Confirm the profile exists in Unomi.
   • Check the fallback UNOMI_PROFILE_ID is valid.

3. Session Issues:

   • Remember sessions are date-based.
   • Only one session per profile per day is allowed.
   • Check the session ID format: profileId-YYYYMMDD.
   • Verify the scope exists for the session.

4. Connection Problems:

   • Verify the Unomi server is running.
   • Check network connectivity.
   • Ensure UNOMI_BASE_URL is correct.
   • Verify authentication credentials.

Log Files for Diagnosis

1. Claude Desktop Logs:

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

2. Unomi Server Logs:

   # Typically located 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. Locate or Create the Configuration File:

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

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": "[email protected]",
           "UNOMI_SOURCE_ID": "claude-desktop"
         }
       }
     }
   }

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

Alternatively, specify a specific version:

{
  "mcpServers": {
    "unomi-server": {
      "command": "npx",
      "args": ["@inoyu/[email protected]"],
      "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 ...
      }
    }
  }
}