# iotforge

An [MCP](https://modelcontextprotocol.io/) server for discovering and controlling IoT devices on your local network and via Bluetooth LE.

## What it does

**iotforge** exposes your LAN and BLE devices as MCP tools so any MCP-compatible AI assistant can:

- **Discover** devices on your local network (mDNS, ARP) and Bluetooth LE
- **Register** discovered devices into a persistent inventory
- **Control** devices through adapter plugins (smart plugs, BLE lights, etc.)
- **Query** device status and inventory via MCP resources

## Architecture

```
MCP Client (Claude, etc.)
    │
    ▼
┌─────────────────────────────┐
│  iotforge MCP Server        │
│  (stdio or SSE transport)   │
├─────────────────────────────┤
│  Tools: discover, register, │
│         control, status     │
│  Resources: inventory,      │
│             pending         │
├─────────────────────────────┤
│  Core: Scanner, Registry,   │
│        Discovery Service    │
├─────────────────────────────┤
│  Adapters: Meross, BLE      │
│  Database: SQLite (async)   │
└─────────────────────────────┘
    │               │
    ▼               ▼
  LAN/mDNS       BLE/GATT
```

## MCP Tools

| Tool | Description |
|------|-------------|
| `lan_discover` | Scan WiFi/LAN and BLE for devices |
| `lan_discover_pending` | List devices awaiting registration |
| `lan_device_register` | Promote a pending device to the registry |
| `lan_pending_dismiss` | Dismiss a pending device |
| `lan_device_list` | List registered devices with filters |
| `lan_device_control` | Send a command to a device |
| `lan_device_status` | Get current device status |

## MCP Resources

| Resource | Description |
|----------|-------------|
| `devices://inventory` | Full device inventory (markdown) |
| `devices://pending` | Pending devices (markdown) |

## Installation

```bash
pip install -e ".[all]"
```

Optional extras: `meross` (Meross smart plugs), `ble` (Bluetooth LE via bleak).

## Configuration

Copy `config.example.yaml` and edit:

```bash
cp config.example.yaml config.yaml
```

Key settings: network range, scan intervals, transport mode (stdio/SSE), database path.

## Usage

### With Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "iotforge": {
      "command": "iotforge",
      "args": ["config.yaml"]
    }
  }
}
```

### Standalone (SSE mode)

```bash
iotforge config.yaml
```

Set `server.transport: sse` in your config to expose an HTTP endpoint.

## BLE Scripts

The `scripts/` directory contains standalone BLE utilities:

- **`elk_ble_ctl.py`** — GATT controller for ELK-BLEDDM LED strips (service 0xFFF0)
- **`lampsmart_pro.py`** — BLE ADV broadcast controller for LampSmart Pro ceiling lights (multiple protocol versions)
- **`ble_adv_sniffer.py`** — Raw HCI BLE advertisement sniffer for protocol discovery

## Adapters

iotforge uses a plugin adapter system. Built-in adapters:

- **meross** — Meross smart plugs/switches (requires `meross-iot`)
- **ble_light** — BLE GATT light control (requires `bleak`)

Custom adapters implement the `BaseAdapter` interface in `src/iotforge/adapters/base.py`.

## Development

```bash
pip install -e ".[dev]"
ruff check .
python -m pytest --cov=iotforge
```

## License

MIT — see [LICENSE](LICENSE).