AI导哈

CODESYS MCP工具包

一个用于CODESYS V3编程环境的模型上下文协议(MCP)服务器工具包，支持通过脚本引擎自动化管理项目、创建POU、编辑代码和编译任务。

  • by johannesPettersson80
  • TypeScript
  • 本地部署
  • 127 星标
  • 更新于
在 GitHub 查看 johannesPettersson80/codesys-mcp-toolkit

使用说明

@codesys/mcp工具包

用于CODESYS V3编程环境的模型上下文协议（MCP）服务器。该工具包实现了MCP客户端（如Claude Desktop）和CODESYS之间的无缝交互，允许通过CODESYS脚本引擎自动化项目管理、POU创建、代码编辑和编译任务。

🌟 特性

  • 项目管理

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

  • POU管理

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

  • 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 @codesys/mcp-toolkit

这将全局安装软件包，使 codesys-mcp-tool 命令在系统的终端PATH中可用。

（高级用户也可以从源代码安装以进行开发-如果可用，请参阅CONTRIBUTING.md）。

🔧 配置（重要！）

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

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

由于潜在的环境变量问题（尤其是 PATH)当通过包装器启动Node.js工具时，例如 npx 在某些主机应用程序（例如，Claude Desktop）中，它是 强烈建议 配置MCP客户端以运行已安装的命令 codesys-mcp-tool 直接.

Claude Desktop示例(settings.json -> mcpServers):

{
  "mcpServers": {
    // ... other servers ...
    "codesys_local": {
      "command": "codesys-mcp-tool", // <<< Use the direct command name
      "args": [
        // Pass arguments directly to the tool using flags
        "--codesys-path", "C:\\Program Files\\Path\\To\\Your\\CODESYS\\Common\\CODESYS.exe",
        "--codesys-profile", "Your CODESYS Profile Name"
        // Optional: Add --workspace "/path/to/your/projects" if needed
      ]
    }
    // ... other servers ...
  }
}

关键步骤：

  1. 替换 "C:\\Program Files\\Path\\To\\Your\\CODESYS\\Common\\CODESYS.exe" 随着 完整、正确的路径 根据您的具体情况 CODESYS.exe 文件。
  2. 替换 "Your CODESYS Profile Name" 随着 确切名称 您要使用的CODESYS配置文件（在CODESYS UI中可见）。
  3. 确保 codesys-mcp-tool 命令可以在MCP客户端应用程序运行的系统PATH中访问。全球安装通过 npm install -g 通常会处理这个问题。
  4. 重新启动MCP客户端应用程序（例如Claude Desktop）以应用设置更改。

替代配置（使用 npx -不推荐）

启动方式 npx 已被观察到会立即导致错误('C:\Program' is not recognized...)在某些环境中，可能是由于 npx 处理执行环境。 如果可能的话，使用上面的直接命令方法。 如果你必须使用 npx:

// Example using npx (POTENTIALLY PROBLEMATIC - USE WITH CAUTION):
{
  "mcpServers": {
    "codesys_local": {
      "command": "npx",
      "args": [
        "-y", // Tells npx to install temporarily if not found globally
        "@codesys/mcp-toolkit",
        // Arguments for the tool MUST come AFTER the package name
        "--codesys-path", "C:\\Program Files\\Path\\To\\Your\\CODESYS\\Common\\CODESYS.exe",
        "--codesys-profile", "Your CODESYS Profile Name"
      ]
    }
  }
}

（注： -- 包名后的分隔符有时可能会有所帮助 npx 但不能保证解决环境问题。)

🛠️ 命令行参数

跑步时 codesys-mcp-tool 您可以直接使用或配置这些参数：

  • -p, --codesys-path <path>：完整路径 CODESYS.exe。（必填，覆盖 CODESYS_PATH env-var有一个默认值，但不建议依赖它）。
  • -f, --codesys-profile <profile>：CODESYS配置文件的名称。（必填，覆盖 CODESYS_PROFILE env-var有一个默认值，但不建议依赖它）。
  • -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: 消息或Python DEBUG: / ERROR: 从CODESYS脚本执行打印到stderr的消息。
    • 确保 --codesys-path 和 --codesys-profile 传递给命令的参数是正确的，并且指向启用了脚本的有效CODESYS安装。
    • 验证传递给工具的项目路径和对象路径是否正确（使用正斜杠 /).
    • 确保没有其他CODESYS实例以冲突的方式运行（例如，在配置文件上持有锁）。

  • command not found: codesys-mcp-tool:

    • 确保该软件包已全局安装(npm install -g @codesys/mcp-toolkit).
    • 确保npm全局bin目录在您的系统中 PATH 环境变量。找到它 npm config get prefix 并添加 bin 将子目录（或Windows上的主目录本身）添加到PATH中。

  • 检查日志：

    • 克劳德桌面日志： C:\Users\<YourUsername>\AppData\Roaming\Claude\logs\ （Windows）

🤝 贡献

欢迎投稿、问题和功能请求！请随时查看问题页面。（可选择添加一个包含更多详细信息的CONTRIBUTING.md文件）。

📝 许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

🙏 致谢

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

相关 MCP