Inoyu Apache Unomi MCP Server

Inoyu Apache Unomi MCP 服务

一个模型上下文协议服务，使 Claude 能够通过 Apache Unomi 配置文件管理来维护用户上下文。

⚠️ 早期实现说明

此实现处于早期阶段，仅供演示：

• 尚未经过生产环境验证
• 可能会发生变化
• 尚未获得官方支持
• 仅供学习和实验

当前范围

此实现提供：

• 使用电子邮件查找和创建配置文件
• 配置文件属性管理
• 基本会话处理
• 用于隔离上下文的范围管理

目前尚未实现 Unomi 的其他功能（事件、细分、会话属性等）。欢迎社区反馈后续开发优先事项。

演示

观看 MCP 服务如何帮助 Claude 维护上下文并管理用户配置文件：

安装

要与 Claude Desktop 一起使用，请添加服务配置和环境变量：

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

配置中的 env 部分允许你为服务设置所需的环境变量。请将值替换为实际的 Unomi 服务详情。

更新配置后，请务必重启 Claude Desktop。然后，你可以点击聊天窗口右下角的工具图标，确认它已找到此服务提供的所有工具。

功能

配置文件访问

• 基于电子邮件查找配置文件，并在必要时自动创建
• 访问配置文件属性、细分和评分
• 所有数据交换均采用 JSON 格式
• 使用基于日期的 ID 自动管理会话

工具

• get_my_profile - 使用环境变量获取你的配置文件
  • 使用环境变量中的 UNOMI_PROFILE_ID，或通过电子邮件查找
  • 根据当前日期自动生成会话 ID
  • 可选参数：
    • requireSegments：包含细分信息
    • requireScores：包含评分信息
• update_my_profile - 更新你的配置文件属性
  • 使用环境变量中的 UNOMI_PROFILE_ID，或通过电子邮件查找
  • 接收一个包含待更新键值对的属性对象
  • 支持字符串、数字、布尔值和 null 值
  • 示例：

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

• get_profile - 根据 ID 获取指定配置文件
  • 将 profileId 作为必需参数
  • 返回来自 Unomi 的完整配置文件数据
• search_profiles - 搜索配置文件
  • 接收查询字符串以及可选的 limit/offset 参数
  • 在 firstName、lastName 和 email 字段中搜索
• create_scope - 创建新的 Unomi 范围
  • 接收范围标识符以及可选的名称/描述
  • 事件跟踪和配置文件更新必需
  • 示例：

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

• get_tenant_info - 获取当前租户的信息（仅限 V3）
  • 返回租户详情、版本信息和密钥状态
  • 仅在使用 Unomi V3 时可用
  • 无需参数

同意管理工具

• update_consent - 使用 modifyConsent 事件更新用户的同意状态

  • 使用 Apache Unomi Consent API，具体说明请参阅官方文档
  • 必需参数：
    • consentId：同意的唯一标识符
    • status：同意状态（GRANTED、DENIED 或 REVOKED）
  • 可选参数：
    • typeIdentifier：同意的类型标识符
    • scope：同意的作用域（默认为 claude-desktop）
    • metadata：同意的其他元数据
  • GDPR 合规性：
    • GRANTED 状态的同意在 1 年后过期（GDPR 建议）
    • DENIED/REVOKED 状态的同意会立即过期
  • 示例：

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

• get_consent - 获取个人资料的特定同意信息

  • 必需参数为 consentId
  • 返回同意详情，包括状态、时间戳和元数据
  • 默认使用你的个人资料（通过环境变量或电子邮件查询获取）
  • 示例：

    {
      "consentId": "marketing-consent"
    }
    

• list_consents - 列出个人资料的所有同意，并支持可选筛选

  • 可选参数：
    • profileId：要列出同意的个人资料 ID（未提供时使用你的个人资料）
    • status：按同意状态筛选（GRANTED、DENIED 或 REVOKED）
    • scope：按作用域筛选
  • 返回经过筛选且包含元数据的同意列表
  • 示例：

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

作用域管理

服务会自动为你管理作用域：

1. 默认作用域：

   • 所有操作均使用默认作用域 claude-desktop
   • 需要时自动创建
   • 用于个人资料更新和事件跟踪

