Indigo MCP Server

🚀 Indigo MCP 服務器插件

Indigo MCP 服務器插件是一款為 Indigo Domotics 打造的模型上下文協議（MCP）服務器插件，它能讓 Claude 等 AI 助手通過自然語言查詢與你的家庭自動化系統進行交互。

🚀 快速開始

本插件藉助向量數據庫（LanceDB）實現語義搜索功能，相較於簡單的文本匹配，它能理解查詢的含義和上下文，使搜索更加直觀和強大。

✨ 主要特性

• 語義搜索：通過向量數據庫實現，理解查詢的含義和上下文，讓搜索更智能。
• 豐富的 API 接口：提供設備、變量和動作資源的多種 API，支持自然語言搜索和設備控制。
• 多工具支持：包含多種工具，如語義搜索、設備類型過濾、設備控制、變量更新、動作執行和歷史數據分析等。
• 多客戶端兼容：支持 Claude Desktop 等 MCP 兼容客戶端。

📦 安裝指南

必備條件

• OpenAI API 密鑰：這對於語義搜索功能至關重要。
  • 你可以從 OpenAI 平臺 獲取 API 密鑰。
  • 該密鑰用於生成嵌入向量，以支持向量搜索功能。
  • 對於家庭自動化查詢，費用通常較低。
• 支持的系統：
  • Indigo Domotics 2024.2 或更高版本。
  • Python 3.11+。

可選配置

LangSmith（測試和調試）

• 用途：對 AI 交互進行高級跟蹤和調試。
• 好處：監控查詢性能、調試搜索結果、優化提示。
• 設置：需要 LangSmith API 密鑰和項目配置。
• 適用場景：推薦給開發者或遇到搜索問題的用戶。

InfluxDB（歷史查詢）

• 用途：訪問歷史設備數據和趨勢。
• 好處：查詢過去的設備狀態，分析隨時間的使用模式。
• 設置：需要運行一個包含 Indigo 歷史數據的 InfluxDB 實例。
• 適用場景：對已有 InfluxDB 日誌設置的用戶很有用。

💻 使用示例

基礎用法

以下是使用 search_entities 工具進行自然語言搜索的示例：

# 假設使用 Python 調用 API 進行自然語言搜索
import requests

# 假設的 API 地址
api_url = "http://[your server]:[YOUR_PORT]/mcp"
query = "bedroom lights"
response = requests.get(f"{api_url}/search_entities?query={query}")
print(response.json())

高級用法

以下是使用 analyze_historical_data 工具進行歷史數據分析的示例：

# 假設使用 Python 調用 API 進行歷史數據分析
import requests

# 假設的 API 地址
api_url = "http://[your server]:[YOUR_PORT]/mcp"
query = "Analyze the temperature trend in the past month"
device_names = ["TemperatureSensor1", "TemperatureSensor2"]
time_range = 30
response = requests.get(f"{api_url}/analyze_historical_data?query={query}&device_names={','.join(device_names)}&time_range={time_range}")
print(response.json())

📚 詳細文檔

API 特性

可用的 MCP 資源

設備資源

• GET /devices - 列出所有設備的基本屬性（用於概覽）。
• GET /devices/{id} - 獲取具有完整屬性的特定設備。
• GET /devices/by-type/{type} - 獲取按邏輯類型過濾的設備。

變量資源

• GET /variables - 列出所有變量。
• GET /variables/{id} - 獲取特定變量。

動作資源

• GET /actions - 列出所有動作組。
• GET /actions/{id} - 獲取特定動作組。

可用的 MCP 工具

1. search_entities

在所有 Indigo 實體上進行自然語言搜索：

• 用途：對設備、變量和動作組進行語義搜索。
• 輸入：自然語言查詢（例如，“臥室燈光”，“溫度傳感器”）。
• 搜索特性：
  • 相似度閾值：0.15（返回所有高於此閾值的相關結果）。
  • 無人工結果限制 - 返回所有匹配的實體。
  • 包含完整的設備屬性（未過濾）。
  • 語義關鍵字增強，提高搜索準確性。
  • 支持設備類型過濾（調光器、繼電器、傳感器、恆溫器、灑水器、IO、其他）。
