Smart Bulb MCP Server

Node.js와 TypeScript로 구축된 Model Context Protocol(MCP) 서버로, IP를 통해 스마트 전구를 제어합니다. 지원 기능:

• 모의/시뮬레이션 전구: 실제 하드웨어 없이 로컬 테스트 및 개발을 위한 기능입니다.

• Yeelight/Xiaomi 전구: 표준 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. 실행 / 개발

표준 I/O(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, 필수): 켜려면 ON 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

hex 색상 코드를 사용하여 전구의 색상을 설정합니다.

• 인자:

  • hex (string, 필수): Hex 코드 (예: "#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)과 상태 형태(BulbState)를 정의합니다.

• src/bulb/mock.ts: 메모리 내에서 네트워크 지연과 상태 변경을 모사하는 시레이션 전구 인스턴스입니다.

• src/bulb/yeelight.ts: 제3자 SDK 의존 없이 물리 Yeelight WiFi 전구과 JSON-RPC 패킷을 직접 주고 받기 위한 수동 TCP 라인 기반 버퍼 파서를 구현합니다.

• src/index.ts: @modelcontextprotocol/server 도구를 구성하고 마운트하며 연결 상태와 유효성 검사 스키마를 처리합니다.

• src/openai-client.ts: MCP 서버를 하위 프로세스로 실행하고, 모든 도구를 동적으로 로드하여 OpenAI 함수로 노출하며, 다중 턴 대화형 도구 실행 루프를 처리합니다.

만든 이: Palwinder Singh