# Smart Bulb MCP Server

A Model Context Protocol (MCP) server built with **Node.js** and **TypeScript** to control smart bulbs over IP. It supports:
- **Mock/Simulated Bulb**: For local testing and development without physical hardware.
- **Yeelight/Xiaomi Bulb**: Uses standard TCP port `55443` (local control JSON-RPC protocol) to control real physical smart bulbs.

## Features

- **Connect using IP**: Dynamically connect to different bulbs on your local network.
- **Power Control**: Turn the bulb on or off.
- **Brightness & Opacity**: Adjust bulb brightness / intensity from 1% to 100%.
- **Color Control**: Set colors using RGB coordinates or hexadecimal color codes.
- **State Queries**: Fetch the current state of the bulb in real-time.

---

## Getting Started

### 1. Build the Server

First, install the dependencies and compile the TypeScript files:

```bash
# Install dependencies
npm install

# Compile the TypeScript files
npm run build
```

The compiled files will be output to the `dist/` directory.

### 2. Run / Development

You can run the server directly via standard I/O (Stdio):

```bash
# Run the built JS
npm start

# Compile and run in development mode
npm run dev
```

---

## Configuring with MCP Clients

To use this server with an MCP client (such as Claude Desktop or Cursor), add the server configuration to your configuration file.

### For Claude Desktop

Edit your `claude_desktop_config.json` (typically located in `%APPDATA%\Claude` on Windows or `~/Library/Application Support/Claude` on macOS):

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

*Note: Replace `D:/Palwinder/mcp-server-bulb/dist/index.js` with the absolute path to `dist/index.js` on your machine.*

---

## Exposed MCP Tools

Once the server is connected, the host LLM will have access to the following tools:

### 1. `connect_bulb`
Connects to a bulb at a specified IP.
- **Arguments**:
  - `ip` (string, required): IP address (e.g. `"192.168.1.15"` or `"127.0.0.1"`).
  - `type` (enum `["mock", "yeelight"]`, default: `"mock"`): Driver type. Use `"mock"` to test the server features without physical hardware, or `"yeelight"` for real Yeelight bulbs.
  - `port` (number, optional): Port to use. Defaults to `55443` for Yeelight, and `9999` for Mock.

### 2. `disconnect_bulb`
Disconnects from the currently connected bulb.
- **Arguments**: None.

### 3. `get_bulb_state`
Retrieves the connection status, power state, brightness/opacity percentage, and RGB color.
- **Arguments**: None.

### 4. `set_bulb_power`
Turns the light bulb ON or OFF.
- **Arguments**:
  - `power` (boolean, required): `true` to turn ON, `false` to turn OFF.

### 5. `set_bulb_brightness`
Sets the bulb's brightness / opacity.
- **Arguments**:
  - `brightness` (number, required): Values from `1` to `100`.

### 6. `set_bulb_color_rgb`
Sets the color of the bulb using RGB values.
- **Arguments**:
  - `r` (number, required): Red component `0` - `255`.
  - `g` (number, required): Green component `0` - `255`.
  - `b` (number, required): Blue component `0` - `255`.

### 7. `set_bulb_color_hex`
Sets the color of the bulb using a hex color code.
- **Arguments**:
  - `hex` (string, required): Hex code (e.g., `"#FF0000"` or `"00FF00"`).

---

## OpenAI Connection Client

We have built a client wrapper in `src/openai-client.ts` that allows you to feed prompts directly to OpenAI. OpenAI will then autonomously invoke the MCP tools to perform the actions on your smart bulb.

### Setup and Running the Client

1. **Set your OpenAI API Key**:
   On Windows (PowerShell):
   ```powershell
   $env:OPENAI_API_KEY="your-actual-api-key"
   ```
   On macOS/Linux (Bash):
   ```bash
   export OPENAI_API_KEY="your-actual-api-key"
   ```

2. **Run the Client**:
   - **Interactive CLI mode**:
     ```bash
     npm run client
     ```
     This opens a shell prompt. Try typing:
     > *Connect to the mock bulb, turn it on, set its brightness to 80% and color to yellow.*
     
   - **One-off command mode**:
     Pass your prompt directly as arguments:
     ```bash
     npm run client -- "connect to the mock bulb, turn it on, and set color to blue"
     ```

3. **Customizing the Model (Optional)**:
   By default, it uses `gpt-4o-mini`. You can change it by setting the `OPENAI_MODEL` environment variable:
   ```powershell
   $env:OPENAI_MODEL="gpt-4o"
   ```

---

## Developer Details & Architecture

The project has a modular architecture:
- [`src/bulb/interface.ts`](src/bulb/interface.ts): Defines the common contract (`ISmartBulb`) and state shape (`BulbState`).
- [`src/bulb/mock.ts`](src/bulb/mock.ts): Simulated bulb instance that mimics network latency and state changes in memory.
- [`src/bulb/yeelight.ts`](src/bulb/yeelight.ts): Implements a raw TCP line-based buffer parser to send and receive JSON-RPC packets directly from physical Yeelight WiFi bulbs without any third-party SDK dependencies.
- [`src/index.ts`](src/index.ts): Configures and mounts the `@modelcontextprotocol/server` tools, handling connection states and validation schemas.
- [`src/openai-client.ts`](src/openai-client.ts): Launches the MCP server as a subprocess, loads all its tools dynamically, exposes them as OpenAI Functions, and handles the multi-turn conversational tool execution loop.

---

**Built by [Palwinder Singh](https://github.com/PalwinderSinghPaali)**