• 輸出：帶有完整實體屬性和相關性評分的格式化結果。

2. get_devices_by_type

在不進行語義過濾的情況下獲取特定類型的所有設備：

• 用途：檢索所有匹配特定設備類型的設備。
• 輸入：設備類型（調光器、繼電器、傳感器、多 IO、速度控制、灑水器、恆溫器、設備）。
• 輸出：具有完整屬性的指定類型的所有設備。
• 適用場景：當你需要特定類型的所有設備，而不是上下文搜索結果時。

3. 設備控制工具

直接控制設備的功能：

• device_turn_on - 通過設備 ID 打開設備。
• device_turn_off - 通過設備 ID 關閉設備。
• device_set_brightness - 為可調光設備設置亮度級別（0 - 1 或 0 - 100）。

4. variable_update

更新 Indigo 變量的值：

• 用途：修改 Indigo 系統中的變量值。
• 輸入：變量 ID 和新值（作為字符串）。
• 輸出：操作狀態和更新後的變量信息。

5. action_execute_group

執行 Indigo 動作組（場景）：

• 用途：觸發 Indigo 系統中的動作組/場景。
• 輸入：動作組 ID 和可選的延遲時間（秒）。
• 輸出：執行狀態和確認信息。

6. analyze_historical_data

使用 LangGraph 工作流進行 AI 驅動的歷史數據分析：

• 用途：分析設備行為模式和隨時間的趨勢。
• 輸入：自然語言查詢、設備名稱列表、時間範圍（1 - 365 天，默認：30 天）。
• 特性：
  • 使用高級 AI 工作流進行數據分析。
  • 提供見解和趨勢識別。
  • 支持複雜的模式識別查詢。
• 輸出：帶有見解和可視化的詳細分析結果。

MCP 客戶端設置

Claude Desktop 配置

將以下配置添加到你的 claude_desktop_config.json 文件中：

{
  "mcpServers": {
    "indigo": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://[your server]:8080/mcp"
      ]
    }
  }
}

將 [your server] 替換為你的 IP 或 Indigo 服務器主機名，如果端口不是 8080，請將其替換為你配置的服務器端口。

Claude Desktop 配置文件位置

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

其他 MCP 客戶端

該插件可與任何 MCP 兼容的客戶端配合使用。使用以下 HTTP 傳輸端點：

http://[your server]:[YOUR_PORT]/mcp

已測試的客戶端

• ✅ Claude Desktop：經過全面測試和支持。
• ⚠️ 其他 MCP 客戶端：應該可以工作，但未進行廣泛測試。

🔧 技術細節

LLM 使用

重要隱私注意事項：

• OpenAI API：你的設備名稱、狀態和描述會發送到 OpenAI 以生成嵌入向量。
• 搜索查詢：自然語言查詢可能會由 OpenAI 進行語義理解處理。
• 最小數據傳輸：僅發送設備名稱、類型和描述，不包含敏感配置細節。
• 本地存儲：所有向量嵌入都存儲在你的 Indigo 服務器本地。

HTTP 服務器安全

• 僅本地訪問：為了安全起見，服務器默認綁定到 127.0.0.1（本地主機）。
• 如果你決定啟用遠程訪問，切勿暴露到互聯網：絕對不要將此 HTTP 服務器暴露到互聯網。

📄 許可證

文檔中未提及許可證相關信息。

其他說明

提升 AI 結果

你可以在設備的備註中添加信息，這將有助於引導大語言模型（LLM）。

路線圖

計劃功能

• 添加 SSL 支持（可能會比較複雜）。
• 添加認證令牌。

支持與故障排除

如果你遇到問題，請在此處提交問題。如需支持，請訪問：https://forums.indigodomo.com/viewforum.php?f=274&sid=42b03ddd145b4f1309cb493be3bb2908