Smart Bulb MCP Server

Node.js と TypeScript で構築された Model Context Protocol (MCP) サーバーで、IP 経由でスマート電球を制御します。以下に対応しています：

• Mock/Simulated Bulb: 物理的なハードウェアなしでローカルのテストと開発を行うためのシミュレーション電球です。

• Yeelight/Xiaomi Bulb: 標準 TCP ポート 55443（ローカル制御 JSON-RPC プロトコル）を使用して、実際の物理的なスマート電球を制御します。

機能

• IP を使用した接続: ローカルネットワーク上のさまざまな電球に動的に接続できます。

• 電源制御: 電球をオンまたはオフにします。

• 明るさと不透明度: 電球の明るさ / 強度を 1% から 100% の範囲で調整します。

• 色の制御: RGB 座標または16進数のカラーコードを使用して色を設定します。

• 状態クエリ: 電球の現在の状態をリアルタイムで取得します。

Related MCP server: Philips Hue MCP Service

はじめに

1. サーバーのビルド

まず、依存関係をインストールして TypeScript ファイルをコンパイルします：

# Install dependencies
npm install

# Compile the TypeScript files
npm run build

コンパイルされたファイルは dist/ ディレクトリに出力されます。

2. 実行 / 開発

標準入出力（Stdio）経由でサーバーを直接実行できます：

# Run the built JS
npm start

# Compile and run in development mode
npm run dev

MCP クライアントでの設定

このサーバーを MCP クライアント（Claude Desktop や Cursor など）で使用するには、設定ファイルにサーバー設定を追加してください。

Claude Desktop の場合

claude_desktop_config.json を編集します（通常、Windows では %APPDATA%\Claude、macOS では ~/Library/Application Support/Claude にあります）：

{
  "mcpServers": {
    "smart-bulb": {
      "command": "node",
      "args": ["D:/Palwinder/mcp-server-bulb/dist/index.js"]
    }
  }
}

注：D:/Palwinder/mcp-server-bulb/dist/index.js は、お使いのマシン上の dist/index.js への絶対パスに置き換えてください。

公開されている MCP ツール

サーバーが接続されると、ホストの LLM は以下のツールにアクセスできるようになります：

1. connect_bulb

指定した IP の電球に接続します。

• 引数:

  • ip（string、必須）: IP アドレス（例: "192.168.1.15" または "127.0.0.1"）。

  • type（enum ["mock", "yeelight"]、デフォルト: "mock"）: ドライバーの種類です。物理的なハードウェアなしでサーバーの機能をテストするには "mock" を、実際の Yeelight 電球には "yeelight" を使用します。

  • port（number、任意）: 使用するポートです。Yeelight のデフォルトは 55443、Mock のデフォルトは 9999 です。

2. disconnect_bulb

現在接続されている電球から切断します。

• 引数: なし。

3. get_bulb_state

接続ステータス、電源状態、明るさ / 不透明度のパーセンテージ、RGB カラーを取得します。

• 引数: なし。

4. set_bulb_power

電球をオンまたはオフにします。

• 引数:

  • power（boolean、必須）: オンにするには true、オフにするには false を指定します。

5. set_bulb_brightness

電球の明るさ / 不透明度を設定します。

• 引数:

  • brightness（number、必須）: 1 から 100 までの値です。

6. set_bulb_color_rgb

RGB の値を使用して電球の色を設定します。

• 引数:

  • r（number、必須）: 赤の成分 0 - 255。

  • g（number、必須）: 緑の成分 0 - 255。

  • b（number、必須）: 青の成分 0 - 255。

7. set_bulb_color_hex

16 進数のカラーコードを使用して電球の色を設定します。

• 引数:

  • hex（string、必須）: 16 進数のコードです（例: "#FF0000" または "00FF00"）。

OpenAI 接続クライアント

src/openai-client.ts に、OpenAI にプロンプトを直接渡すためのクライアントラッパーを構築しました。OpenAI は MCP ツールを自律的に呼び出して、スマート電球に対してアクションを実行します。

クライアントのセットアップと実行

1. OpenAI API キーを設定する： Windows（PowerShell）の場合：

   $env:OPENAI_API_KEY="your-actual-api-key"

   macOS/Linux（Bash）の場合：

   export OPENAI_API_KEY="your-actual-api-key"

2. クライアントを実行する：

   • 対話型 CLI モード：

     npm run client

     シェルのプロンプトが開きます。次のようにお試しください：

     モック電球に接続し、電源をオンにして、明るさを 80% に設定し、色を黄色に変更してください。

   • 単発コマンドモード： プロンプトを引数として直接渡します：

     npm run client -- "connect to the mock bulb, turn it on, and set color to blue"

3. モデルのカスタマイズ（任意）: デフォルトでは gpt-4o-mini を使用します。OPENAI_MODEL 環境変数を設定することで変更できます：

   $env:OPENAI_MODEL="gpt-4o"

開発者の詳細 & アーキテクチャ

このプロジェクトはモジュール構造になっています：

• src/bulb/interface.ts: 共通のコントラクト（ISmartBulb）と 状態 のshape（BulbState）を定義します。

• src/bulb/mock.ts: ネットワークの遅延とメモリ内の状態変化を模擬するシミュレーション電球インスタンスです。

• src/bulb/yeelight.ts: サードパーティーの SDK に依存せず、実際の Yeelight WiFi 電球との間で JSON-RPC パケットを直接送受信するための、生の TCP ラインベースのバッファパーサーを実装しています。

• src/index.ts: @modelcontextprotocol/server ツールを設定してマウントし、接続状態と検証スキーマを処理します。

• src/openai-client.ts: MCP サーバーをサブプロセスとして起動し、すべてのツールを動的に読み込んで OpenAI 関数として公開し、マルチターンの会話型ツール実行ループを処理します。

Palwinder Singh によって作成されました