@codesys/mcp-toolkit 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 CODESYS MCP Server Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# @codesys/mcp-toolkit
+
+This project provides a Model Context Protocol (MCP) server that allows interaction with a local CODESYS V3 development environment (tested with 3.5 SP21) via its scripting interface. It enables MCP clients like Claude Desktop to perform actions such as opening/creating/saving projects, creating POUs, adding code, and compiling projects.
+
+## Features
+
+Currently implemented features:
+
+*   **Resources:**
+    *   `codesys://project/status`: Checks scripting status and if a project is open.
+    *   `codesys://project/structure`: Retrieves the structure of the open project as text.
+    *   `codesys://pou/{+pou_path}/code`: Reads the implementation or declaration code of a specific POU or DUT/GVL.
+*   **Tools:**
+    *   `open_project`: Opens a specified CODESYS project file (`.project`).
+    *   `create_project`: Creates a new CODESYS project file (`.project`), optionally from a template.
+    *   `save_project`: Saves the currently open CODESYS project.
+    *   `create_pou`: Creates a new POU (Program, Function Block, Function) with a specified language under a parent object in the project tree.
+    *   `add_code`: Sets the implementation code for a specified POU.
+    *   `compile_project`: Initiates the compilation of the open project.
+
+## Prerequisites
+
+1.  **CODESYS V3 Installation:** A working CODESYS V3 installation (e.g., 3.5 SP21) with the **Scripting Engine** component enabled.
+2.  **Node.js:** Node.js (version 18 or later recommended) installed on your system. You can download it from [nodejs.org](https://nodejs.org/).
+3.  **MCP Client:** An MCP client application, such as **Claude Desktop**.
+
+## Installation
+
+### Option 1: Install from npm (Recommended)
+
+```bash
+npm install -g @codesys/mcp-toolkit
+```
+
+This will install the server globally, making the `codesys-mcp-toolkit` command available in your terminal.
+
+### Option 2: Install from Source
+
+1. **Clone Repository:**
+   ```bash
+   git clone https://github.com/yourusername/codesys-mcp-server.git
+   cd codesys-mcp-server
+   ```
+
+2. **Install Dependencies:**
+   ```bash
+   npm install
+   ```
+
+3. **Build the Project:**
+   ```bash
+   npm run build
+   ```
+
+4. **Install Globally:**
+   ```bash
+   npm install -g .
+   ```
+
+## Running the Server (via Claude Desktop)
+
+This server is designed to be launched automatically by an MCP client like Claude Desktop using its stdio connection mechanism. You don't typically run it directly from the command line yourself.
+
+## Configuring Claude Desktop
+
+1.  **Locate Configuration File:** Find Claude Desktop's MCP configuration file. On Windows, it's typically located at:
+    `C:\Users\<YourUsername>\AppData\Roaming\Claude\claude_desktop_config.json`
+    (Replace `<YourUsername>` with your actual Windows username).
+2.  **Edit Configuration:** Open `claude_desktop_config.json` in a text editor.
+3.  **Add Server Entry:** Add an entry for the CODESYS server within the `mcpServers` object. Make sure to replace the example paths and profile name with your actual values.
+
+    ```json
+    {
+      "mcpServers": {
+        // ... other servers like puppeteer, filesystem ...
+
+        "codesys_local": {
+          "command": "npx",
+          "args": [
+            "-y",
+            "@codesys/mcp-toolkit",
+            "--codesys-path", "C:\\Program Files\\CODESYS 3.5.21.0\\CODESYS\\Common\\CODESYS.exe",
+            "--codesys-profile", "CODESYS V3.5 SP21"
+          ]
+        }
+      }
+    }
+    ```
+
+    **Important:**
+    *   Replace `C:/Users/ek6430/Desktop/codesys-mcp-server/dist/server.js` with the correct **absolute path** to the compiled `server.js` file on your system. Use forward slashes (`/`) for path separators within this JSON string.
+    *   Replace `"C:\\Program Files\\CODESYS 3.5.21.0\\CODESYS\\Common\\CODESYS.exe"` with the correct **absolute path** to your `CODESYS.exe`. Note the use of double backslashes (`\\`) because backslashes need to be escaped within JSON strings.
+    *   Replace `"CODESYS V3.5 SP21"` with the **exact name** of your CODESYS profile (the one with scripting enabled). Find this name when starting CODESYS or in its title bar.
+4.  **Save the File.**
+5.  **Restart Claude Desktop:** Close Claude Desktop completely and restart it. It will now read the updated configuration and attempt to launch the CODESYS server with the specified arguments.
+6.  **Verify Connection:** Claude Desktop should indicate that it has successfully connected to the "codesys_local" server. You might see the server listed in your available MCP integrations.
+7.  **Use Tools/Resources:** You can now interact with the server from within Claude. For example:
+    *   Ask Claude to "Use the `project-status` resource from the CODESYS Local server."
+    *   Ask Claude to "Use the `open_project` tool from CODESYS Local with filePath set to 'C:/Path/To/Your/Project.project'." (Replace with a real project path).
+
+## Troubleshooting
+
+*   **Configuration Errors:** If Claude Desktop fails to connect, check its logs (often found in `C:\Users\<YourUsername>\AppData\Roaming\Claude\logs\`). Look for errors related to the `codesys_local` server.
+    *   Verify the paths and profile name in `claude_desktop_config.json` are absolutely correct. Pay attention to path separators (`/` for the script path, `\\` for the CODESYS path within the JSON string).
+    *   Ensure the profile name exactly matches the one in CODESYS.
+*   **Server Script Errors:** If the server starts but tools/resources fail, check the server's output in the Claude Desktop logs. The `executeCodesysScript` function in the server code includes `console.log` and `console.error` statements that might appear in the logs, providing clues about script execution issues.
+*   **Permissions:** The user account running Claude Desktop (and thus the Node.js server) needs permission to execute `CODESYS.exe` and write temporary files to the OS's temporary directory.
+*   **CODESYS Script Errors:** If a CODESYS script itself fails (e.g., invalid POU path, project not open), the error message from the script should be returned in the MCP tool/resource response. Check the `output` field in the response.
+*   **CODESYS Not Running/Responding:** The `executeCodesysScript` might time out or fail if the CODESYS scripting engine cannot be launched properly. Ensure CODESYS isn't already running in a conflicting way (though `--noUI` should help).
+
+## Future Enhancements (Based on Provided API Details)
+
+The detailed API information provided (especially `ScriptOnline`) opens up possibilities for significant future enhancements, such as:
+
+*   Connecting to a running PLC (`create_online_device`, `connect`).
+*   Logging into the PLC (`login`).
+*   Starting/Stopping applications (`start`, `stop`).
+*   Reading/Writing live variable values (`read_value`, `set_prepared_value`, `write_prepared_values`).
+*   Forcing/Unforcing values (`force_prepared_values`, `unforce_all_values`).
+*   Performing downloads and online changes (`login` with options).
+*   Managing PLC files (`download_file`, `upload_file`, `delete_file`).
+*   Handling PLC user management (`create_live_user_management`).
+*   License management (`activate_license`).

package/dist/bin.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * CODESYS MCP Server CLI
+ * Command-line interface for starting the CODESYS MCP server
+ * with configurable CODESYS executable paths and profile names.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+// Define version from package.json
+const packageJson = require('../package.json');
+const version = packageJson.version;
+commander_1.program
+    .name('codesys-mcp-toolkit')
+    .description('Model Context Protocol (MCP) server for CODESYS automation platform')
+    .version(version)
+    .option('-e, --codesys-path <path>', 'Path to CODESYS executable', 'C:\\Program Files\\CODESYS 3.5.21.0\\CODESYS\\Common\\CODESYS.exe')
+    .option('-p, --codesys-profile <profile>', 'CODESYS profile name', 'CODESYS V3.5 SP21')
+    .parse(process.argv);
+const options = commander_1.program.opts();
+// Log startup message for debugging
+console.error(`Starting CODESYS MCP Server v${version}`);
+console.error(`Using CODESYS path: ${options.codesysPath}`);
+console.error(`Using CODESYS profile: ${options.codesysProfile}`);
+// Pass command line arguments to the CODESYS executable path and profile
+// The server.js file expects these as positional parameters
+process.argv[2] = options.codesysPath;
+process.argv[3] = options.codesysProfile;
+// Import and start the server
+import('./server.js');

package/dist/codesys_interop.js

@@ -0,0 +1,180 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeCodesysScript = executeCodesysScript;
+const child_process_1 = require("child_process");
+const promises_1 = require("fs/promises");
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+// Define expected success/error markers from the Python scripts
+const SCRIPT_SUCCESS_MARKER = 'SCRIPT_SUCCESS';
+const SCRIPT_ERROR_MARKER = 'SCRIPT_ERROR';
+/**
+ * Executes a CODESYS Python script using the command line interface.
+ *
+ * @param scriptContent The Python script code to execute.
+ * @param codesysExePath The full path to the CODESYS.exe executable.
+ * @param codesysProfileName The name of the CODESYS profile to use for scripting.
+ * @returns A promise resolving to an object containing the success status and the script's output.
+ */
+function executeCodesysScript(scriptContent, codesysExePath, codesysProfileName) {
+    return __awaiter(this, void 0, void 0, function* () {
+        // Validate arguments passed to the function
+        if (!codesysExePath) {
+            throw new Error('CODESYS executable path was not provided to executeCodesysScript.');
+        }
+        if (!codesysProfileName) {
+            throw new Error('CODESYS profile name was not provided to executeCodesysScript.');
+        }
+        // Create a temporary file for the script
+        const tempDir = os.tmpdir();
+        const tempFileName = `codesys_script_${Date.now()}_${Math.random().toString(36).substring(7)}.py`;
+        const tempFilePath = path.join(tempDir, tempFileName);
+        let output = '';
+        let success = false;
+        try {
+            // Normalize line endings to LF (\n)
+            const normalizedScriptContent = scriptContent.replace(/\r\n/g, '\n');
+            // Write the script content to the temporary file using latin1 encoding
+            yield (0, promises_1.writeFile)(tempFilePath, normalizedScriptContent, 'latin1'); // Explicitly use latin1
+            process.stderr.write(`Temporary script written to: ${tempFilePath} with latin1 encoding and LF line endings\n`); // Use process.stderr
+            // Add --additionalfolder argument
+            const additionalFolderPath = "C:\\Program Files\\CODESYS 3.5.21.0\\CODESYS\\AdditionalFolders\\Default"; // Assuming Default instance
+            // Fix: Use shell:true and pass the entire command as a single string without additionalfolder
+            const commandWithArgs = `"${codesysExePath}" --profile="${codesysProfileName}" --noUI --runscript="${tempFilePath}"`;
+            process.stderr.write(`Executing: ${commandWithArgs}\n`); // Log the command string
+            // Spawn the CODESYS process using shell:true for proper argument handling
+            const codesysProcess = (0, child_process_1.spawn)(commandWithArgs, {
+                stdio: ['ignore', 'pipe', 'pipe'], // Ignore stdin, pipe stdout and stderr
+                shell: true // Use shell to handle the command string properly
+            });
+            // Capture stdout
+            codesysProcess.stdout.on('data', (data) => {
+                const chunk = data.toString();
+                // console.error('CODESYS stdout:', chunk); // Optional: Original debug log
+                output += chunk;
+            });
+            // Capture stderr
+            codesysProcess.stderr.on('data', (data) => {
+                const chunk = data.toString();
+                process.stderr.write(`CODESYS stderr: ${chunk}\n`); // Use process.stderr
+                output += chunk; // Include stderr in the output for debugging
+            });
+            // Wait for the process to exit with a timeout
+            const exitCode = yield new Promise((resolve, reject) => {
+                // Add timeout handling
+                const timeoutMs = 30000; // 30 seconds
+                const timeout = setTimeout(() => {
+                    process.stderr.write(`TIMEOUT: CODESYS process did not complete in ${timeoutMs}ms\n`);
+                    // Force resolve with 0 to proceed with parsing output collected so far
+                    codesysProcess.kill();
+                    resolve(0);
+                }, timeoutMs);
+                codesysProcess.on('close', (code) => {
+                    clearTimeout(timeout);
+                    resolve(code !== null && code !== void 0 ? code : 0);
+                });
+                codesysProcess.on('error', (err) => {
+                    clearTimeout(timeout);
+                    // Error starting the process itself (e.g., command not found)
+                    process.stderr.write(`Failed to start CODESYS process: ${err.message}\n`); // Use process.stderr
+                    reject(err);
+                });
+            });
+            process.stderr.write(`CODESYS process exited with code: ${exitCode}\n`); // Use process.stderr
+            // Determine success based on exit code and output markers
+            // Note: CODESYS scripting might return exit code 0 even if the script had logical errors.
+            // Relying on specific output markers is more robust.
+            if (output.includes(SCRIPT_SUCCESS_MARKER)) {
+                success = true;
+            }
+            else if (output.includes(SCRIPT_ERROR_MARKER)) {
+                success = false;
+            }
+            else {
+                // If no markers found, fall back to exit code (less reliable)
+                success = exitCode === 0;
+                if (!success) {
+                    // Append the specific CODESYS error if available and no other marker found
+                    if (!output.includes(SCRIPT_ERROR_MARKER)) {
+                        output += `\nSCRIPT_ERROR: Process exited with non-zero code ${exitCode}. Check CODESYS stderr output above for details.`;
+                    }
+                    else {
+                        output += `\nSCRIPT_ERROR: Process exited with non-zero code ${exitCode}.`;
+                    }
+                }
+                else {
+                    // If exit code is 0 but no success marker, treat as potential issue or simple script
+                    console.error("Warning: CODESYS script finished with exit code 0 but no SCRIPT_SUCCESS marker found."); // Log warning to stderr
+                    // Optionally, you could treat this as success or failure depending on requirements
+                    // For now, let's assume success if exit code is 0 and no error marker.
+                    if (!output.includes(SCRIPT_ERROR_MARKER)) {
+                        success = true;
+                    }
+                }
+            }
+        }
+        catch (error) {
+            process.stderr.write(`Error executing CODESYS script: ${error}\n`); // Use process.stderr
+            output += `\nSCRIPT_ERROR: Failed to execute script process. ${error.message}`;
+            success = false;
+        }
+        finally {
+            // Clean up the temporary file
+            try {
+                yield (0, promises_1.unlink)(tempFilePath);
+                process.stderr.write(`Temporary script deleted: ${tempFilePath}\n`); // Use process.stderr
+            }
+            catch (cleanupError) {
+                process.stderr.write(`Failed to delete temporary script file ${tempFilePath}: ${cleanupError}\n`); // Use process.stderr
+                // Don't overwrite the original error if cleanup fails
+                if (success) { // Only add cleanup error if the main process didn't already fail
+                    output += `\nWARNING: Failed to delete temporary script file ${tempFilePath}. ${cleanupError.message}`;
+                }
+            }
+        }
+        process.stderr.write(`Final script output received:\n---\n${output}\n---\n`); // Use process.stderr
+        return { success, output }; // Revert return object
+    });
+}