@codesys/mcp-toolkit

这是一个针对CODESYS V3编程环境的Model Context Protocol (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）中完成。

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

由于通过包装器（如npx）在某些宿主应用（如Claude Desktop）中启动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\\Path\\To\\Your\\CODESYS\\Common\\CODESYS.exe",
        "--codesys-profile", "Your CODESYS Profile Name"
        // 可选：如果需要，添加 --workspace "/path/to/your/projects"
      ]
    }
    // ... 其他服务器 ...
  }
}

关键步骤：

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：

// 示例使用npx（可能有问题 - 使用时需谨慎）:
{
  "mcpServers": {
    "codesys_local": {
      "command": "npx",
      "args": [
        "-y", // 告诉npx如果未找到全局安装则临时安装
        "@codesys/mcp-toolkit",
        // 工具的参数必须在包名之后
        "--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...错误：

  • 原因: 这通常发生在通过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 @codesys/mcp-toolkit)。
  • 确保npm全局bin目录在系统的PATH环境变量中。使用npm config get prefix找到它，并将bin子目录（或Windows上的主目录本身）添加到PATH中。

• 检查日志：

  • Claude Desktop日志: C:\Users\<YourUsername>\AppData\Roaming\Claude\logs\ (Windows)

🤝 贡献

欢迎贡献、问题报告和功能请求！请随意查看问题页面。(可选地添加一个包含更多细节的CONTRIBUTING.md文件)。

📝 许可

该项目根据MIT许可发布 - 详情见LICENSE文件。

🙏 致谢

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