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_USERNAME": "your-username", // 默认情况下，Apache Unomi 使用 karaf
        "UNOMI_PASSWORD": "your-password", // 默认情况下，Apache Unomi 使用 karaf
        "UNOMI_PROFILE_ID": "your-profile-id",
        "UNOMI_KEY": "your-unomi-key", // 默认情况下，Apache Unomi 使用 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 或电子邮件查找
  • 接受一个属性对象，其中包含要更新的键值对
  • 支持字符串、数字、布尔值和空值
  • 示例：

    {
      "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 请求和响应：

# 实时跟踪日志
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": {
        // ... 环境变量 ...
      }
    }
  }
}

对于开发或本地安装：

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