Bond MCP Server

🚀 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令牌

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

添加到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"
      ]
    }
  }
}

📦 安装指南

1. 创建并激活虚拟环境：

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

2. 安装依赖项：

   pip install -r requirements.txt
   

3. 配置环境：

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

4. 运行服务器：

   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文档

🔧 技术细节

故障排除

常见问题

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

调试日志记录

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

📄 许可证

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