@codesys/mcp-toolkit

@codesys/mcp-toolkit

适用于 CODESYS V3 编程环境的模型上下文协议（MCP）服务。此工具包可让 MCP 客户端（例如 Claude Desktop）与 CODESYS 无缝交互，从而通过 CODESYS Scripting Engine 自动执行项目管理、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 上测试），安装时需启用 Scripting Engine 组件。
• 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）中进行配置。

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

在某些宿主应用（例如 Claude Desktop）中，通过 npx 等封装程序启动 Node.js 工具时，可能会遇到环境变量问题（尤其是 PATH）。因此，强烈建议将 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. 确保 MCP 客户端应用运行时，系统 PATH 中可以访问 codesys-mcp-tool 命令。通过 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 环境变量；虽然有默认值，但不建议依赖该默认值。）
• -f, --codesys-profile <profile>：CODESYS 配置文件的名称。（必填，会覆盖 CODESYS_PROFILE 环境变量；虽然有默认值，但不建议依赖该默认值。）
• -w, --workspace <dir>：用于解析传递给工具的相对项目路径的工作区目录。默认为启动命令时所在的目录（通过其他应用运行时，该目录可能不可预测）。如果使用相对路径，可能需要显式设置此参数。
• -h, --help：显示帮助信息。
• --version：显示软件包版本。

🔍 故障排除

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

  • 原因： 通常在 Claude Desktop 等环境中通过 npx 启动工具时会出现此问题。提供给进程的执行环境（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 实例以冲突方式运行（例如占用了配置文件锁）。

• command not found: codesys-mcp-tool：

  • 确保已全局安装该软件包（npm install -g @codesys/mcp-toolkit）。
  • 确保 npm 全局 bin 目录位于系统的 PATH 环境变量中。使用 npm config get prefix 查找该目录，并将其 bin 子目录（Windows 上也可以是主目录本身）添加到 PATH。

• 检查日志：

  • Claude Desktop 日志：C:\Users\<YourUsername>\AppData\Roaming\Claude\logs\（Windows）

🤝 参与贡献

欢迎贡献代码、提交问题和功能请求！欢迎查看 issues 页面。（也可以选择添加包含更多详细信息的 CONTRIBUTING.md 文件。）

📝 许可证

本项目采用 MIT License 授权，详情请参阅 LICENSE 文件。

🙏 致谢

• 感谢 CODESYS GmbH 团队打造强大的 CODESYS 平台及其脚本引擎。
• 感谢 Model Context Protocol 项目制定交互标准。
• 感谢所有帮助改进此工具包的贡献者和用户。