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

配置中的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 - 搜索个人资料
  • 采用查询字符串和可选的限制/偏移参数
  • 搜索 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桌面安装
• 通过网络访问 Unomi 服务器
• 适当的安全配置
• 必需的环境变量

配置

环境变量

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

配置文件解析

服务器使用两步流程来解析配置文件 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. 确保您的 Unomi 服务器在etc/org.apache.unomi.cors.cfg中正确配置了 CORS：
   # Add your Claude Desktop origin if needed org.apache.unomi.cors.allowed.origins=http://localhost:*
3. 重新启动 Unomi 服务器以应用更改

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

配置

环境变量

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

配置文件解析

服务器使用两步流程来解析配置文件 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. 确保您的 Unomi 服务器在etc/org.apache.unomi.cors.cfg中正确配置了 CORS：
   # Add your Claude Desktop origin if needed org.apache.unomi.cors.allowed.origins=http://localhost:*
3. 重新启动 Unomi 服务器以应用更改

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

发展

安装依赖项：

构建服务器：

对于使用自动重建的开发：

调试

由于 MCP 服务器通过 stdio 进行通信，调试起来可能比较困难。我们推荐使用MCP Inspector ，它以包脚本的形式提供：

检查器将提供一个 URL 来访问浏览器中的调试工具。

您还可以跟踪 Claude Desktop 日志来查看 MCP 请求和响应：

会话 ID 格式

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

例如，如果您的个人资料 ID 是“user123”，并且今天是 2024 年 3 月 15 日，则会话 ID 将为：

故障排除

常见问题

1. 受保护事件失败
   • 验证 Unomi 密钥在两个配置中完全匹配
   • 检查 IP 地址是否正确列入白名单
   • 更新属性之前确保范围存在
   • 如果需要，请验证 CORS 配置
2. 未找到个人资料
   • 检查 UNOMI_EMAIL 是否正确设置
   • 验证电子邮件格式是否有效
   • 确保配置文件存在于 Unomi 中
   • 检查后备 UNOMI_PROFILE_ID 是否有效
3. 会话问题
   • 请记住，会议是基于日期的
   • 每个个人资料每天仅限一次会话
   • 检查会话 ID 格式是否与profileId-YYYYMMDD匹配
   • 验证会话的范围是否存在
4. 连接问题
   • 验证 Unomi 服务器是否正在运行
   • 检查网络连接
   • 确保 UNOMI_BASE_URL 正确
   • 验证身份验证凭据

要检查的日志

1. Claude 桌面日志：
   # 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 桌面配置选项

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 可确保您始终运行服务器的最新发布版本。

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

对于开发或本地安装：