CodeSysUltra

一个为 CODESYS V3 编程环境设计的强大工具包，通过模型上下文协议（MCP）实现与 CODESYS 的无缝集成。

简介

CodeSysUltra 是一个基于 Node.js 的 MCP 服务器，它允许你通过 MCP 客户端（如 Claude Desktop）与 CODESYS V3 进行交互。利用 CODESYS 的脚本引擎，你可以自动化项目管理、POU 创建、代码编辑和编译等任务。

核心功能

项目管理

• 打开现有的 CODESYS 项目
• 从标准模板创建新项目
• 保存项目更改

POU 管理

• 创建程序、功能块和函数
• 设置声明和实现代码
• 为功能块创建属性
• 为功能块创建方法
• 编译项目

MCP 资源

• codesys://project/status - 检查脚本状态和当前打开的项目状态
• codesys://project/{+project_path}/structure - 获取指定项目的对象结构
• codesys://project/{+project_path}/pou/{+pou_path}/code - 读取指定 POU、方法或属性访问器的声明和实现代码

环境要求

• CODESYS V3：已安装的 CODESYS V3（测试版本 3.5 SP21），并在安装时启用了脚本引擎组件
• Node.js：建议使用 18.0.0 或更高版本
• MCP 客户端：支持 MCP 的应用程序（例如 Claude Desktop）

注意：CODESYS 内部使用 Python 2.7 作为脚本引擎，但本工具包会处理所有交互，你无需单独管理 Python。

安装方法

全局安装（推荐）

使用 npm 进行全局安装：

npm install -g codesysultra

安装后，codesys-mcp-tool 命令将可在系统终端中使用。

从源码安装

高级用户也可以从源码进行开发安装（如有需要，请参考 CONTRIBUTING.md）。

配置说明

本工具包需要知道你的 CODESYS 安装位置和要使用的配置文件。配置通常在 MCP 客户端应用程序（如 Claude Desktop）中完成。

推荐配置方式（直接命令）

由于在某些宿主应用程序（如 Claude Desktop）中通过 npx 启动 Node.js 工具时可能会出现环境变量问题（特别是 PATH），强烈建议配置 MCP 客户端直接运行已安装的 codesys-mcp-tool 命令。

Claude Desktop 配置示例（settings.json -> mcpServers）：

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

配置步骤：

1. 将 "C:\\Program Files\\CODESYS\\Common\\CODESYS.exe" 替换为你实际的 CODESYS.exe 文件的完整路径
2. 将 "你的配置文件名称" 替换为你要使用的 CODESYS 配置文件的确切名称（在 CODESYS 界面中可见）
3. 确保 codesys-mcp-tool 命令在 MCP 客户端运行的系统 PATH 中可访问。通过 npm install -g 全局安装通常会自动处理
4. 重启 MCP 客户端应用程序（如 Claude Desktop）以应用设置更改

备选配置方式（使用 npx - 不推荐）

使用 npx 启动在某些环境中已被观察到会导致立即错误（如 'C:\Program' is not recognized...），这可能是由于 npx 处理执行环境的方式造成的。如果可能，请使用上述直接命令方法。

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

命令行参数

直接运行 codesys-mcp-tool 或配置时，可以使用以下参数：

• -p, --codesys-path <path> - CODESYS.exe 的完整路径（必需，覆盖 CODESYS_PATH 环境变量）
• -f, --codesys-profile <profile> - CODESYS 配置文件名称（必需，覆盖 CODESYS_PROFILE 环境变量）
• -w, --workspace <dir> - 工作区目录，用于解析传递给工具的相对项目路径。默认为命令启动的目录
• -h, --help - 显示帮助信息
• --version - 显示包版本

常见问题

连接后立即出现 'C:\Program' is not recognized... 错误

原因：这通常发生在通过 npx 在 Claude Desktop 等环境中启动工具时。提供给进程的执行环境（PATH 变量）可能导致内部 CODESYS 命令（如运行 Python）失败。

解决方案：配置 MCP 客户端直接运行命令（"command": "codesys-mcp-tool"），而不是使用 "command": "npx"。参见上面的推荐配置方式。

工具失败 / 输出中出现错误

• 检查 MCP 客户端应用程序的日志（例如 Claude Desktop 日志）。查找 INTEROP: 消息或从 CODESYS 脚本执行打印到 stderr 的 Python DEBUG: / ERROR: 消息
• 确保传递给命令的 --codesys-path 和 --codesys-profile 参数正确，并指向启用了脚本的有效 CODESYS 安装
• 验证传递给工具的项目路径和对象路径是否正确（使用正斜杠 /）
• 确保没有其他 CODESYS 实例以冲突的方式运行（例如，锁定配置文件）

找不到命令 codesys-mcp-tool

• 确保已全局安装包（npm install -g codesysultra）
• 确保 npm 全局 bin 目录在系统的 PATH 环境变量中。使用 npm config get prefix 查找，并将 bin 子目录（Windows 上为主目录本身）添加到你的 PATH

查看日志

• Claude Desktop 日志：C:\Users\<你的用户名>\AppData\Roaming\Claude\logs\（Windows）

贡献指南

欢迎贡献、提出问题和功能请求！随时查看问题页面。

许可证

本项目采用 Apache License 2.0 许可证 - 详见 LICENSE 文件。

致谢

• CODESYS GmbH 团队提供了强大的 CODESYS 平台及其脚本引擎
• 模型上下文协议项目定义了交互标准
• 所有帮助改进此工具包的贡献者和用户

版本历史

当前版本：1.0

联系方式

如有问题或建议，请通过 GitHub Issues 联系我们。