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文件。