# mcp-kr-controller

MCP (Model Context Protocol) server for KR-series relay controllers. Connect your hardware controllers to AI through serial/UART, TCP, or UDP — zero configuration, conversational discovery.

## Features

- **Conversational Architecture** — No config file needed. Tell the AI your connection type, it handles the rest.
- **Multi-Transport** — Serial (UART 9600 8N1), TCP, UDP with unified transport abstraction.
- **Auto Discovery** — Broadcast scan finds all connected devices, queries I/O channels and function modules, registers automatically.
- **State Persistence** — Device connections and registrations saved to `state.json`, auto-restored on restart.
- **23 MCP Tools** — Auto discovery, device scanning, status query, relay control, PLC advanced control, animations, DI trigger automation.
- **Fire-and-Forget** — Control commands return instantly without waiting for hardware response.

## Quick Start

### Install

```bash
npm install -g mcp-kr-controller
# or use directly without install
npx mcp-kr-controller
```

### Configure in your MCP client

Add to your MCP client config (e.g. Claude Desktop `claude_desktop_config.json`, WorkBuddy `mcp.json`):

```json
{
  "mcpServers": {
    "kr-controller": {
      "command": "npx",
      "args": ["mcp-kr-controller"],
      "type": "stdio"
    }
  }
}
```

Or if installed globally:

```json
{
  "mcpServers": {
    "kr-controller": {
      "command": "mcp-kr-controller",
      "type": "stdio"
    }
  }
}
```

### Usage Flow

1. **Confirm connection type** — Tell the AI: "Search for devices"
   - AI will ask: "串口还是网络？" (Serial or Network?)
2. **Network** — AI calls `auto_discover(connection_type="network")`
   - Auto-tries V4 TCP `192.168.16.254:8080` and V5 UDP broadcast `192.168.1.255:8080`
   - Multi-NIC: auto-matches local NIC to the same subnet (255.255.255.0)
   - Devices found are automatically registered with I/O config
3. **Serial** — AI asks for COM port, then calls `auto_discover(connection_type="serial", path="COM3")`
   - Connects via RS-485 at 9600 baud, scans and registers devices
4. **Control** — Say "Turn on channel 3 of device 1" — AI handles the rest

**If default addresses don't match your network**, use `setup_connection` with manual config.

> **Multi-NIC Note**: The V5 UDP discovery automatically selects the local NIC matching the target subnet (255.255.255.0). If you have multiple network cards, make sure the controller is on the same subnet as one of them.

## Hardware Support

Two hardware versions, three transport modes — all share the same control protocol.

| Version | Transport | Product Line |
|---------|-----------|--------------|
| **V5** | TCP / UDP (network) | 8DI, 8DI+8DO, 12DI+8DO, 2DI+9DO, 16DI, 16DO |
| **V4** | RS-485 serial, TCP/UDP transparent | Various I/O configurations |

Tested configurations (as of 2026-07-30):

| Device | Ver | I/O | Transport | Status |
|--------|-----|-----|-----------|--------|
| #1 | V5 | 12DI+8DO | UDP broadcast | Verified |
| #1 | V4 | 16DO | TCP transparent | Verified |
| #21 | V4 | 8DI+8DO | RS-485 COM3 | Verified |

### Environment Variables (optional)

| Variable | Description |
|----------|-------------|
| `KR_SERIAL_PATH` | Serial port path (e.g. `COM3`, `/dev/ttyUSB0`) |
| `KR_TCP_HOST` | TCP host |
| `KR_TCP_PORT` | TCP port (default 8080) |
| `KR_UDP_HOST` | UDP host |
| `KR_UDP_PORT` | UDP port (default 8080) |

## Protocol

KR-series controllers use an 8-byte fixed-length frame protocol over UART (9600 bps, 8N1):

```
| Header | Address | Command | Data0 | Data1 | Data2 | Data3 | Checksum |
|  1 byte | 1 byte  | 1 byte  | 1 byte | 1 byte | 1 byte | 1 byte | 1 byte   |
```

- **Header**: `0x55` (request) / `0x22` (response)
- **Address**: `0x00`/`0xFF` (broadcast) or `0x01`–`0xFE` (device address 1-254)
- **Checksum**: `sum(byte[0..6]) & 0xFF`

### Supported Commands

| Code | Function |
|------|----------|
| 0x21 | Find devices (broadcast) |
| 0x2D | Query device properties (I/O count, modules) |
| 0x10 | Read status (DI + relay) |
| 0x11 | Disconnect one relay |
| 0x12 | Connect one relay |
| 0x13 | Set relays by bitmask |
| 0x06/0x08 | Momentary on/off (by mask) |
| 0x09/0x18 | Momentary on/off (single channel) |
| 0x07/0x17 | Blink (single/multi) |
| 0x14/0x15/0x16 | Group disconnect/connect/toggle |

## MCP Tools

### Connection Management
- `setup_connection` — Establish serial/TCP/UDP connection
- `list_connections` — List active connections
- `remove_connection` — Remove a connection

### Device Discovery
- `scan_devices` — Broadcast scan + auto-register devices
- `list_devices` — Show registered devices

### Status & Query
- `read_status` — Read DI inputs + relay outputs
- `get_function_modules` — Query function module bitmask

### Basic Control
- `connect_relay` — Connect (energize) one relay
- `disconnect_relay` — Disconnect (de-energize) one relay
- `set_relays_by_mask` — Set all relays by bitmask
- `all_relays_on` / `all_relays_off` — All relays on/off

### Advanced Control
- `momentary_on_off_single` / `momentary_off_on_single` — Momentary action (single channel)
- `momentary_on_off_multi` / `momentary_off_on_multi` — Momentary action (by mask)
- `blink_single` / `blink_multi` — Blink relay(s)
- `group_connect` / `group_disconnect` / `group_toggle` — Group operations

### Animation Test
- `ping_pong` — Ping-pong bounce animation with configurable delay

### Event Trigger
- `wait_di_trigger` — Monitor DI channel, execute action on rising edge

## Development

```bash
# Clone
git clone https://github.com/kinbeg/mcp-kr-controller.git
cd mcp-kr-controller

# Install dependencies
npm install

# Build
npm run build

# Run in dev mode
npm run dev
```

## Purchase

KR-series controllers are available at the official store:

[kinbeg.taobao.com](http://kinbeg.taobao.com)

## License

MIT