JinDaGe - inoyu-mcp-unomi-server MCP Details

article

README

🚀 Inoyu MCP Unomi Server 中文配置指南

Inoyu MCP Unomi Server 是一个用于与 Unomi（一个 Apache CXS 项目）交互的 MCP 协议适配器。本指南将详细介绍该服务器的安装、配置和使用方法。

🚀 快速开始

本指南将帮助你完成 Inoyu MCP Unomi Server 的安装、配置和使用。按照步骤操作，你将能够顺利运行该服务器。

📦 安装指南

你可以通过 npm 安装 Inoyu MCP Unomi Server 的最新版本：

npm install -g @inoyu/mcp-unomi-server

若要指定特定版本，请运行以下命令：

npm install -g @inoyu/mcp-unomi-server@0.1.0

📚 详细文档

配置 MCP 服务器

环境变量

以下是配置所需的环境变量及其说明： | 属性 | 详情 | |------|------| | UNOMI_BASE_URL | 字符串类型，必填。Unomi 的基础 URL，例如 http://localhost:8181。 | | UNOMI_USERNAME | 字符串类型，必填。登录 Unomi 的用户名。 | | UNOMI_PASSWORD | 字符串类型，必填。对应的密码。 | | UNOMI_PROFILE_ID | 字符串类型，必填。用户的唯一标识符，必须与 Unomi 中注册的用户匹配。 | | UNOMI_SOURCE_ID | 字符串类型，必填。用于标识此 MCP 服务器的来源 ID，默认为 default-source-id。 | | UNOMI_KEY | 字符串类型，选填。用于加密通信的安全密钥，建议在生产环境中启用。 |

配置选项

会话 ID 格式

默认情况下，get_my_profile 方法生成的会话 ID 格式为：

[profileId]-YYYYMMDD

例如：如果 profileId 是 user123 且当前日期是 2024 年 3 月 15 日，则会话 ID 为 user123-20240315。

💻 使用示例

基础用法

以下是运行服务器的基本命令：

# 基本使用
npx @inoyu/mcp-unomi-server

高级用法

指定环境变量来运行服务器：

# 指定环境变量
UNOMI_BASE_URL=http://localhost:8181 \
UNOMI_USERNAME=admin \
UNOMI_PASSWORD=secret \
npx @inoyu/mcp-unomi-server

🔧 技术细节

调试

由于 MCP 服务器通过标准输入输出进行通信，调试可能会比较困难。我们推荐使用 MCP Inspector 来帮助调试：

npm run inspector

此外，您还可以查看 Claude Desktop 的日志：

# MacOS
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

# Windows
tail -n 20 -f %APPDATA%\Claude\mcp*.log

故障排除

常见问题

受保护的事件失败
- 确保 Unomi 密钥在两处配置中完全一致。
- 检查 IP 地址是否被允许访问 Unomi。
- 确保目标上下文已正确注册。
连接问题
- 确保 Unomi 服务正在运行且网络可达。
- 检查防火墙设置，确保端口未被阻止。
配置错误
- 确保所有必填环境变量均已正确设置。
- 验证 profileId 是否与 Unomi 中的用户记录匹配。

高级主题

安全最佳实践

在生产环境中启用 UNOMI_KEY 进行加密通信。
使用 HTTPS 保护与 Unomi 的通信。
定期轮换密钥并监控未经授权的访问尝试。

日志和监控

使用日志管理工具（如 ELK 系列）来集中处理 MCP 服务器的日志。
监控关键指标，例如请求成功率和延迟。

示例配置

以下是一个完整的 package.json 示例：

{
    "name": "mcp-unomi-server",
    "version": "1.0.0",
    "scripts": {
        "start": "npx @inoyu/mcp-unomi-server"
    },
    "dependencies": {
        "@inoyu/mcp-unomi-server": "^0.1.0"
    }
}

结语

通过本文档，你应该能够顺利配置并运行 Inoyu MCP Unomi Server。如果仍有疑问或遇到问题，请参考 MCP 协议文档或联系社区支持。

inoyu-mcp-unomi-server