内容
# codesys-auto-mcp
**独立的[模型上下文协议](https://modelcontextprotocol.io)服务器，适用于CODESYS V3** — 让AI代理（如Claude Desktop、Claude Code、Cursor等）创建CODESYS项目、插入控制器和IO卡、生成结构化文本代码、连接任务并编译，带有**结构化错误回读**。
无需IDE插件：服务器通过其官方脚本引擎（`CODESYS.exe --profile … --noUI --runscript …`）无头驱动CODESYS。
## 需求
- **Windows**（CODESYS V3仅支持Windows）
- **CODESYS V3.5**（已测试3.5 SP22），需安装**脚本引擎组件**（默认安装中包含）
- **Node.js ≥ 18**
## 安装
```bash
git clone https://github.com/uiff/Codesys-MCP-Server.git
cd Codesys-MCP-Server
npm install # 同时编译（准备脚本）
npm run test:smoke # 协议自测试，无需CODESYS
```
## 配置
服务器**自动检测** `%ProgramFiles%` 下的最新CODESYS安装，并从 `<install>\CODESYS\Profiles\*.profile.xml` 推导出配置文件名。零配置适用于标准安装。
覆盖配置（命令行参数 > 环境变量 > 自动检测）：
| 命令行参数 | 环境变量 | 含义 |
|---|---|---|
| `--codesys-path` | `CODESYS_PATH` | `CODESYS.exe` 的完整路径 |
| `--codesys-profile` | `CODESYS_PROFILE` | 配置文件名称，例如 `CODESYS V3.5 SP22 Patch 1`（显示在CODESYS标题栏中） |
| `--timeout` | `CODESYS_TIMEOUT` | 每次调用超时时间（毫秒）（默认为240000） |
### Claude Desktop / Claude Code / Cursor（stdio）
```json
{
"mcpServers": {
"codesys": {
"command": "node",
"args": ["C:/path/to/codesys-auto-mcp/dist/bin.js"]
}
}
}
```
仅当自动检测不适合您的设置时，才添加命令行参数。
## 工具（21）
| 分组 | 工具 |
|---|---|
| 项目 | `codesys_create_project` · `codesys_open_project` · `codesys_save_project` · `codesys_browse_tree` |
| 代码 | `codesys_create_pou` · `codesys_set_pou_code` · `codesys_get_pou_code` · `codesys_create_gvl` · `codesys_create_dut`（结构体/枚举） |
| 任务 | `codesys_create_task` · `codesys_add_program_to_task` |
| 库 | `codesys_add_library`（添加 `Standard` 前面是 `R_TRIG`/`TON`/`TP`） · `codesys_resolve_placeholder`（修复设备固定的库版本） |
| 编译 | `codesys_build` — 从CODESYS Build消息存储返回 `{ clean, errorCount, errors[], warnings[] }` |
| 设备/IO | `codesys_list_devices` · `codesys_insert_device`（接受版本 `*` = 最新安装） · `codesys_get_io_config` · `codesys_map_io` |
| 知识库 | `codesys_list_patterns` · `codesys_get_pattern` · `codesys_catalog_devices` |
### 可靠性保证
- **结构化编译门控**。CODESYS `build()` 不返回任何值 — 幼稚的自动化报告会在代码出错时返回成功。此服务器清除编译消息类别（`{97F48D64-A2A3-4856-B640-75C046E37EA9}`），编译并返回类型化的错误/警告，实现生成 → 编译 → 修复的循环。
- **序列化执行**。工具调用被排队，因此一次只有一个CODESYS进程访问项目。
- **冷启动处理**。第一次启动CODESYS很慢；服务器在超时后重试一次，随后的调用会命中热实例。
- **模式库**。自带验证的IEC 61131-3功能块（带有验收测试头），代理实例化而不是自由表单逻辑 — 例如 `FB_ConveyorSegment`（边缘触发定时停止，基于 `TP`）和 `FB_DebounceDI`。
## 典型代理流程（输送带示例）
1. `codesys_create_project`
2. `codesys_list_devices` 筛选 `"CODESYS Control Win"` → `codesys_insert_device`（类型4096，ID `0000 0001`）
3. `codesys_add_library` `"Standard"`（脚本创建的项目引用库）
4. `codesys_get_pattern` `FB_ConveyorSegment` → `codesys_create_pou` + `codesys_set_pou_code`
5. `codesys_create_gvl` `GVL_IO` → `codesys_create_pou` `PLC_PRG`
6. `codesys_create_task` + `codesys_add_program_to_task`
7. `codesys_build` → 必须返回 `clean: true`
8. `codesys_get_io_config` → `codesys_map_io`（绑定通道到 `GVL_IO.*`）
`test/e2e.mjs` 在本地CODESYS上运行此流程 — 它是发布门控，并通过端到端（16步，干净编译）在CODESYS 3.5 SP22上通过。
### 服务器吸收的版本怪癖（因此代理不需要）
- CODESYS的CLI拒绝标准Windows argv引用：`--profile="Name With Spaces"`必须引用值；服务器自己组成命令行。
- `ScriptDeviceDescription.name`在新版本中不存在 — 设备名称通过`device_info.name`解析。
- IronPython的`json`在非ASCII（®, 变音符号）上崩溃；所有输出在序列化前进行实体转义。
- 脚本添加的库引用默认为`qualified_only`，隐藏`R_TRIG`/`TP`在命名空间后面；服务器像IDE一样清除标志。
- `get_all_devices`有模糊的重载；一些“成功”的结果为空。
## 测试
```bash
npm run test:smoke # MCP握手 + 工具列表 + 知识库工具（无需CODESYS）
node test/e2e.mjs # 完整的实时流水线，针对本地CODESYS（数分钟）
```
## 故障排除
- **第一次调用超时** → 冷启动；调用自动重试。如果您的机器速度慢，请增加 `--timeout`。
- **“找不到CODESYS安装”** → 显式传递 `--codesys-path` 和 `--codesys-profile`。
- **CODESYS配置文件错误** → 配置文件名称必须完全匹配；检查 `<install>\CODESYS\Profiles\*.profile.xml` 或CODESYS标题栏。
- **CODESYS实例占用配置文件** → 关闭CODESYS窗口 / 在任务管理器中检查 `CODESYS.exe`。
## 安全说明
该服务器使用生成的脚本和完全的用户权限启动 `CODESYS.exe`：它可以创建/修改项目文件，只要用户可以写入的位置。仅与您信任的MCP客户端一起运行，并像处理任何文件写入一样对待代理传递的项目路径。它**不**执行对物理硬件的PLC下载。
## 安全通知（PLC代码）
生成的IEC 61131-3代码是工程辅助，**非**认证的功能安全逻辑。人员保护功能（紧急停止，防护罩，灯幕）属于安全评级硬件，具有认证的PLCopen安全功能块，必须由合格工程师验证。
## 已知限制
- **供应商锁定IO编辑器**。一些供应商通过专有GUI编辑器路由他们的IO模块，没有脚本钩子。例如：**Weidmüller u-control M-series** — 集成 `System_Bus` 上的u-remote卡不能通过*任何*脚本添加（CODESYS本身回复 *"在System-Bus设备的设备管理器编辑器中添加设备"*）。卡必须在IDE中插入一次；其他所有操作（控制器，代码，任务，库，编译 — 以及之后的 `map_io`）都是自动化的。标准驱动程序（EtherCAT/Modbus/CANopen/Profinet）接受脚本 `insert_device`。
- **IO变量绑定** (`map_io`) 使用文档化的ScriptEngine API，包括连接器遍历，但尚未针对物理IO硬件进行测试。
- **没有在线下载** 到PLC — 该服务器构建/验证项目；下载是IDE中的手动，刻意的步骤。
## 示例：完整的热泵控制器
**[examples/heatpump/](examples/heatpump/)** 包含一个完整的热泵控制应用程序 — 热曲线，DHW优先级，压缩机防短循环保护，泵预/后排序，备用加热器双价，安全互锁和7状态机 — 作为：
- 一个 **已准备好的 `.project`**，可以直接在CODESYS中打开，和
- **ST源代码 + `generate.mjs`**，通过此服务器在一个运行中再生和构建整个项目（`node examples/heatpump/generate.mjs` → 以 `"clean":true` 结束）。
## 状态 / 路线图
- ✅ 项目、代码、库、任务和编译工具 — **针对CODESYS 3.5 SP22验证端到端** （参见 `test/e2e.mjs`：项目 → Control Win V3 → 标准库 → ST代码 → 任务 → 清洁编译）
- ✅ 设备列表/插入 — 实时验证（1686设备存储库枚举；控制器插入有效）
- ⚠️ IO映射（`codesys_map_io`）使用文档化的ScriptEngine API，包括连接器遍历，但尚未针对物理IO硬件进行测试
- 🔜 在线/模拟测试（登录，强制值，读取输出）
- 🔜 模式库CI自测试，针对真实CODESYS构建
## 贡献
欢迎提交问题和拉取请求！尤其有价值的是：
- **版本怪癖报告** — CODESYS服务包和供应商包各不相同；如果工具在您的设置上出现故障，请提交问题并附上CODESYS版本，配置文件名称和工具的错误输出。
- **模式库添加** (`kb/patterns/*.st`) — 可重用的，已验证的IEC 61131-3功能块，带有验收测试头。
- **设备目录条目** (`kb/catalog/`) — 已确认控制器和IO卡的DeviceID三元组。
在提交之前：`npm run build && npm run test:smoke` 必须通过；如果您已安装CODESYS，则 `node test/e2e.mjs` 是完整的关卡。
## License
MIT
