金大哥 - bond-mcp-server MCP 详情

article

README

🚀 Bond MCP Server

Bond MCP Server是一个模型上下文协议（MCP）服务器，它提供了用于控制Bond Bridge智能家居设备的工具。该服务器使Claude等AI助手能够通过Bond Bridge集线器与吊扇、壁炉、遮阳帘、灯光和其他射频控制设备进行交互。

✨ 主要特性

设备管理：列出并获取所有已连接的Bond设备的信息
风扇控制：控制吊扇的速度、方向和电源状态
遮阳帘控制：打开、关闭电动遮阳帘并设置其位置
灯光控制：控制可调光灯光及其亮度级别
自定义操作：向设备发送任何Bond API操作
桥接信息：获取Bond Bridge的状态和配置

🚀 快速开始

前提条件

本地网络中的Bond Bridge
Bond API令牌（可从Bond Home应用程序获取）

获取Bond令牌

在移动设备上打开Bond Home应用程序
转到“设置”→“Bond Bridge”→“高级”→“API”
复制本地令牌（而非云令牌）

添加到MCP设置中：

{
  "mcpServers": {
    "bond": {
      "command": "podman",
      "args": [
        "run", "-i", "--rm",
        "-e", "BOND_TOKEN=your_token_here",
        "-e", "BOND_HOST=192.168.1.100",
        "quay.io/madorn/bond-mcp-server:latest"
      ]
    }
  }
}

📦 安装指南

创建并激活虚拟环境：

python3 -m venv bond-mcp-env
source bond-mcp-env/bin/activate  # 在Windows上：bond-mcp-env\Scripts\activate

安装依赖项：
```
pip install -r requirements.txt
```

配置环境：

cp .env.example .env
# 使用你的Bond Bridge设置编辑.env文件

运行服务器：
```
python -m bond_mcp.server
```

配置

创建一个包含Bond Bridge配置的.env文件：

# 必需：Bond Bridge设置
BOND_TOKEN=your_bond_api_token_here
BOND_HOST=192.168.1.100

# 可选：连接设置
BOND_TIMEOUT=10.0
BOND_MAX_RETRIES=3
BOND_RETRY_DELAY=1.0

# 可选：日志记录
LOG_LEVEL=INFO

💻 使用示例

基础用法

以下是一些使用该服务器提供的工具的基础示例：

# 列出所有Bond设备
from bond_mcp.server import list_devices
devices = list_devices()
print(devices)

# 获取特定设备的信息
from bond_mcp.server import get_device_info
device_info = get_device_info('device_id_here')
print(device_info)

高级用法

以下是一些高级场景下的使用示例：

# 发送自定义操作到设备
from bond_mcp.server import send_custom_action
result = send_custom_action('device_id_here', 'custom_action_name', 'optional_argument')
print(result)

# 设置风扇速度
from bond_mcp.server import set_fan_speed
set_fan_speed('device_id_here', 5)

📚 详细文档

可用工具

设备管理

list_devices() - 列出所有Bond设备
get_device_info(device_id) - 获取详细的设备信息
get_device_state(device_id) - 获取当前设备状态
get_bridge_info() - 获取Bond Bridge信息

设备控制

toggle_device_power(device_id) - 切换设备的电源开关
send_custom_action(device_id, action, argument?) - 发送自定义Bond操作

风扇控制

set_fan_speed(device_id, speed) - 设置风扇速度（0 - 8）
set_fan_direction(device_id, direction) - 设置风扇方向（“forward”/“reverse”）

遮阳帘控制

control_shades(device_id, action, position?) - 控制遮阳帘
- 操作：“open”、“close”、“set_position”
- 位置：0 - 100（用于“set_position”操作）

灯光控制

set_light_brightness(device_id, brightness) - 设置灯光亮度（0 - 100）

Bond API参考

此服务器使用Bond Local API v2：

基础URL：http://{bridge_ip}/v2/
身份验证：授权标头中的Bearer令牌
文档：Bond Local API文档

🔧 技术细节

故障排除

常见问题

连接被拒绝：确保Bond Bridge的IP地址正确且可访问
身份验证失败：验证Bond令牌是否正确（使用本地令牌，而非云令牌）
设备未找到：使用list_devices()检查设备ID是否存在
操作不支持：使用get_device_info()验证设备是否支持该操作

调试日志记录

通过在环境中设置LOG_LEVEL=DEBUG来启用调试日志记录。

📄 许可证

本项目采用MIT许可证。有关详细信息，请参阅LICENSE文件。

bond-mcp-server