2. 自定义作用域：

   • 可使用 create_scope 工具创建
   • 适用于区分不同应用或上下文
   • 用于个人资料操作前必须先创建

3. 自动创建作用域：

   • 服务会检查所需作用域是否存在
   • 如果不存在，则自动创建
   • 使用有意义的默认作用域元数据

注意：虽然需要时会自动创建作用域，但你仍可使用 create_scope 工具手动创建带有自定义名称和描述的作用域。

Apache Unomi V2/V3 兼容性

此 MCP 服务同时支持 Apache Unomi V2 和 V3，并可自动检测版本并使用相应的身份验证方法。

版本检测

服务会根据 UNOMI_VERSION 环境变量自动检测 Unomi 版本：

• UNOMI_VERSION=2 - 使用 V2 身份验证（系统管理员）
• UNOMI_VERSION=3 - 使用 V3 身份验证（基于租户）——默认

V2 与 V3 身份验证

V2（旧版）：

• 使用系统管理员身份验证（默认使用 karaf/karaf）
• 所有操作均使用相同的身份验证方法
• 需要 UNOMI_USERNAME、UNOMI_PASSWORD 和 UNOMI_KEY

V3（多租户）：

• 使用基于租户的身份验证和 API 密钥
• 不同类型的端点使用不同的身份验证方式：
  • 公共端点（/context.json）：使用包含公钥的 X-Unomi-Api-Key 标头
  • 私有端点（个人资料、作用域）：使用租户身份验证（tenantId:privateKey）
  • 系统操作：回退到系统管理员身份验证
• 需要 UNOMI_TENANT_ID、UNOMI_PUBLIC_KEY 和 UNOMI_PRIVATE_KEY

从 V2 迁移到 V3

1. 更新环境变量：

   # 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. V3 的优势：

   • 租户之间实现完整的数据隔离
   • 使用租户专属 API 密钥增强安全性
   • 更适合多租户部署，扩展性更强
   • 更符合数据隐私法规

概述

此 MCP 服务通过 Apache Unomi 的用户档案管理系统，帮助 Claude 保持用户上下文。借助它，你可以实现以下功能：

核心功能

1. 用户识别：

   • 使用电子邮件或用户档案 ID 跨对话识别用户
   • 在不同会话之间保持一致的用户上下文
   • 自动创建和管理用户档案

2. 上下文管理：

   • 存储和检索用户偏好
   • 管理用户同意偏好
   • 跟踪同意状态和历史记录

3. 同意管理：

   • 使用 Apache Unomi 的 Consent API 更新用户同意状态
   • 检索特定的同意信息
   • 按状态和范围列出并筛选同意记录
   • 自动处理同意过期（符合 GDPR 要求）
   • 支持 GDPR 和隐私合规

4. 集成功能：

   • 与 Claude Desktop 无缝集成
   • 自动管理会话
   • 基于范围隔离上下文

你可以实现的功能

• 让 Claude 在不同对话之间记住用户偏好
• 存储和检索特定用户的信息
• 保持一致的用户上下文
• 通过电子邮件识别管理多个用户
• 跟踪和管理用户同意偏好
• 遵守隐私法规（GDPR、CCPA 等）
• 实时更新同意状态
• 查询同意历史记录和状态

前提条件

• 正在运行的 Apache Unomi 服务
• 已安装 Claude Desktop
• 可访问 Unomi 服务的网络连接
• 正确配置的安全设置
• 所需的环境变量

配置

环境变量

此服务需要以下环境变量：

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

可选：

# Where the server writes its debug log. Defaults to <os-temp-dir>/unomi-mcp-server.log.
UNOMI_LOG_FILE=/path/to/unomi-mcp-server.log

用户档案解析

此服务通过两个步骤解析用户档案 ID：

1. 电子邮件查找（如果设置了 UNOMI_EMAIL）：

   • 搜索电子邮件匹配的用户档案
   • 如果找到，则使用该用户档案的 ID
   • 有助于在不同会话之间保持用户档案一致

2. 回退用户档案 ID：

   • 如果电子邮件查找失败，或未设置 UNOMI_EMAIL
   • 使用环境变量中的 UNOMI_PROFILE_ID
   • 确保始终有可用的用户档案

