MCP HubMCP Hub
sergehuber

inoyu-mcp-unomi-server

by: sergehuber

An implementation of Anthropic's Model Context Protocol for the Apache Unomi CDP

4created 01/12/2024
Visit
Anthropic
Unomi

📌Overview

Purpose: This MCP server facilitates user context management for Claude by utilizing Apache Unomi's profile management capabilities.

Overview: The Inoyu Apache Unomi MCP Server serves as a Model Context Protocol server that enables Claude to maintain user context through profile management. It allows for the lookup, creation, and manipulation of user profiles, all while managing user sessions and context within defined scopes. This implementation is intended for educational and experimental purposes.

Key Features:

  • Profile Access: Enables email-based profile creation and lookup, ensuring user profiles are managed effectively and automatically, complete with session management and JSON data exchange.

  • Context Management: Facilitates the storage and retrieval of user preferences, leading to a personalized experience across user interactions with Claude.

  • Scope Management: Automatically handles scope creation and management, isolating context for different applications or user groups for improved data organization and flow.

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 is welcome on future development priorities.

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_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"
      }
    }
  }
}

Replace the values with your actual Unomi server details. Restart Claude Desktop after updating the configuration. You can then click on the tools icon on the lower right of the chat window to verify tool availability.

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

    • Uses UNOMI_PROFILE_ID from environment or email lookup
    • Generates a session ID based on the current date
    • Optional parameters: requireSegments, requireScores

  • update_my_profile

    • Updates properties of your profile
    • 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

  • search_profiles

    • Search profiles by query string with optional limit/offset

  • create_scope

    • Create a new Unomi scope
    • Example: 
      {
  "scope": "my-app",
  "name": "My Application",
  "description": "Scope for my application events"
}

Scope Management

  • Default scope claude-desktop is used and created automatically for operations
  • Custom scopes can be created using create_scope
  • Server checks and creates missing scopes automatically with defaults

Note: Scopes can be created manually with custom names/descriptions.

Overview

This MCP server enables Claude to maintain context about users via Apache Unomi's profile management.

Key Capabilities

  • User Recognition: Identify users by email or profile ID, maintain consistent context and manage profiles automatically
  • Context Management: Store and retrieve user preferences
  • Integration Features: Claude Desktop integration, automatic session management, scope-based context isolation

What You Can Do

  • Have Claude remember user preferences across conversations
  • Store and retrieve user-specific information
  • Maintain consistent user context
  • Manage multiple users by email

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 these 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

  1. Email Lookup (UNOMI_EMAIL set):

    • Searches for profile by email, uses profile ID if found.

  2. Fallback Profile ID:

    • Uses UNOMI_PROFILE_ID if email lookup fails or is not set.

Response includes source field:

  • "email_lookup": Profile found by email
  • "environment": Fallback profile ID used

Unomi Server Configuration

  1. Configure protected events in etc/org.apache.unomi.cluster.cfg:

    org.apache.unomi.cluster.authorization.key=your-unomi-key
org.apache.unomi.ip.ranges=127.0.0.1,::1,your-claude-desktop-ip

  2. Configure CORS in etc/org.apache.unomi.cors.cfg:

    org.apache.unomi.cors.allowed.origins=http://localhost:*

  3. Restart Unomi server to apply changes.

Important: The Unomi key must exactly match between server configuration and UNOMI_KEY environment variable.

Development

Install dependencies:

npm install

Build the server:

npm run build

For development with auto-rebuild:

npm run watch

Debugging

Use the MCP Inspector tool:

npm run inspector

This starts a debugging interface accessible from your browser.

You can also tail Claude Desktop logs:

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

Session ID Format

Session ID format when using get_my_profile:

[profileId]-YYYYMMDD

Example: user123-20240315

Troubleshooting

Common Issues

  • Protected Events Failing: Verify Unomi key, IP whitelist, scope existence, CORS settings
  • Profile Not Found: Check UNOMI_EMAIL is set and valid, profile existence, fallback ID validity
  • Session Issues: Sessions are date-based, one per profile per day, verify session ID format and scope existence
  • Connection Problems: Verify Unomi server is running, network connectivity, correct URL, authentication

Logs to Check

  • Claude Desktop logs (MacOS): ~/Library/Logs/Claude/mcp*.log
  • Unomi server logs: $UNOMI_HOME/logs/karaf.log

Quick Fixes

  • Reset State:

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

  • Verify Configuration:

    curl -u username:password http://your-unomi-server:8181/cxs/cluster
curl -u username:password http://your-unomi-server:8181/cxs/scopes/claude-desktop

Claude Desktop Configuration Options

  1. Edit your Claude Desktop config:

    • 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": "your-email@example.com",
        "UNOMI_SOURCE_ID": "claude-desktop"
      }
    }
  }
}

Note: Using NPX ensures running latest published server version.

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 installation:

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

End of Document