Inoyu MCP Unomi 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": "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
      }
    }
  }
}

这 env 配置中的部分允许您为服务器设置所需的环境变量。用实际的Unomi服务器详细信息替换这些值。

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

特性

个人资料访问

• 基于电子邮件的个人资料查找，可自动创建
• 个人资料属性、细分市场和分数访问
• 用于所有数据交换的JSON格式
• 基于日期的ID的自动会话管理

工具

• get_my_profile -使用环境变量获取您的个人资料

- 从环境或电子邮件查找中使用UNOMI_PROFILE_ID - 根据当前日期自动生成会话ID - 可选参数： - requireSegments：包括分段信息 - requireScores：包括评分信息

• update_my_profile -更新您个人资料的属性

- 从环境或电子邮件查找中使用UNOMI_PROFILE_ID - 接受具有键值对的属性对象进行更新 - 支持字符串、数字、布尔值和空值 - 例子：

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

• get_profile -按ID检索特定配置文件

- 将profileId作为必需参数 - 从Unomi返回完整的配置文件数据

• search_profiles -搜索个人资料

- 接受查询字符串和可选的限制/偏移参数 - 在名字、姓氏和电子邮件字段中搜索

• create_scope -创建新的Unomi作用域

- 接受作用域标识符和可选名称/描述 - 事件跟踪和配置文件更新所需 - 例子：

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

• get_tenant_info -获取当前租户的信息（仅限V3）

- 返回租户详细信息、版本信息和密钥状态 - 仅在使用Unomi V3时可用 - 无需参数

同意管理工具

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

- 使用Apache Unomi Consent API，如 官方文件 - 所需参数： - consultId：同意的唯一标识符 - 状态：同意状态（授予、拒绝或撤销） - 可选参数： - typeIdentifier：同意的类型标识符 - scope：同意的范围（默认为claude桌面） - 元数据：同意的其他元数据 - GDPR合规性： - 授予的同意在1年后到期（GDPR建议） - 被拒绝/撤销的同意立即到期 - 例子：

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

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

- 将consultId作为必需参数 - 返回同意详细信息，包括状态、时间戳和元数据 - 默认情况下使用您的个人资料（从环境或电子邮件查找） - 例子：

    {
      "consentId": "marketing-consent"
    }

• list_consents -列出具有可选过滤功能的个人资料的所有同意书

- 可选参数： - profileId：用于列出同意的配置文件ID（如果没有提供，则使用您的配置文件） - status：按同意状态筛选（已授予、拒绝或已撤销） - 范围：按范围筛选 - 返回经过筛选的同意列表及其元数据 - 例子：

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

范围管理

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

1. 默认范围：

- 默认作用域 claude-desktop 用于所有操作 - 需要时自动创建 - 用于配置文件更新和事件跟踪

1. 自定义范围：

- 可以使用创建 create_scope 工具 - 可用于分隔不同的应用程序或上下文 - 在用于配置文件操作之前必须存在

1. 自动创建作用域：

- 服务器检查是否存在所需的作用域 - 如果缺少，则自动创建它们 - 对作用域元数据使用有意义的默认值

备注：虽然作用域是在需要时自动创建的，但您仍然可以使用自定义名称和描述手动创建它们 create_scope 工具。

Apache Unomi V2/V3兼容性

此MCP服务器支持Apache Unomi V2和V3，具有自动版本检测和适当的身份验证方法。

版本检测

服务器根据以下内容自动检测Unomi版本 UNOMI_VERSION 环境变量：

• 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

1. V3的优点：

- 租户之间完全数据隔离 - 使用特定于租户的API密钥增强了安全性 - 多租户部署的可扩展性更好 - 更好地遵守数据隐私法规

概述

此MCP服务器使Claude能够通过Apache Unomi的配置文件管理系统维护用户的上下文。以下是你可以用它实现的目标：

关键能力

1. 用户识别:

- 使用电子邮件或个人资料ID在对话中识别用户 - 在会话之间保持一致的用户上下文 - 自动创建和管理用户配置文件

1. 上下文管理:

- 存储和检索用户首选项 - 管理用户同意首选项 - 跟踪同意状态和历史

1. 同意管理:

- 使用Apache Unomi的同意API更新用户同意状态 - 检索特定同意信息 - 按状态和范围列出和过滤同意书 - 自动同意过期处理（符合GDPR） - 支持GDPR和隐私合规

1. 集成功能:

- 无缝集成Claude桌面 - 自动会话管理 - 基于范围的上下文隔离

你能做什么

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

先决条件

• 运行Apache Unomi服务器
• Claude桌面安装
• 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

配置文件分辨率

服务器使用两步过程来解析配置文件ID：

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

- 搜索具有匹配电子邮件的个人资料 - 如果找到，则使用该配置文件的ID - 有助于在会话之间保持一致的配置文件

1. 后备配置文件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

1. 确保您的Unomi服务器在中正确配置了CORS etc/org.apache.unomi.cors.cfg:

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

1. 重新启动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

配置文件分辨率

服务器使用两步过程来解析配置文件ID：

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

- 搜索具有匹配电子邮件的个人资料 - 如果找到，则使用该配置文件的ID - 有助于在会话之间保持一致的配置文件

1. 后备配置文件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

1. 确保您的Unomi服务器在中正确配置了CORS etc/org.apache.unomi.cors.cfg:

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

1. 重新启动Unomi服务器以应用更改

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

发展

安装依赖项：

npm install

构建服务器：

npm run build

对于自动重建的开发：

npm run watch

调试

由于MCP服务器通过stdio进行通信，调试可能具有挑战性。我们建议使用 MCP检查员，可作为包脚本使用：

npm run 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配置

1. 未找到配置文件

- 检查UNOMI_EMAIL是否设置正确 - 验证电子邮件格式是否有效 - 确保Unomi中存在配置文件 - 检查回退UNOMI_PROFILE_ID是否有效

1. 会话问题

- 记住会话是基于日期的 - 每个配置文件每天只进行一次会话 - 检查会话ID格式是否匹配 profileId-YYYYMMDD - 验证会话的作用域是否存在

1. 连接问题

- 验证Unomi服务器是否正在运行 - 检查网络连接 - 确保UNOMI_BASE_URL正确 - 验证身份验证凭据

要检查的日志

1. 克劳德桌面日志:

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

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

1. Unomi服务器日志:

   # Usually in
   $UNOMI_HOME/logs/karaf.log

快速修复

1. 复位状态:

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

1. 验证配置:

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

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

- MacOS： ~/Library/Application Support/Claude/claude_desktop_config.json - 窗户： %APPDATA%/Claude/claude_desktop_config.json

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

备注：使用NPX可确保您始终运行最新发布的服务器版本。

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

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

对于开发或本地安装：

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