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