Inoyu MCP Unomi Server

🚀 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 服務器

環境變量

以下是配置所需的環境變量及其說明：

配置選項

會話 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

故障排除

常見問題

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 協議文檔 或聯繫社區支持。