# EtherCAT MCP Server

[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue.svg)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/MCP-Protocol%201.32-orange.svg)](https://modelcontextprotocol.io/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

面向工业自动化与机器人控制的 **EtherCAT Model Context Protocol (MCP)** 服务。让 Claude Code、Codex CLI、Antigravity、Cursor 等 AI 工具能够直接与 EtherCAT 现场总线交互，实现从站拓扑扫描、ESM 状态机调度、CoE (CANopen over EtherCAT) SDO 读写、PDO 周期过程数据交互、CiA 402 伺服运动控制以及总线健康诊断。

内置**高保真虚拟总线仿真器**，开箱即用，无需真实硬件或专用网卡权限即可完成全流程调试与闭环测试。

---

## 🌟 核心特性

- 🚀 **全面支持标准 ESM 状态机**：无缝调度总线与各从站的 `INIT`、`PRE-OP`、`BOOT`、`SAFE-OP`、`OP` 状态转换与 AL 错误复位。
- ⚡ **CoE 对象字典全功能支持**：任意读取/写入 SDO 索引与子索引（支持十六进制如 `0x6040`、`0x1018` 与十进制）。
- 🔄 **PDO 周期数据交互**：实时读取数字量/模拟量输入、伺服编码器位置与状态字；高速下发数字量输出与运动指令。
- 🦾 **内置 CiA 402 伺服驱动状态机**：提供高层运动控制工具（电机使能、停机、急停、故障复位、点动/位置定位、速度模式）。
- 🌐 **零门槛高仿真虚拟总线**：自带由倍福（Beckhoff）与汇川（Inovance）经典设备构成的 5 从站虚拟链路，离线即测。
- 🔌 **硬件网关无缝接入**：支持无缝对接原生 EtherCAT 主站后台（SOEM daemon / IgH EtherCAT Master / TwinCAT ADS 桥接）。

---

## 🏗️ 架构图

```
┌────────────────────────────────────────────────────────┐
│        AI Assistants (Claude / Codex / Antigravity)    │
└───────────────────────────┬────────────────────────────┘
                            │ MCP Protocol (stdio)
                            ▼
┌────────────────────────────────────────────────────────┐
│                   ethercat-mcp Server                  │
│       - 12 Native MCP Tools (ESM, SDO, PDO, CiA 402)   │
└─────────────┬────────────────────────────┬─────────────┘
              │ (Simulation Mode)          │ (Hardware Mode)
              ▼                            ▼
┌───────────────────────────┐  ┌─────────────────────────┐
│ Built-in Virtual Bus      │  │ Native Master Gateway   │
│ - EK1100 (Bus Coupler)    │  │ (SOEM / IgH / ADS)      │
│ - EL1008 (8-Ch DI)        │  └───────────┬─────────────┘
│ - EL2008 (8-Ch DO)        │              │ Ethernet Raw Socket
│ - EL3064 (4-Ch AI 0-10V)  │              ▼
│ - SV660N (CiA 402 Servo)  │  ┌─────────────────────────┐
└───────────────────────────┘  │ Real EtherCAT Slaves    │
                               └─────────────────────────┘
```

---

## 🛠️ MCP 工具列表 (Tools)

| 工具名称 | 功能描述 | 典型参数示例 |
|---|---|---|
| `scan_slaves` | 扫描总线上的所有从站设备并输出厂商、型号代码、固件版本、序列号及状态 | `{}` |
| `get_slave_info` | 查询特定从站的软硬件详情、CoE 对象字典映射及 PDO 配置 | `{"slaveIndex": 4}` |
| `get_topology` | 输出 EtherCAT 总线物理网线级联拓扑关系与端口链路状态 | `{}` |
| `get_esm_state` | 查询总线主站或指定从站的 ESM 当前状态与 AL 状态码 | `{"slaveIndex": 4}` |
| `set_esm_state` | 请求总线或特定从站执行状态迁移 (`INIT`/`PREOP`/`SAFEOP`/`OP`) | `{"targetState": "OP"}` |
| `read_sdo` | 读取 CoE 对象字典条目（支持十六进制索引） | `{"slaveIndex": 4, "index": "0x6041", "subIndex": 0}` |
| `write_sdo` | 向 CoE 对象字典写入参数值 | `{"slaveIndex": 4, "index": "0x6040", "subIndex": 0, "value": 15}` |
| `read_pdo` | 读取周期过程输入映像 (TxPDO: 数字量/模拟量/当前位置速度) | `{"slaveIndex": 1}` |
| `write_pdo` | 下发周期过程输出映像 (RxPDO: 继电器开闭/控制字/目标位置) | `{"slaveIndex": 2, "values": {"do1": true}}` |
| `get_diagnostics` | 获取总线通信质量报告（周期时间、抖动、丢包率、CRC 错误） | `{}` |
| `reset_error` | 复位从站 AL 报警及驱动器故障状态 | `{"slaveIndex": 4}` |
| `drive_control` | 高层 CiA 402 伺服电机控制快捷工具（使能/去使能/回零/定位） | `{"slaveIndex": 4, "action": "enable"}` |

---

## ⚡ 快速接入与配置

### 1. Claude Code
```bash
claude mcp add -s user ethercat -- npx -y ethercat-mcp
```

### 2. Codex CLI
```bash
codex mcp add ethercat -- npx -y ethercat-mcp
```

### 3. Claude Desktop
在 `claude_desktop_config.json` 中追加：
```json
{
  "mcpServers": {
    "ethercat": {
      "command": "npx",
      "args": ["-y", "ethercat-mcp"]
    }
  }
}
```

### 4. 真实硬件网关模式 (SOEM / TwinCAT ADS)
若要连接外部工业总线主站守护进程：
```bash
npx ethercat-mcp --hardware --endpoint=http://127.0.0.1:8088
```

---

## 🤖 典型 AI 交互示例

连接完成后，您可以直接在 AI 中输入自然语言：

- **扫描总线拓扑**：
  > “帮我扫描一下当前 EtherCAT 总线挂载了哪些设备，现在的通信状态是什么？”
- **电机上电与位置运动**：
  > “把 4 号从站伺服驱动器使能上电，并控制它运动到位置 25000 脉冲。”
- **读取 IO 终端信号**：
  > “读取 1 号从站 EL1008 的所有输入通道电平，以及 3 号从站当前的模拟量电压。”
- **故障诊断与排除**：
  > “检查总线是否有丢包或者 CRC 校验错误，如果驱动器报错请帮我读取 0x603F 并复位报警。”

---

## 💻 本地构建与测试

```bash
# 克隆仓库
git clone https://github.com/LckAndLove/ethercat-mcp.git
cd ethercat-mcp

# 安装依赖
npm install

# 类型检查与编译
npm run check
npm run build

# 运行自动化单元测试
npm test
```

---

## 📄 License

[MIT License](LICENSE) © 2026 [LckAndLove](https://github.com/LckAndLove)