CodeSysUltra MCP CXK

codesysultra-mcp-cxk 是一个面向 CODESYS V3 的增强版 MCP 包。它基于现有 codesysultra 能力继续扩展，补上了变量管理、批量在线读写、文档导出、代码分析和项目互操作等工程师常用能力，并以独立包身份分发。

当前定位

• 包名：codesysultra-mcp-cxk
• 命令名：codesysultra-mcp-cxk
• 作者：蔡徐坤
• 当前版本：1.2.0

核心能力

基础能力

• 打开、创建、保存 CODESYS 项目
• 创建 POU、属性、方法
• 读取和写入 POU 代码
• 编译项目
• 读取项目结构与状态

增强工具

• 变量管理：list_variables、batch_declare_variables、check_io_address_conflicts、find_variable_references
• 批量在线操作：batch_read_variables、batch_write_variables、force_variable、capture_variable_snapshot
• 文档导出：export_io_list、export_variable_dictionary、generate_project_report
• 代码分析：find_unused_variables、analyze_pou_complexity、get_cross_references
• 项目互操作：export_project_as_xml、export_pou_as_xml、import_pou_from_xml
• 测试与部署：get_build_messages、get_device_info、create_boot_application、run_unit_tests、set_breakpoint

MCP 资源

• codesys://project/status
• codesys://project/{+project_path}/structure
• codesys://project/{+project_path}/pou/{+pou_path}/code

环境要求

• 已安装 CODESYS V3，并启用脚本引擎
• Node.js 18 或更高版本
• 任意支持 MCP 的客户端

注意：本包当前已完成模板接线、工具注册与打包整理，但未在所有在线相关接口上完成全量实机验收。在线工具建议先在目标环境做一次小范围冒烟验证。

安装方式

方式一：从本地打包产物安装

如果你拿到的是本地生成的 .tgz 包，直接安装：

npm install -g ./codesysultra-mcp-cxk-1.2.0.tgz

方式二：从当前目录安装

如果你拿到的是解压后的源码目录：

npm install
npm install -g .

安装完成后，系统命令为：

codesysultra-mcp-cxk --version

方式三：未来发布到新 npm 名称后安装

如果后续发布到新的 npm 包名，可直接执行：

npm install -g codesysultra-mcp-cxk

推荐配置

优先使用直接命令，而不是 npx。

{
  "mcpServers": {
    "codesys_local": {
      "command": "codesysultra-mcp-cxk",
      "args": [
        "--codesys-path",
        "C:\\Program Files\\CODESYS\\Common\\CODESYS.exe",
        "--codesys-profile",
        "你的配置文件名称"
      ]
    }
  }
}

如果未来需要走 npx，也应使用新的包名：

{
  "mcpServers": {
    "codesys_local": {
      "command": "npx",
      "args": [
        "-y",
        "codesysultra-mcp-cxk",
        "--codesys-path",
        "C:\\Program Files\\CODESYS\\Common\\CODESYS.exe",
        "--codesys-profile",
        "你的配置文件名称"
      ]
    }
  }
}

命令行参数

• -p, --codesys-path <path>：CODESYS.exe 的完整路径
• -f, --codesys-profile <profile>：CODESYS 配置文件名称
• -w, --workspace <dir>：工作区目录，用于解析相对项目路径
• -g, --generate-config：根据版本信息文件生成 MCP 配置
• -v, --version-info <path>：版本信息文件路径
• -o, --output <path>：配置输出路径
• -h, --help：显示帮助
• --version：显示版本号

常见问题

为什么优先推荐直接命令？

在部分 MCP 宿主里，npx 会改变进程运行环境，容易引发路径解析和 CODESYS 内部命令调用问题。直接命令更稳。

如果命令找不到怎么办？

• 确认已经执行过 npm install -g
• 确认 npm 全局 bin 目录已加入系统 PATH
• 重新打开终端后再试一次

如果工具执行失败怎么办？

• 检查 MCP 客户端日志
• 核对 --codesys-path 和 --codesys-profile
• 确认项目路径、对象路径是否正确
• 避免同时有冲突的 CODESYS 实例占用同一配置

许可证

本项目使用 Apache License 2.0，详见 LICENSE。