🚀 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 协议文档 或联系社区支持。