响应会通过 source 字段指明使用的方法：

• "email_lookup"：通过电子邮件找到用户档案
• "environment"：使用回退用户档案 ID

Unomi 服务配置

1. 在 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. 确保在 etc/org.apache.unomi.cors.cfg 中正确配置 Unomi 服务的 CORS：

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

3. 重启 Unomi 服务以应用更改

重要：服务器配置中的 Unomi 密钥必须与 Claude Desktop 中的 UNOMI_KEY 环境变量完全一致。

配置

环境变量

此服务需要以下环境变量：

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

可选：

# Where the server writes its debug log. Defaults to <os-temp-dir>/unomi-mcp-server.log.
UNOMI_LOG_FILE=/path/to/unomi-mcp-server.log

用户档案解析

此服务通过两个步骤解析用户档案 ID：

1. 电子邮件查找（如果设置了 UNOMI_EMAIL）：

   • 搜索电子邮件匹配的用户档案
   • 如果找到，则使用该用户档案的 ID
   • 有助于在不同会话之间保持用户档案一致

2. 回退用户档案 ID：

   • 如果电子邮件查找失败，或未设置 UNOMI_EMAIL
   • 使用环境变量中的 UNOMI_PROFILE_ID
   • 确保始终有可用的用户档案

响应会通过 source 字段指明使用的方法：

• "email_lookup"：通过电子邮件找到用户档案
• "environment"：使用回退用户档案 ID

Unomi 服务配置

1. 在 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. 确保在 etc/org.apache.unomi.cors.cfg 中正确配置 Unomi 服务的 CORS：

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

3. 重启 Unomi 服务以应用更改

重要：服务器配置中的 Unomi 密钥必须与 Claude Desktop 中的 UNOMI_KEY 环境变量完全一致。

开发

欢迎贡献。请阅读 CONTRIBUTING.md，并在合并拉取请求前签署贡献者许可协议。

安装依赖：

npm install

构建服务：

npm run build

在开发时启用自动重新构建：

npm run watch

调试

由于 MCP 服务通过 stdio 通信，调试可能颇具挑战。我们建议使用 MCP Inspector，它可通过包脚本运行：

npm run inspector

Inspector 会提供一个 URL，供你在浏览器中访问调试工具。

你也可以持续查看 Claude Desktop 日志，以查看 MCP 请求和响应：

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

会话 ID 格式

使用 get_my_profile 时，系统会自动按以下格式生成会话 ID：

[profileId]-YYYYMMDD

例如，如果你的个人资料 ID 为 "user123"，今天是 2024 年 3 月 15 日，那么会话 ID 将为：

user123-20240315

故障排除

常见问题

1. 受保护事件失败

   • 确认两处配置中的 Unomi 密钥完全一致
   • 检查 IP 地址是否已正确加入白名单
   • 更新属性前，确保作用域已存在
   • 如有需要，检查 CORS 配置

2. 未找到个人资料

   • 检查是否已正确设置 UNOMI_EMAIL
   • 确认电子邮件格式有效
   • 确保 Unomi 中存在该个人资料
   • 检查备用 UNOMI_PROFILE_ID 是否有效

3. 会话问题

   • 请记住，会话按日期划分
   • 每个个人资料每天只能有一个会话
   • 检查会话 ID 格式是否与 profileId-YYYYMMDD 匹配
   • 确认会话对应的作用域已存在

4. 连接问题

   • 确认 Unomi 服务正在运行
   • 检查网络连接
   • 确保 UNOMI_BASE_URL 正确
   • 确认身份验证凭据

要检查的日志

1. Claude Desktop 日志：

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

2. Unomi 服务日志：

   # Usually in
   $UNOMI_HOME/logs/karaf.log
   

快速修复

1. 重置状态：

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

2. 验证配置：

   # 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 配置选项

1. 创建或编辑 Claude Desktop 配置：

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

2. 使用 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"
         }
       }
     }
   }
   

注意：使用 NPX 可确保你始终运行服务的最新已发布版本。

或者，如果你想使用特定版本：

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

开发或本地安装时：

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