Inoyu MCP Unomi Server 中文配置指南

介绍

Inoyu MCP Unomi Server 是一个用于与 Unomi（一个 Apache CXS 项目）交互的 MCP 协议适配器。本文档详细介绍了如何安装、配置和使用该服务器。

安装

通过 npm 安装最新版本：

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

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

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

配置 MCP 服务器

环境变量

以下是所需的环境变量及其说明：

使用示例

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

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

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

配置选项

会话 ID 格式

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

[profileId]-YYYYMMDD

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

调试

由于 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

故障排除

常见问题

1. 受保护的事件失败

   • 确保 Unomi 密钥在两处配置中完全一致。
   • 检查 IP 地址是否被允许访问 Unomi。
   • 确保目标上下文已正确注册。

2. 连接问题

   • 确保 Unomi 服务正在运行且网络可达。
   • 检查防火墙设置，确保端口未被阻止。

3. 配置错误

   • 确保所有必填环境变量均已正确设置。
   • 验证 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 协议文档 或联系社区支持。