Inoyu Apache Unomi MCP 服务器

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

⚠️ 早期实现通知

这是一个用于演示目的的早期实现：

• 尚未验证可用于生产环境
• 可能会有所更改
• 尚未（目前）得到官方支持
• 仅用于学习和实验

当前范围

此实现提供：

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

其他 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_USERNAME": "your-username", // by default Apache Unomi uses karaf  
        "UNOMI_PASSWORD": "your-password", // by default Apache Unomi uses karaf
        "UNOMI_PROFILE_ID": "your-profile-id",
        "UNOMI_KEY": "your-unomi-key", // by default Apache Unomi uses 670c26d1cc413346c3b2fd9ce65dab41
        "UNOMI_EMAIL": "your-email@example.com",
        "UNOMI_SOURCE_ID": "claude-desktop"
      }
    }
  }
}

配置中的 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"
    }
    

范围管理

服务器自动为您管理范围：

1. 默认范围：

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

2. 自定义范围：

   • 可以使用 create_scope 工具创建
   • 适用于分离不同的应用程序或上下文
   • 在用于个人资料操作之前必须存在

3. 自动范围创建：

   • 服务器检查所需的范围是否存在
   • 如果缺失则自动创建
   • 使用有意义的默认值为范围元数据

注意：虽然在需要时会自动创建范围，但您仍然可以使用 create_scope 工具手动创建具有自定义名称和描述的范围。

概览

此 MCP 服务器使 Claude 能够通过 Apache Unomi 的个人资料管理系统维护关于用户的上下文。您可以实现以下功能：

主要功能

1. 用户识别：

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

2. 上下文管理：

   • 存储和检索用户偏好

3. 集成特性：

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

您可以做什么

• 让 Claude 在对话中记住用户偏好
• 存储和检索特定于用户的信息
• 维护一致的用户上下文
• 通过电子邮件识别管理多个用户

先决条件

• 运行 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

用户画像解析

服务器使用两步过程来解析用户画像 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 中配置受保护事件：

   # 受保护事件（如属性更新）所需
   org.apache.unomi.cluster.authorization.key=your-unomi-key
   
   # 允许 Claude Desktop 访问 Unomi 所需
   # 将 your-claude-desktop-ip 替换为实际 IP
   org.apache.unomi.ip.ranges=127.0.0.1,::1,your-claude-desktop-ip
   

2. 确保你的 Unomi 服务器在 etc/org.apache.unomi.cors.cfg 中正确配置了 CORS：

   # 如有需要，添加你的 Claude Desktop 源
   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

用户画像解析

服务器使用两步过程来解析用户画像 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 中配置受保护的事件：

   # 对于属性更新等受保护的事件是必需的
   org.apache.unomi.cluster.authorization.key=your-unomi-key
   
   # 允许 Claude Desktop 访问 Unomi 所需
   # 请将 your-claude-desktop-ip 替换为您的实际 IP 地址
   org.apache.unomi.ip.ranges=127.0.0.1,::1,your-claude-desktop-ip
   

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

   # 如有需要，请添加您的 Claude Desktop 源
   org.apache.unomi.cors.allowed.origins=http://localhost:*
   

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

重要：Unomi 密钥必须在您的服务器配置和 Claude Desktop 中的 UNOMI_KEY 环境变量之间完全匹配。

开发

安装依赖项：

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 服务器日志：

   # 通常位于
   $UNOMI_HOME/logs/karaf.log
   

快速修复

1. 重置状态:

   # 停止 Claude Desktop
   # 清除日志
   rm ~/Library/Logs/Claude/mcp*.log
   # 重启 Claude Desktop
   

2. 验证配置:

   # 检查 Unomi 连接
   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 配置选项

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": "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 ...
      }
    }
  }
}