INOYU-MCP-用户属性服务器
项目介绍
Inoyu Apache Unomi MCP Server
一个模型上下文协议服务器，使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", // 使用“2”表示Unomi V2，使用“3”表示Unomi V3（默认）
"UNOMI_USERNAME": "your-username", // 对于V2是必需的，对于V3是备用的
"UNOMI_PASSWORD": "your-password", // 对于V2是必需的，对于V3是备用的
"UNOMI_PROFILE_ID": "your-profile-id",
"UNOMI_KEY": "your-unomi-key", // 仅对V2是必需的
"UNOMI_EMAIL": "your-email@example.com",
"UNOMI_SOURCE_ID": "claude-desktop",
"UNOMI_TENANT_ID": "your-tenant-id", // 对于V3是必需的
"UNOMI_PUBLIC_KEY": "your-public-key", // 对于V3是必需的
"UNOMI_PRIVATE_KEY": "your-private-key" // 对于V3是必需的
}
}
}
}
配置中的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": "用于我的应用程序事件的范围" }
get_tenant_info- 获取当前租户的信息（仅限V3）- 返回租户详情、版本信息和密钥状态
- 仅当使用Unomi V3时可用
- 不需要任何参数
同意管理工具
-
update_consent- 使用modifyConsent事件更新用户的同意状态- 使用Apache Unomi同意API，如官方文档所述
- 必需参数：
- consentId: 同意的唯一标识符
- status: 同意状态（GRANTED、DENIED或REVOKED）
- 可选参数：
- typeIdentifier: 同意的类型标识符
- scope: 同意的范围（默认为claude-desktop）
- metadata: 同意的附加元数据
- GDPR合规性：
- GRANTED同意在一年后过期（GDPR建议）
- DENIED/REVOKED同意立即过期
- 示例：
{ "consentId": "marketing-consent", "status": "GRANTED", "typeIdentifier": "marketing", "scope": "claude-desktop", "metadata": { "source": "claude-desktop", "timestamp": "2024-01-15T10:30:00Z" } }
-
get_consent- 获取特定配置文件的同意信息- 需要consentId作为必填参数
- 返回包括状态、时间戳和元数据在内的同意详情
- 默认使用您的配置文件（从环境或电子邮件查找）
- 示例：
{ "consentId": "marketing-consent" }
-
list_consents- 列出配置文件的所有同意，可选过滤- 可选参数：
- profileId: 要列出同意的配置文件ID（如果未提供，则使用您的配置文件）
- status: 按同意状态过滤（GRANTED、DENIED或REVOKED）
- scope: 按范围过滤
- 返回过滤后的同意列表及其元数据
- 示例：
{ "status": "GRANTED", "scope": "claude-desktop" }
- 可选参数：
范围管理
服务器为您自动管理范围：
-
默认范围：
- 所有操作都使用默认范围
claude-desktop - 需要时自动创建
- 用于配置文件更新和事件跟踪
- 所有操作都使用默认范围
-
自定义范围：
- 可以使用
create_scope工具创建 - 用于分离不同的应用程序或上下文
- 在配置文件操作之前必须存在
- 可以使用
-
自动范围创建：
- 服务器检查所需范围是否存在
- 如果缺失则自动创建
- 使用有意义的默认值为范围元数据
注意：虽然范围在需要时会自动创建，但您仍然可以使用
create_scope工具手动创建具有自定义名称和描述的范围。
Apache Unomi V2/V3兼容性
此MCP服务器支持Apache Unomi V2和V3，并自动检测版本和适当的认证方法。
版本检测
服务器根据UNOMI_VERSION环境变量自动检测Unomi版本：
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
-
更新环境变量：
# 移除V2特有的变量 # UNOMI_KEY（不再需要） # 添加V3特有的变量 UNOMI_VERSION=3 UNOMI_TENANT_ID=your-tenant-id UNOMI_PUBLIC_KEY=your-public-key UNOMI_PRIVATE_KEY=your-private-key -
V3的优势：
- 租户之间的完全数据隔离
- 使用租户特定的API密钥增强安全性
- 多租户部署更好的可扩展性
- 更好地符合数据隐私法规
概览
此MCP服务器使Claude能够通过Apache Unomi的配置文件管理系统来维护关于用户的上下文。以下是您可以实现的目标：
关键能力
-
用户识别：
- 使用电子邮件或配置文件ID跨对话识别用户
- 在会话之间保持一致的用户上下文
- 自动创建和管理用户配置文件
-
上下文管理：
- 存储和检索用户偏好
- 管理用户同意偏好
- 跟踪同意状态和历史记录
-
同意管理：
- 使用Apache Unomi的同意API更新用户同意状态
- 检索特定的同意信息
- 列出并按状态和范围筛选同意
- 自动处理同意到期（GDPR合规）
- 支持GDPR和隐私合规
-
集成特性：
- 无缝集成到Claude Desktop
- 自动会话管理
- 基于范围的上下文隔离
您可以做什么
- 让Claude记住跨对话的用户偏好
- 存储和检索特定于用户的资料
- 维护一致的用户上下文
- 通过电子邮件识别管理多个用户
- 跟踪和管理用户同意偏好
- 符合隐私法规（GDPR、CCPA等）
- 实时更新同意状态
- 查询同意历史和状态
先决条件
- 运行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环境变量完全匹配。
开发
安装依赖项：
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
故障排除
常见问题
-
受保护事件失败
- 验证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
- MacOS：
-
使用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": {