Inoyu Apache Unomi MCP Server

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

⚠️ 早期实施通知

这是一个早期实施版本，仅用于演示目的：

未经过生产环境验证

可能会发生变化

尚未（正式）提供支持

仅用于学习和实验

当前范围

此实施提供：

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

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

Demo

观看 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 格式
基于日期的自动会话管理

工具

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 和电子邮件字段中搜索
create_scope - 创建新的 Unomi 范围
- 接收范围标识符和可选的名称/描述
- 对于事件跟踪和配置文件更新是必需的
- 示例：
```
{
  "scope": "my-app",
  "name": "My Application",
  "description": "Scope for my application events"
}
```

范围管理

服务器会自动管理范围：

默认范围：
- 所有操作都使用默认范围 claude-desktop
- 当需要时自动创建
- 用于配置文件更新和事件跟踪
自定义范围：
- 可以使用 create_scope 工具创建
- 对于分离不同的应用程序或上下文很有用
- 在使用前必须存在
自动创建范围：
- 服务器检查所需范围是否存在
- 如果缺失则自动创建
- 为范围元数据使用有意义的默认值

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

概述

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

关键功能

用户识别：
- 使用电子邮件或配置文件 ID 跨对话识别用户
- 在会话之间保持一致的用户上下文
- 自动创建和管理用户配置文件
上下文管理：
- 存储和检索用户偏好
集成功能：
- 与 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：

电子邮件查找（如果设置了 UNOMI_EMAIL）：
- 搜索具有匹配电子邮件的配置文件
- 如果找到，则使用该配置文件的 ID
- 对于在会话之间保持一致配置文件很有用
备用配置文件 ID：
- 如果电子邮件查找失败或未设置 UNOMI_EMAIL
- 使用环境中的 UNOMI_PROFILE_ID
- 确保始终有配置文件可用

响应将通过 source 字段指示使用的方法：

"email_lookup"：通过电子邮件找到配置文件
"environment"：使用备用配置文件 ID

Unomi 服务器配置

在 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

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

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

重启 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：

电子邮件查找（如果设置了 UNOMI_EMAIL）：
- 搜索具有匹配电子邮件的配置文件
- 如果找到，则使用该配置文件的 ID
- 对于在会话之间保持一致配置文件很有用
备用配置文件 ID：
- 如果电子邮件查找失败或未设置 UNOMI_EMAIL
- 使用环境中的 UNOMI_PROFILE_ID
- 确保始终有配置文件可用

响应将通过 source 字段指示使用的方法：

"email_lookup"：通过电子邮件找到配置文件
"environment"：使用备用配置文件 ID

Unomi 服务器配置

在 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

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

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

重启 Unomi 服务器以应用更改

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

开发

安装依赖项：

npm install

构建服务器：

npm run build

用于开发并自动重建：

npm run watch

调试

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

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

故障排除

常见问题

受保护的事件失败
- 验证 Unomi 密钥在两个配置中完全匹配
- 检查 IP 地址是否正确白名单
- 确保在更新属性前存在范围
- 如有必要，验证 CORS 配置
配置文件未找到
- 检查是否正确设置了 UNOMI_EMAIL
- 验证电子邮件格式是否有效
- 确保配置文件存在于 Unomi
- 检查备用 UNOMI_PROFILE_ID 是否有效
会话问题
- 请记住会话是基于日期的
- 每个配置文件每天只有一个会话
- 检查会话 ID 格式是否匹配 profileId-YYYYMMDD
- 验证会话的范围是否存在
连接问题
- 验证 Unomi 服务器是否正在运行
- 检查网络连接
- 确保 UNOMI_BASE_URL 是否正确
- 验证身份验证凭据

要检查的日志

Claude Desktop 日志：

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

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

Unomi 服务器日志：
```
# 通常在
$UNOMI_HOME/logs/karaf.log
```

快速修复

重置状态：

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

验证配置：

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

创建或编辑您的 Claude Desktop 配置：
- MacOS：~/Library/Application Support/Claude/claude_desktop_config.json
- Windows：%APPDATA%/Claude/claude_desktop_config.json

使用 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": {
        // ... 环境变量 ...
      }
    }
  }
}

sergehuber/inoyu-mcp-unomi-server

星标增长

证据时间轴

Inoyu Apache Unomi MCP Server

当前范围

Demo

安装

功能

配置文件访问

工具

范围管理

概述

关键功能

您可以做什么

前提条件

配置

环境变量

配置文件解析

Unomi 服务器配置

配置

环境变量

配置文件解析

Unomi 服务器配置

开发

调试

会话 ID 格式

故障排除

常见问题

要检查的日志

快速修复

Claude Desktop 配置选项