# mcp-kr-controller

**Repository Path**: kinbeg/mcp-kr-controller

## Basic Information

- **Project Name**: mcp-kr-controller
- **Description**: 用于AI驱动KR系列V4、V5控制器的MCP
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-31
- **Last Updated**: 2026-08-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# mcp-kr-controller

KR 系列控制器的 MCP（Model Context Protocol）服务端。通过串口/UART、TCP 或 UDP 将自研硬件控制器接入 AI，零配置、对话式发现，AI 直接驱动物理设备。

## 特性

- **对话式架构** — 无需配置文件。告诉 AI 你的连接方式（串口还是网络），其余自动处理。
- **多传输层** — 串口（UART 9600 8N1）、TCP、UDP，统一传输抽象层。
- **自动发现** — 广播扫描发现所有在线设备，自动查询 I/O 通道数和功能模块，自动注册。
- **状态持久化** — 设备连接和注册信息保存至 `state.json`，重启自动恢复。
- **23 个 MCP 工具** — 自动发现、设备扫描、状态查询、继电器控制、PLC 高级控制、动画效果、DI 事件触发。
- **发后即忘** — 控制指令瞬时发送，无需等待硬件应答。

## 快速开始

### 安装

```bash
npm install -g mcp-kr-controller
# 或无需安装，直接使用
npx mcp-kr-controller
```

### 配置 MCP 客户端

将以下配置添加到 MCP 客户端（如 WorkBuddy 的 `mcp.json`、Claude Desktop 的 `claude_desktop_config.json`）：

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

全局安装后也可以直接调用：

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

### 使用流程

1. **确认连接方式** — 对 AI 说："搜索设备"
   - AI 会询问："串口还是网络？"
2. **网络** — AI 调用 `auto_discover(connection_type="network")`
   - 自动依次尝试 V4 TCP 默认地址 `192.168.16.254:8080` 和 V5 UDP 广播默���地址 `192.168.1.255:8080`
   - 多网卡：自动匹配同网段本地网卡（子网掩码 255.255.255.0）
   - 发现的设备自动注册 I/O 配置
3. **串口** — AI 询问 COM 口号，然后调用 `auto_discover(connection_type="serial", path="COM3")`
   - 通过 RS-485 总线（9600 波特率）连接、扫描并注册设备
4. **控制** — 说"1号设备第3路吸合" — AI 自动完成

> **如果默认地址与你的网络不匹配**，可使用 `setup_connection` 手动指定连接参数。

> **多网卡提示**：V5 UDP 广播搜索会自动选择与目标地址同一子网（255.255.255.0）的本地网卡。如有多张网卡，请确保控制器与其中一张在同一网段。

## 硬件支持

两个硬件版本，三种通讯方式 — 控制协议完全通用。

| 版本 | 通讯方式 | 产品线 |
|------|----------|--------|
| **V5** | TCP / UDP（网络版） | 8DI, 8DI+8DO, 12DI+8DO, 2DI+9DO, 16DI, 16DO |
| **V4** | RS-485 串口 / TCP / UDP 透传 | 多种 I/O 配置 |

实测验证配置（截至 2026-07-30）：

| 设备 | 版本 | I/O | 通讯方式 | 状态 |
|------|------|-----|----------|------|
| 1号 | V5 | 12DI+8DO | UDP 广播 | ✅ 已验证 |
| 1号 | V4 | 16DO | TCP 透传 | ✅ 已验证 |
| 11号 | V4 | 8DI+8DO | RS-485 串口 | ✅ 已验证 |
| 21号 | V4 | 8DI+8DO | RS-485 串口 | ✅ 已验证 |

### 环境变量（可选）

| 变量 | 说明 |
|------|------|
| `KR_SERIAL_PATH` | 串口路径（如 `COM3`、`/dev/ttyUSB0`） |
| `KR_TCP_HOST` | TCP 主机地址 |
| `KR_TCP_PORT` | TCP 端口（默认 8080） |
| `KR_UDP_HOST` | UDP 主机地址 |
| `KR_UDP_PORT` | UDP 端口（默认 8080） |

## 通信协议

KR 系列控制器采用 8 字节定长帧协议，通过 UART 通信（9600 bps，8N1）：

```
| 帧头 | 地址 | 功能码 | 数据0 | 数据1 | 数据2 | 数据3 | 校验和 |
| 1字节 | 1字节 | 1字节 | 1字节 | 1字节 | 1字节 | 1字节 | 1字节  |
```

- **帧头**：`0x55`（请求）/ `0x22`（应答）
- **地址**：`0x00`/`0xFF`（广播）或 `0x01`–`0xFE`（设备地址 1-254）
- **校验和**：`sum(byte[0..6]) & 0xFF`

### 支持的命令

| 功能码 | 功能 |
|--------|------|
| 0x21 | 查找设备（广播） |
| 0x2D | 查询设备属性（I/O 数量、功能模块） |
| 0x10 | 读取状态（DI 输入 + 继电器输出） |
| 0x11 | 断开一路继电器 |
| 0x12 | 吸合一路继电器 |
| 0x13 | 按位掩码设置继电器 |
| 0x06/0x08 | 点动（按位掩码） |
| 0x09/0x18 | 点动（单路） |
| 0x07/0x17 | 闪烁（单路/多路） |
| 0x14/0x15/0x16 | 组断开/吸合/翻转 |

## MCP 工具列表

### 连接管理
- `setup_connection` — 建立串口/TCP/UDP 连接
- `list_connections` — 列出当前连接
- `remove_connection` — 移除连接

### 设备发现
- `auto_discover` — 一键自动发现（先确认连接方式，再依次尝试默认地址）
- `scan_devices` — 广播扫描 + 自动注册设备
- `list_devices` — 显示已注册设备

### 状态查询
- `read_status` — 读取 DI 输入 + 继电器输出状态
- `get_function_modules` — 查询功能模块位掩码

### 基础控制
- `connect_relay` — 吸合一路继电器
- `disconnect_relay` — 断开一路继电器
- `set_relays_by_mask` — 按位掩码设置全部继电器
- `all_relays_on` / `all_relays_off` — 全部吸合/断开

### 高级控制
- `momentary_on_off_single` / `momentary_off_on_single` — 点动（单路）
- `momentary_on_off_multi` / `momentary_off_on_multi` — 点动（按位掩码）
- `blink_single` / `blink_multi` — 闪烁（单路/多路）
- `group_connect` / `group_disconnect` / `group_toggle` — 组操作

### 动画测试
- `ping_pong` — 乒乓球弹跳动画，可配置帧间隔时间

### 事件触发
- `wait_di_trigger` — 监控 DI 通道，上升沿时自动执行动作

## 开发

```bash
# 克隆仓库
git clone https://github.com/kinbeg/mcp-kr-controller.git
cd mcp-kr-controller

# 安装依赖
npm install

# 编译
npm run build

# 开发模式运行
npm run dev

# 运行单元测试
npm test
```

## 硬件购买渠道

KR 系列控制器可通过官方店铺购买：

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

## 许可证

MIT