内容
# 印第哥MCP精简版
印第哥MCP精简版是一个仅限于标准库的[模型上下文协议](https://modelcontextprotocol.io)服务器，作为印第哥插件打包。它允许克劳德等AI助手通过自然语言搜索、控制和推理印第哥设备。
> **为什么叫“精简版”？** 这个插件取代了[`mlamoure/indigo-mcp-server`](https://github.com/mlamoure/indigo-mcp-server)，适用于无法运行该插件的矢量搜索依赖项的用户（LanceDB需要AVX2 + Apple Silicon或最近的Intel； 在印第哥2025.2 / Python 3.13上，LanceDB轮子完全停止在Intel Mac上安装）。精简版使用SQLite FTS5代替 - 内置于Python的标准库中，无需本地依赖，无需外部API密钥，无需嵌入。搜索是基于关键词和别名的，而不是语义的，但速度很快（<50ms超过~2k实体），并且在印第哥运行的任何地方运行。
## 它能做什么
问克劳德：
- “我在厨房里有多少个调光器？”
- “查找所有漏水传感器”
- “将卧室灯调至30％暖白色”
- “客厅的供暖设定点是什么？”
- “显示过去一小时事件日志中的错误”
- “运行晚安场景”
精简版公开了68个MCP工具 - 完全读取设备/变量/动作组/触发器/计划的权限，写入调光器/继电器/恒温器/变量/动作组的控制权限，系统自省（事件日志，插件状态），以及一个基于FTS5的`find_devices`搜索。
## 服务器要求
- **印第哥Domotics**：2024.2或更高版本
- **macOS**：任何印第哥支持的版本 - 精简版没有本地依赖
- **CPU**：Intel或Apple Silicon - 无AVX2要求，无嵌入库
- **Python**：3.10+（印第哥自带；无需额外安装）
- **Pip依赖**：零（SQL Logger历史记录通过标准库sqlite3工作，或使用`psql` CLI用于PostgreSQL - 无需psycopg2）
这是“精简版”的重点 - 安装在任何印第哥支持的Mac上即可运行。
## 安装
1. **下载** 最新版本的`Indigo MCP Lite.indigoPlugin.zip` 从 [发布页面](https://github.com/simons-plugins/indigo-mcp-lite/releases)。
2. **首次安装：双击** 解压后的`.indigoPlugin` 通过印第哥安装。后续更新可以通过`cp`部署，但首次安装必须通过印第哥UI进行，以便正确注册。
3. **启用** 印第哥中的插件：插件 → 印第哥MCP精简版 → 启用。
4. **无需配置** - 精简版在启用后立即运行。MCP端点通过印第哥的IWS自动公开在`https://<your-indigo-host>/message/com.simons-plugins.indigo-mcp-lite/mcp`。
### 认证
认证由 **印第哥的Web服务器（IWS）在插件前面强制执行** - 插件本身不执行任何授权检查，并且永远不会看到您的凭证。没有有效Bearer令牌的请求在调用MCP端点之前被IWS拒绝。 使用以下任意一种：
- **本地密钥** 用于局域网访问 - 通过`secrets.json`按照 [印第哥的本地密钥文档](https://wiki.indigodomo.com/doku.php?id=indigo_2024.2_documentation:indigo_web_server#local_secrets) 设置，并作为`Authorization: Bearer <local-secret>`传递。
- **反射器API密钥** 用于远程访问 - 从您的印第哥反射器设置中颁发。
因此，请勿在未配置本地密钥的情况下将IWS的端口直接暴露给互联网 - 如果禁用或绕过IWS身份验证，则没有第二道防线，每个工具（包括控制工具）都可以在未经身份验证的情况下访问。
## 克劳德代码/克劳德桌面配置
两种配置模式。选择适合您情况的一种。
### 模式A - 替换（推荐大多数用户）
用精简版替换mlamoure的`indigo`MCP服务器条目。保留`mcp__indigo__*`工具命名空间和现有的肌肉记忆；当精简版是您唯一的印第哥MCP时最佳。
在您的克劳德代码项目的`.mcp.json`（带有点 - 克劳德代码读取此文件；不是`mcp.json`）：
```json
{
"mcpServers": {
"indigo": {
"command": "/opt/homebrew/bin/npx",
"args": [
"-y",
"mcp-remote",
"https://your-reflector.indigodomo.net/message/com.simons-plugins.indigo-mcp-lite/mcp",
"--header",
"Authorization:Bearer YOUR_TOKEN"
],
"env": {
"PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
}
}
}
}
```
对于克劳德桌面，相应的文件是`~/Library/Application Support/Claude/claude_desktop_config.json`。
### 模式B - 并存
使用不同的密钥，以便工具前缀不会冲突。工具出现在`mcp__indigo_mcp_lite__*`下。
```json
{
"mcpServers": {
"indigo": {
"command": "/opt/homebrew/bin/npx",
"args": [
"-y", "mcp-remote",
"https://your-reflector.indigodomo.net/message/com.vtmikel.mcp_server/mcp/",
"--header", "Authorization:Bearer YOUR_TOKEN"
],
"env": {"PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"}
},
"indigo-mcp-lite": {
"command": "/opt/homebrew/bin/npx",
"args": [
"-y", "mcp-remote",
"https://your-reflector.indigodomo.net/message/com.simons-plugins.indigo-mcp-lite/mcp",
"--header", "Authorization:Bearer YOUR_TOKEN"
],
"env": {"PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"}
}
}
}
```
选择此选项，如果您想在Apple Silicon上保留mlamoure的语义搜索 **和** 精简版的轻量级标准库路径，用于更简单的查询。
### 仅限局域网配置
对于仅限局域网访问，无需反射器，请交换URL主机：
```
https://jarvis.local:8176/message/com.simons-plugins.indigo-mcp-lite/mcp
```
（用您的印第哥服务器的主机名替换`jarvis.local`；`8176`是IWS的HTTPS端口。）使用您的本地密钥作为Bearer令牌。
## 重要配置注意事项
这些问题在我们设置过程中遇到了；在这里提出，以免您遇到同样的问题。
### `.mcp.json`（带点）与`mcp.json`（不带点）
克劳德代码读取 **`.mcp.json`** （点文件）用于项目本地MCP服务器。协和和其他一些工具读取`mcp.json`（不带点）。这两个文件是独立的 - 编辑错误的文件会默默地对另一个工具无效。如果精简版的命名空间在克劳德代码的可用工具中未出现，请 **首先检查您编辑了`.mcp.json`** （点文件）。
### 通过`env.PATH`固定节点
`mcp-remote`的`undici`依赖项需要节点≥18。如果您的shell中有一个较旧的节点在PATH中（常见于`nvm`），则桥会在导入时崩溃，并出现`ReferenceError: ReadableStream is not defined`错误，克劳德代码会显示“服务器断开连接”，没有任何详细信息。
上面的配置中的`env.PATH`块将Homebrew的节点固定在PATH的前面 **仅用于桥接子进程** ，从而避免了这个问题，而无需更改您的shell设置。
### 不要在克劳德代码的MCP配置中使用`type: "http"`
克劳德代码的`type: "http"`表单期望服务器发送事件（SSE）传输。精简版（和Home Intelligence）使用纯HTTP POST JSON-RPC，而不是SSE - 连接在会话开始时默默地失败。 **改用`mcp-remote`桥接表单（`command + args + env`）。** `mcp-remote`在克劳德代码的SSE期望和插件的纯JSON-RPC之间进行转换。
### 冷启动竞争
如果`mcp-remote`尚未在本地缓存，则`npx -y mcp-remote ...`必须在第一次运行时获取包，这可能会超过克劳德代码的MCP服务器启动超时。在`mcp-remote`运行一次并缓存后，随后的会话启动速度很快。如果命名空间在第一次会话中丢失，请手动运行一次`npx -y mcp-remote --help`以预热缓存，然后启动一个新的克劳德代码会话。
### 重启精简版本身
`restart_plugin`故意拒绝重启`com.simons-plugins.indigo-mcp-lite` - 自我重启会杀死正在进行的MCP请求，响应中途，调用者会看到传输错误而不是干净的工具结果。 通过印第哥的UI重启精简版（插件 → 印第哥MCP精简版 → 重载）或其他指向不同印第哥插件的MCP客户端。
## 工具
<!-- BEGIN TOOL TABLE -->
<!-- AUTO-GENERATED by scripts/generate_tool_doc.py — 68 tools -->
### 查询工具（19）
| 工具 | 描述 |
|------|-------------|
| `get_action_group_by_id` | 按ID返回单个印第哥动作组。 |
| `get_dependencies` | 列出引用某个实体的所有内容（触发器、计划、动作组、控制页面、设备、变量）。在删除变量或禁用设备之前检查此项 - 删除某些内容会破坏使用它的自动化。 |
| `get_device_by_id` | 按ID返回单个印第哥设备。 |
| `get_device_group` | 解析分组（多端点）设备为其组：成员设备ID和序列化根设备。某些属性（尤其是电池级别）仅存在于根设备上 - 当子端点显示空电池级别时使用此功能。 |
| `get_devices_by_state` | 列出匹配指定状态规范的印第哥设备。规范是一个JSON对象，其键是状态名称；值是字面值（==）或字符串前缀比较符（>=、<=、>、<），例如 {“onState”: true, “batteryLevel”: “<20”}。 |
| `get_devices_by_type` | 按deviceTypeId筛选印第哥设备。 |
| `get_schedule_by_id` | 按ID返回单个印第哥计划。 |
| `get_trigger_by_id` | 按ID返回单个印第哥触发器。 |
| `get_variable_by_id` | 按ID返回单个印第哥变量。 |
| `get_zwave_device_details` | 返回单个设备的完整Z-Wave元数据：节点地址、电池级别、固件版本、错误状态和原始Z-Wave接口属性（监听/电池标志、制造商信息）来自globalProps。 |
| `list_action_groups` | 列出印第哥动作组，可选分页。 |
| `list_device_folders` | 列出印第哥设备文件夹（ID + 名称）。 |
| `list_devices` | 列出印第哥设备，可选分页和筛选。 |
| `list_schedules` | 列出印第哥计划（ID、名称、启用、next_execution）并分页。计划是时间驱动的自动化。 |
| `list_sql_logger_columns` | 列出为一个设备记录的SQL Logger历史记录列（名称 + 类型）- 有效的`column`值，用于查询sql_logger。如果设备没有历史记录表，则会出错。 |
| `list_triggers` | 列出印第哥触发器（ID、名称、类型、启用）并分页。触发器是事件驱动的自动化。 |
| `list_variable_folders` | 列出印第哥变量文件夹（ID + 名称）。 |
| `list_variables` | 列出印第哥变量，可选分页。 |
| `list_zwave_devices` | 列出Z-Wave设备（协议 == ZWave），带有节点地址、电池级别、固件版本和错误状态。使用get_zwave_device_details获取单个设备的完整元数据。 |
### 控制工具（27）
| 工具 | 描述 |
|------|-------------|
| `action_execute_group` | 执行印第哥动作组ID。 |
| `device_beep` | 要求设备发出可听见的蜂鸣声（硬件允许）- 有助于物理定位。 |
| `device_brighten` | 相对当前级别增加调光器的亮度（可选`by` 1-100，可选延迟）。 |
| `device_dim` | 相对当前级别降低调光器的亮度（可选`by` 1-100，可选延迟）。 |
| `device_enable` | 启用或禁用设备的通信（将故障或离线设备从服务中移除或恢复）。 |
| `device_lock` | 锁定锁定设备。可选延迟和自动解锁持续时间。 |
| `device_ping` | Ping Z-Wave/Insteon模块并报告毫秒级往返时间 - 检查可达性而不更改状态。 |
| `device_reset_energy_accum` | 将设备的累积能量（kWh）计数器重置为零。 |
| `device_set_brightness` | 设置调光器的亮度0-100。接受0-1的浮点数，用于小数调用；超出范围的值将被限制。 |
| `device_set_hex_color` | 从十六进制字符串设置具有颜色功能的调光器的RGB颜色。接受#RRGGBB、RRGGBB、#RGB或RGB。 |
| `device_set_named_color` | 从CSS命名颜色设置具有颜色功能的调光器的RGB颜色（红色、aliceblue、dodgerblue等）。支持140种名称；不区分大小写和空格/下划线；英国*灰色*拼写解析为*灰色*等效。 |
| `device_set_rgb_color` | 设置具有颜色功能的调光器的RGB颜色。通道是0-255字节值；超出范围的值将在转换为印第哥的0-100线单位之前被限制。 |
| `device_set_rgb_percent` | 使用0-100百分比通道设置具有颜色功能的调光器的RGB颜色（匹配印第哥的原生单位）。 |
| `device_set_white_levels` | 在RGBW或双色温调光器上设置暖/冷白光水平和/或色温。所有三个键（白光、白光2、开尔文温度）都是可选的，但至少必须提供一个。白光水平为0-100；温度通常为2000-6500K。 |
| `device_status_request` | 请求设备硬件刷新其在印第哥的状态 - 当设备的显示状态看起来陈旧时使用。 |
| `device_toggle' | 将设备切换为开启和关闭。可选延迟和持续时间（秒数，直到它切换回来）。 |
| `device_turn_off` | 按ID关闭设备。可选延迟（秒前）和持续时间（秒后重新开启）。 |
| `device_turn_on` | 按ID打开设备。可选延迟（秒前）和持续时间（秒后关闭）。 |
| `device_unlock` | 解锁锁定设备。可选延迟和自动锁定持续时间。 |
| `thermostat_set_cool_setpoint` | 设置恒温器的冷却设定点。温度单位遵循恒温器自己的配置（°F或°C）；印第哥处理转换。 |
| `thermostat_set_fan_mode` | 设置恒温器的风扇模式。接受友好名称（不区分大小写，空格/下划线忽略）：自动，始终开启（或“始终开启”/“始终打开”）。 |
| `thermostat_set_heat_setpoint` | 设置恒温器的加热设定点。温度单位遵循恒温器的配置（°F或°C）；印第哥处理转换。 |
| `thermostat_set_hvac_mode` | 设置恒温器的HVAC模式。接受友好名称（不区分大小写）：关闭，制热，制冷，自动（= 制热冷却），制热冷却，程序加热，程序制冷，程序加热冷却。 |
| `variable_create` | 创建新的印第哥变量。返回新变量的ID、名称、值和文件夹。印第哥变量值在传输过程中为字符串；数字/布尔调用者必须在调用前自行序列化。空值是允许的。 |
| `variable_delete` | 删除印第哥变量ID。永久 - 在删除您创建的所有内容之前，请与用户确认依赖项（触发器/控制页面引用它）。 |
| `variable_move_to_folder` | 将变量移动到文件夹（参见list_variable_folders）。 |
| `variable_update` | 更新现有印第哥变量的值。空值会清除变量。 |
### 系统工具（5）
| 工具 | 描述 |
|------|-------------|
| `get_plugin_by_id` | 按ID返回具有完整元数据和实时启用/运行/安装标志的单个插件。如果ID未安装，则引发异常。 |
| `get_plugin_status` | 返回单个插件的实时状态标志（启用/运行/安装）。比get_plugin_by_id便宜，用于轮询式健康检查，不需要静态元数据。 |
| `list_plugins` | 列出每个已安装的印第哥插件，包含ID、显示名称、版本、安装路径和实时启用/运行/安装标志。由于枚举和查找之间的安装/卸载竞争（罕见），消失的插件将被默默跳过。 |
| `query_event_log` | 从印第哥的实时事件日志中读取条目。 ``limit`` （默认50，最大500）限制获取的条目数量。 ``since`` （可选的ISO 8601日期时间）过滤到严格在该时间之后的条目 - 不可解析的时间戳在since过滤下被丢弃。 ``level`` （可选INFO / WARNING / ERROR）通过匹配已知的消息前缀来近似严重程度； INFO默认匹配所有内容。 |
| `restart_plugin` | 重启印第哥插件ID。拒绝重启自身（com.simons-plugins.indigo-mcp-lite） - 自我重启会杀死正在进行的MCP请求，响应中途，调用者会看到传输错误，而不是干净的工具结果。改为通过印第哥的UI重启此插件。 |
### 搜索工具（1）
| 工具 | 描述 |
|------|-------------|
| `find_devices` | 通过SQLite FTS5对印第哥设备、变量和动作组进行自然语言搜索。自由文本查询匹配名称 + 描述 + 文件夹 + 类型别名（因此“light”查找调光器，“leak”查找漏水传感器等）。可选筛选器：'room'（文件夹名称，不区分大小写）、'type'（deviceTypeId精确匹配 - 仅适用于设备）、'entity_type'（字符串或设备/变量/动作组列表）。分页通过'limit'（默认50，最大500）和'offset'。 |
<!-- END TOOL TABLE -->
要重新生成表格，请从活动注册表：`python3 scripts/generate_tool_doc.py`。单一真实来源是`tool_registry.register_all` - 将工具添加到任何`tools/*.py`模块会自动出现在下一次重新生成中。
## 搜索行为
`find_devices`在插件启动时索引每个设备、变量和动作组，然后通过印第哥的变更订阅回调保持索引实时。静态字段更改（重命名、移动文件夹、编辑描述）会触发逐行重新索引；状态变化（亮度、传感器读数、变量值翻转）不会 - 在1,891个实体安装中每分钟约1次重新索引。
FTS5模式索引名称、描述、类型标签、文件夹和精选的类型别名列表（因此 `"light"` 找到任何 `deviceTypeId` 属于调光器家族的设备，即使设备本身并未命名为“light”）。bm25权重偏爱名称匹配（3.0）>别名匹配（2.0）>文件夹/描述（1.0-1.5）。完整的别名列表在 [`type_aliases.py`](Indigo%20MCP%20Lite.indigoPlugin/Contents/Server%20Plugin/type_aliases.py) - 添加条目是一行代码的更改。
## 验证它是否有效
配置克劳德后，询问：
> “使用indigo-mcp-lite，在厨房里找到所有调光器。”
克劳德应该使用 `find_devices` 调用 `query="kitchen"`、`type="dimmer"`（或类似）并返回匹配的设备。如果您看到 `Server disconnected` 错误或命名空间未出现，请检查上面的 [配置注意事项](#%E9%87%8D%E8%A6%81%E9%85%8D%E7%BD%AE%E6%CE%AA%E9%A1%B5)。
## 架构
- **MCP传输**：从姐妹插件[Home Intelligence](https://github.com/simons-plugins/indigo-home-intelligence)直接复制的JSON-RPC 2.0调度程序 - 支持2025-11-25和2025-06-18版MCP协议。
- **工具曲面**：每个工具组位于`tools/<group>.py`并通过`tool_registry.register_all`注册。添加新的工具族是一个文件的操作。
- **索引**：`indexer.py`通过`plugin.py`上的更改订阅回调，在内存中维护SQLite FTS5表，跨`indigo.devices` / `indigo.variables` / `indigo.actionGroups`。
- **生产环境中没有pip依赖项。** `pytest`是唯一测试时间依赖项。
## 开发
```bash
git clone https://github.com/simons-plugins/indigo-mcp-lite
cd indigo-mcp-lite
# 运行测试套件（~1秒）
/Library/Frameworks/Python.framework/Versions/3.11/bin/pytest tests/ -q
# 重新生成README的工具表
python3 scripts/generate_tool_doc.py
```
欢迎贡献 - 将小同义词添加到`type_aliases.py`尤其宝贵。
## 许可证
MIT - 参见 [LICENSE](LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器