使用说明

项目简介

该项目是一个 Model Context Protocol (MCP) 服务器的实现，它作为 Claude 等大型语言模型（LLM）应用的后端，桥接了 Apache Unomi 用户画像管理系统。通过此 MCP 服务器，LLM 应用能够利用 Apache Unomi 强大的用户画像功能，实现用户上下文的持久化和管理，从而提升对话体验和应用智能化水平。

主要功能点

用户画像管理: 基于 Apache Unomi，支持用户画像的创建、检索和更新，允许 LLM 应用存储和访问用户属性、标签和评分等信息。
上下文维护: 为 LLM 应用提供用户会话管理能力，确保跨会话的用户上下文一致性。
工具集成: 提供一系列工具，如获取个人画像信息、更新画像属性、搜索画像、创建 Scope 等，方便 LLM 应用调用和管理用户数据。
Claude 桌面集成: 专门为 Claude 桌面应用设计，可以无缝集成，扩展 Claude 的上下文处理能力。
环境配置: 通过简单的环境变量配置，即可连接到 Apache Unomi 服务器，快速部署和使用。

安装步骤

前提条件: 确保已安装 Node.js 和 npm。同时，您需要预先部署并运行 Apache Unomi 服务器。
配置 Claude 桌面: 根据您的操作系统，编辑 Claude 桌面的配置文件 'claude_desktop_config.json'。
- MacOS: '~/Library/Application Support/Claude/claude_desktop_config.json'
- Windows: '%APPDATA%/Claude/claude_desktop_config.json' 如果文件不存在，请手动创建。
添加 MCP 服务器配置: 在 'claude_desktop_config.json' 文件中添加 'mcpServers' 配置段落，并填入以下 JSON 配置信息。

服务器配置

以下是 'claude_desktop_config.json' 中 'mcpServers' 的配置示例。请根据您的实际 Apache Unomi 服务器信息修改 'env' 中的参数。

{
  "mcpServers": {
    "unomi-server": {
      "command": "npx",
      "args": ["@inoyu/mcp-unomi-server"],
      "env": {
        "UNOMI_BASE_URL": "http://your-unomi-server:8181",  // Apache Unomi 服务器的地址，例如 http://localhost:8181
        "UNOMI_USERNAME": "your-username",                  // Apache Unomi 的用户名，默认是 karaf
        "UNOMI_PASSWORD": "your-password",                  // Apache Unomi 的密码，默认是 karaf
        "UNOMI_PROFILE_ID": "your-profile-id",               // 默认的用户画像 ID，作为备选项
        "UNOMI_KEY": "your-unomi-key",                     // Apache Unomi 的安全密钥，用于事件保护
        "UNOMI_EMAIL": "[email protected]",           // 用户的邮箱地址，用于通过邮箱查找用户画像
        "UNOMI_SOURCE_ID": "claude-desktop"                 // 数据来源 ID，默认为 claude-desktop
      }
    }
  }
}

参数说明:

'server name': 'unomi-server'，服务器名称，可以自定义。
'command': 'npx'，使用 npx 命令执行。
'args': '["@inoyu/mcp-unomi-server"]'，MCP 服务器的 npm 包名，npx 将会自动下载并执行最新版本。
'env': 环境变量配置，用于连接和认证 Apache Unomi 服务器。请务必替换示例值为您实际的 Unomi 服务器配置。

重启 Claude 桌面: 完成配置后，重启 Claude 桌面应用使配置生效。

基本使用方法

检查工具: 重启 Claude 桌面后，点击聊天窗口右下角的 "工具" 图标，确认 Claude 已经成功检测到由 'unomi-server' 提供的工具。
使用工具: 在 Claude 聊天对话中，您可以像调用其他工具一样，使用 'unomi-server' 提供的工具，例如：
- '@unomi-server get_my_profile' : 获取当前用户的画像信息。
- '@unomi-server update_my_profile properties={"firstName": "NewFirstName"}' : 更新用户画像的 'firstName' 属性。
- '@unomi-server search_profiles query="John"' : 搜索名字包含 "John" 的用户画像。
- '@unomi-server create_scope scope="my-app" name="My Application"' : 创建一个新的 Scope。

通过这些工具，您可以在 Claude 对话中实现用户上下文的读取和写入，从而构建更加智能和个性化的 LLM 应用。

关键词