@codesys/mcp-toolkit 1.1.4 → 1.2.1

package/README.md.enhanced

@@ -1,155 +1,155 @@
-# @codesys/mcp-toolkit
-
-![npm](https://img.shields.io/npm/v/@codesys/mcp-toolkit)
-![License](https://img.shields.io/github/license/yourusername/codesys-mcp-toolkit)
-
-A Model Context Protocol (MCP) server for CODESYS V3 programming environments. This toolkit enables seamless interaction between MCP clients (like Claude Desktop) and CODESYS, allowing automation of project management, POU creation, code editing, and compilation tasks.
-
-<p align="center">
-  <img src="https://github.com/yourusername/codesys-mcp-toolkit/raw/main/docs/assets/diagram.png" alt="CODESYS MCP Toolkit Architecture" width="600">
-</p>
-
-## 🌟 Features
-
-- **Project Management**
-  - Open existing CODESYS projects
-  - Create new projects from templates
-  - Save project changes
-
-- **POU Management**
-  - Create Programs, Function Blocks, and Functions
-  - Set declaration and implementation code
-  - Create properties and methods for Function Blocks
-  - Compile projects
-
-- **MCP Resources**
-  - `codesys://project/status`: Check scripting status and project state
-  - `codesys://project/{+project_path}/structure`: Retrieve project structure
-  - `codesys://project/{+project_path}/pou/{+pou_path}/code`: Read POU code
-
-- **MCP Tools**
-  - `open_project`: Open specified CODESYS project
-  - `create_project`: Create new CODESYS project
-  - `save_project`: Save currently open project
-  - `create_pou`: Create new Program, Function Block, or Function
-  - `set_pou_code`: Update code for a specified POU
-  - `create_property`: Create property in a Function Block
-  - `create_method`: Create method in a Function Block
-  - `compile_project`: Compile the open project
-
-## 📋 Prerequisites
-
-- **CODESYS V3**: A working CODESYS V3 installation (tested with 3.5 SP21) with **Scripting Engine** component enabled
-- **Node.js**: Version 18 or later required
-- **MCP Client**: An MCP-enabled application (e.g., Claude Desktop)
-
-## 🚀 Installation
-
-### Option 1: Install from npm (Recommended)
-
-```bash
-npm install -g @codesys/mcp-toolkit
-```
-
-This installs the package globally, making the `codesys-mcp-toolkit` command available in your terminal.
-
-### Option 2: Install from Source
-
-```bash
-# Clone the repository
-git clone https://github.com/yourusername/codesys-mcp-toolkit.git
-cd codesys-mcp-toolkit
-
-# Install dependencies
-npm install
-
-# Build the project
-npm run build
-
-# Install globally
-npm install -g .
-```
-
-## 🔧 Configuration
-
-### Claude Desktop Configuration
-
-1. Locate your Claude Desktop configuration file:
-   - Windows: `C:\Users\<YourUsername>\AppData\Roaming\Claude\claude_desktop_config.json`
-
-2. Add the CODESYS MCP server entry:
-
-```json
-{
-  "mcpServers": {
-    "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"
-      ]
-    }
-  }
-}
-```
-
-3. Customize the paths to match your CODESYS installation:
-   - `--codesys-path`: Path to your CODESYS.exe
-   - `--codesys-profile`: Your CODESYS profile name
-
-4. Restart Claude Desktop to apply the changes
-
-## 🛠️ Usage Examples
-
-### Creating a Function Block with Properties
-
-```
-Ask Claude: "Using the CODESYS Local server, please create a Motor Controller function block with Start and Stop methods, plus CurrentSpeed property."
-```
-
-Claude will execute these MCP tool calls:
-1. `create_pou` to create the MotorController Function Block
-2. `create_property` to add the CurrentSpeed property
-3. `create_method` to add Start and Stop methods
-4. `set_pou_code` to implement each method and property
-
-### Opening and Compiling a Project
-
-```
-Ask Claude: "Can you open the project at C:/MyProjects/TestProject.project using CODESYS Local and compile it?"
-```
-
-Claude will:
-1. Use `open_project` to open the specified file
-2. Use `compile_project` to build the application
-
-## 🔍 Troubleshooting
-
-### Common Issues
-
-- **Connection Failures**: Check Claude Desktop logs for error messages
-- **Path Issues**: Ensure CODESYS executable path is correct
-- **Profile Mismatch**: Verify profile name matches exactly
-- **Permission Problems**: Ensure Claude has appropriate permissions
-- **CODESYS Already Running**: Close other CODESYS instances
-
-### Debug Logs
-
-Check logs at:
-- Windows: `C:\Users\<YourUsername>\AppData\Roaming\Claude\logs\`
-
-## 🤝 Contributing
-
-Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
-
-## 📝 License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-## 🙏 Acknowledgements
-
-- The [CODESYS](https://www.codesys.com/) team for their scripting engine
-- [Model Context Protocol](https://github.com/m-ld/model-context-protocol) project
-- All contributors who have helped improve this toolkit
+# @codesys/mcp-toolkit
+
+![npm](https://img.shields.io/npm/v/@codesys/mcp-toolkit)
+![License](https://img.shields.io/github/license/yourusername/codesys-mcp-toolkit)
+
+A Model Context Protocol (MCP) server for CODESYS V3 programming environments. This toolkit enables seamless interaction between MCP clients (like Claude Desktop) and CODESYS, allowing automation of project management, POU creation, code editing, and compilation tasks.
+
+<p align="center">
+  <img src="https://github.com/yourusername/codesys-mcp-toolkit/raw/main/docs/assets/diagram.png" alt="CODESYS MCP Toolkit Architecture" width="600">
+</p>
+
+## 🌟 Features
+
+- **Project Management**
+  - Open existing CODESYS projects
+  - Create new projects from templates
+  - Save project changes
+
+- **POU Management**
+  - Create Programs, Function Blocks, and Functions
+  - Set declaration and implementation code
+  - Create properties and methods for Function Blocks
+  - Compile projects
+
+- **MCP Resources**
+  - `codesys://project/status`: Check scripting status and project state
+  - `codesys://project/{+project_path}/structure`: Retrieve project structure
+  - `codesys://project/{+project_path}/pou/{+pou_path}/code`: Read POU code
+
+- **MCP Tools**
+  - `open_project`: Open specified CODESYS project
+  - `create_project`: Create new CODESYS project
+  - `save_project`: Save currently open project
+  - `create_pou`: Create new Program, Function Block, or Function
+  - `set_pou_code`: Update code for a specified POU
+  - `create_property`: Create property in a Function Block
+  - `create_method`: Create method in a Function Block
+  - `compile_project`: Compile the open project
+
+## 📋 Prerequisites
+
+- **CODESYS V3**: A working CODESYS V3 installation (tested with 3.5 SP21) with **Scripting Engine** component enabled
+- **Node.js**: Version 18 or later required
+- **MCP Client**: An MCP-enabled application (e.g., Claude Desktop)
+
+## 🚀 Installation
+
+### Option 1: Install from npm (Recommended)
+
+```bash
+npm install -g @codesys/mcp-toolkit
+```
+
+This installs the package globally, making the `codesys-mcp-toolkit` command available in your terminal.
+
+### Option 2: Install from Source
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/codesys-mcp-toolkit.git
+cd codesys-mcp-toolkit
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Install globally
+npm install -g .
+```
+
+## 🔧 Configuration
+
+### Claude Desktop Configuration
+
+1. Locate your Claude Desktop configuration file:
+   - Windows: `C:\Users\<YourUsername>\AppData\Roaming\Claude\claude_desktop_config.json`
+
+2. Add the CODESYS MCP server entry:
+
+```json
+{
+  "mcpServers": {
+    "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"
+      ]
+    }
+  }
+}
+```
+
+3. Customize the paths to match your CODESYS installation:
+   - `--codesys-path`: Path to your CODESYS.exe
+   - `--codesys-profile`: Your CODESYS profile name
+
+4. Restart Claude Desktop to apply the changes
+
+## 🛠️ Usage Examples
+
+### Creating a Function Block with Properties
+
+```
+Ask Claude: "Using the CODESYS Local server, please create a Motor Controller function block with Start and Stop methods, plus CurrentSpeed property."
+```
+
+Claude will execute these MCP tool calls:
+1. `create_pou` to create the MotorController Function Block
+2. `create_property` to add the CurrentSpeed property
+3. `create_method` to add Start and Stop methods
+4. `set_pou_code` to implement each method and property
+
+### Opening and Compiling a Project
+
+```
+Ask Claude: "Can you open the project at C:/MyProjects/TestProject.project using CODESYS Local and compile it?"
+```
+
+Claude will:
+1. Use `open_project` to open the specified file
+2. Use `compile_project` to build the application
+
+## 🔍 Troubleshooting
+
+### Common Issues
+
+- **Connection Failures**: Check Claude Desktop logs for error messages
+- **Path Issues**: Ensure CODESYS executable path is correct
+- **Profile Mismatch**: Verify profile name matches exactly
+- **Permission Problems**: Ensure Claude has appropriate permissions
+- **CODESYS Already Running**: Close other CODESYS instances
+
+### Debug Logs
+
+Check logs at:
+- Windows: `C:\Users\<YourUsername>\AppData\Roaming\Claude\logs\`
+
+## 🤝 Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+## 📝 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgements
+
+- The [CODESYS](https://www.codesys.com/) team for their scripting engine
+- [Model Context Protocol](https://github.com/m-ld/model-context-protocol) project
+- All contributors who have helped improve this toolkit

package/dist/codesys_interop.js

@@ -7,6 +7,7 @@
  * - Creating temporary Python script files
  * - Executing them via CODESYS's scripting engine
  * - Capturing and processing results
+ * - Supporting both one-off script execution and persistent sessions
  *
  * IMPORTANT: Path handling for Windows is critical - paths with spaces require
  * special handling to avoid the 'C:\Program' not recognized error.
@@ -60,6 +61,8 @@ const promises_1 = require("fs/promises");
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const fs = __importStar(require("fs")); // Import fs for existsSync check
+// Optional import for session manager
+const sessionManager_1 = require("./sessionManager");
 // Define expected success/error markers from the Python scripts
 const SCRIPT_SUCCESS_MARKER = 'SCRIPT_SUCCESS';
 const SCRIPT_ERROR_MARKER = 'SCRIPT_ERROR';
@@ -69,12 +72,13 @@ const SCRIPT_ERROR_MARKER = 'SCRIPT_ERROR';
  * @param scriptContent The Python script code to execute.
  * @param codesysExePath The full path to the CODESYS.exe executable (can contain spaces).
  * @param codesysProfileName The name of the CODESYS profile to use for scripting.
+ * @param sessionManager Optional session manager for persistent session execution
  * @returns A promise resolving to an object containing the success status and the script's output.
  *
  * NOTE: Using shell: true with careful command string quoting to handle
  * CODESYS argument parsing quirks when launched non-interactively.
  */
-function executeCodesysScript(scriptContent, codesysExePath, codesysProfileName) {
+function executeCodesysScript(scriptContent, codesysExePath, codesysProfileName, sessionManager) {
     return __awaiter(this, void 0, void 0, function* () {
         // --- Pre-checks ---
         if (!codesysExePath)
@@ -84,6 +88,29 @@ function executeCodesysScript(scriptContent, codesysExePath, codesysProfileName)
         if (!fs.existsSync(codesysExePath))
             throw new Error(`CODESYS executable not found at provided path: ${codesysExePath}`);
         // --- End Pre-checks ---
+        // --- Check if we should use the persistent session ---
+        if (sessionManager) {
+            const sessionState = sessionManager.getState();
+            if (sessionState === sessionManager_1.SessionState.RUNNING || sessionState === sessionManager_1.SessionState.BUSY) {
+                process.stderr.write(`INTEROP: Using persistent session for script execution\n`);
+                try {
+                    const result = yield sessionManager.executeScript(scriptContent);
+                    return {
+                        success: result.success,
+                        output: result.output
+                    };
+                }
+                catch (error) {
+                    process.stderr.write(`INTEROP: Error executing script in persistent session: ${error.message}\n`);
+                    process.stderr.write(`INTEROP: Falling back to one-time execution mode\n`);
+                    // Continue with the non-persistent approach as fallback
+                }
+            }
+            else {
+                process.stderr.write(`INTEROP: Session not in RUNNING/BUSY state (current: ${sessionState}). Using one-time execution.\n`);
+            }
+        }
+        // --- Standard one-time script execution ---
         const tempDir = os.tmpdir();
         const tempFileName = `codesys_script_${Date.now()}_${Math.random().toString(36).substring(2, 9)}.py`;
         const tempFilePath = path.join(tempDir, tempFileName); // Path module uses OS-specific separators ('\' on Windows)
@@ -118,7 +145,7 @@ function executeCodesysScript(scriptContent, codesysExePath, codesysProfileName)
             process.stderr.write(`INTEROP ENV: Forcing CWD for spawn: ${codesysDir}\n`); // Re-enabled CWD change
             // --- Create modified environment (Re-enabled) ---
             const spawnEnv = Object.assign({}, process.env);
-            const pathSeparator = ';'; // Windows
+            const pathSeparator = os.platform() === 'win32' ? ';' : ':';
             const originalPath = spawnEnv.PATH || '';
             spawnEnv.PATH = `${codesysDir}${pathSeparator}${originalPath}`; // Prepend CODESYS dir to PATH
             process.stderr.write(`INTEROP ENV: MODIFIED PATH for spawn (prepended): ${spawnEnv.PATH.substring(0, 100)}...\n`); // Re-enabled ENV change

package/dist/scripts/check_status.py

@@ -0,0 +1,21 @@
+import sys, scriptengine as script_engine, os, traceback
+project_open = False; project_name = "No project open"; project_path = "N/A"; scripting_ok = False
+try:
+    scripting_ok = True; primary_project = script_engine.projects.primary
+    if primary_project:
+        project_open = True
+        try:
+            project_path = os.path.normcase(os.path.abspath(primary_project.path))
+            try:
+                 project_name = primary_project.get_name() # Might fail
+                 if not project_name: project_name = "Unnamed (path: %s)" % os.path.basename(project_path)
+            except: project_name = "Unnamed (path: %s)" % os.path.basename(project_path)
+        except Exception as e_path: project_path = "N/A (Error: %s)" % e_path; project_name = "Unnamed (Path Error)"
+    print("Project Open: %s" % project_open); print("Project Name: %s" % project_name)
+    print("Project Path: %s" % project_path); print("Scripting OK: %s" % scripting_ok)
+    print("SCRIPT_SUCCESS: Status check complete."); sys.exit(0)
+except Exception as e:
+    error_message = "Error during status check: %s" % e
+    print(error_message); print("Scripting OK: False")
+    # traceback.print_exc() # Optional traceback
+    print("SCRIPT_ERROR: %s" % error_message); sys.exit(1)

package/dist/scripts/compile_project.py

@@ -0,0 +1,65 @@
+import sys, scriptengine as script_engine, os, traceback
+
+# Import ensure_project_open function from the template
+# This will be prepended by the script loader
+def ensure_project_open(target_project_path):
+    # Function implementation will be included from ensure_project_open.py
+    pass
+
+try:
+    print("DEBUG: compile_project script: Project='%s'" % PROJECT_FILE_PATH)
+    primary_project = ensure_project_open(PROJECT_FILE_PATH)
+    project_name = os.path.basename(PROJECT_FILE_PATH)
+    target_app = None
+    app_name = "N/A"
+
+    # Try getting active application first
+    try:
+        target_app = primary_project.active_application
+        if target_app:
+            app_name = getattr(target_app, 'get_name', lambda: "Unnamed App (Active)")()
+            print("DEBUG: Found active application: %s" % app_name)
+    except Exception as active_err:
+        print("WARN: Could not get active application: %s. Searching..." % active_err)
+
+    # If no active app, search for the first one
+    if not target_app:
+        print("DEBUG: Searching for first compilable application...")
+        apps = []
+        try:
+             # Search recursively through all project objects
+             all_children = primary_project.get_children(True)
+             for child in all_children:
+                  # Check using the marker property and if build method exists
+                  if hasattr(child, 'is_application') and child.is_application and hasattr(child, 'build'):
+                       app_name_found = getattr(child, 'get_name', lambda: "Unnamed App")()
+                       print("DEBUG: Found potential application object: %s" % app_name_found)
+                       apps.append(child)
+                       break # Take the first one found
+        except Exception as find_err: print("WARN: Error finding application object: %s" % find_err)
+
+        if not apps: raise RuntimeError("No compilable application found in project '%s'" % project_name)
+        target_app = apps[0]
+        app_name = getattr(target_app, 'get_name', lambda: "Unnamed App (First Found)")()
+        print("WARN: Compiling first found application: %s" % app_name)
+
+    print("DEBUG: Calling build() on app '%s'..." % app_name)
+    if not hasattr(target_app, 'build'):
+         raise TypeError("Selected object '%s' is not an application or doesn't support build()." % app_name)
+
+    # Execute the build
+    target_app.build();
+    print("DEBUG: Build command executed for application '%s'." % app_name)
+
+    # Check messages is harder without direct access to message store from script.
+    # Rely on CODESYS UI or log output for now.
+    print("Compile Initiated For Application: %s" % app_name)
+    print("In Project: %s" % project_name)
+    print("SCRIPT_SUCCESS: Application compilation initiated.")
+    sys.exit(0)
+except Exception as e:
+    detailed_error = traceback.format_exc()
+    error_message = "Error initiating compilation for project %s: %s\\n%s" % (PROJECT_FILE_PATH, e, detailed_error)
+    print(error_message)
+    print("SCRIPT_ERROR: %s" % error_message)
+    sys.exit(1)

package/dist/scripts/create_method.py

@@ -0,0 +1,80 @@
+import sys, scriptengine as script_engine, os, traceback
+
+# Import ensure_project_open function from the template
+# This will be prepended by the script loader
+def ensure_project_open(target_project_path):
+    # Function implementation will be included from ensure_project_open.py
+    pass
+
+# Import find_object_by_path function from the template
+# This will be prepended by the script loader
+def find_object_by_path_robust(start_node, full_path, target_type_name="object"):
+    # Function implementation will be included from find_object_by_path.py
+    pass
+
+PARENT_POU_FULL_PATH = "{PARENT_POU_FULL_PATH}" # e.g., "Application/MyFB"
+METHOD_NAME = "{METHOD_NAME}"
+RETURN_TYPE = "{RETURN_TYPE}" # Can be empty string for no return type
+# Optional: Language
+# LANG_GUID_STR = "{LANG_GUID_STR}" # Example if needed
+
+try:
+    print("DEBUG: create_method script: ParentPOU='%s', Name='%s', ReturnType='%s', Project='%s'" % (PARENT_POU_FULL_PATH, METHOD_NAME, RETURN_TYPE, PROJECT_FILE_PATH))
+    primary_project = ensure_project_open(PROJECT_FILE_PATH)
+    if not PARENT_POU_FULL_PATH: raise ValueError("Parent POU full path empty.")
+    if not METHOD_NAME: raise ValueError("Method name empty.")
+    # RETURN_TYPE can be empty
+
+    # Find the parent POU object
+    parent_pou_object = find_object_by_path_robust(primary_project, PARENT_POU_FULL_PATH, "parent POU")
+    if not parent_pou_object: raise ValueError("Parent POU object not found: %s" % PARENT_POU_FULL_PATH)
+
+    parent_pou_name = getattr(parent_pou_object, 'get_name', lambda: PARENT_POU_FULL_PATH)()
+    print("DEBUG: Found Parent POU object: %s" % parent_pou_name)
+
+     # Check if parent object supports creating methods (should implement ScriptIecLanguageMemberContainer)
+    if not hasattr(parent_pou_object, 'create_method'):
+         raise TypeError("Parent object '%s' of type %s does not support create_method." % (parent_pou_name, type(parent_pou_object).__name__))
+
+    # Default language to None (usually ST)
+    lang_guid = None
+    # Use None if RETURN_TYPE is empty string, otherwise use the string
+    actual_return_type = RETURN_TYPE if RETURN_TYPE else None
+    print("DEBUG: Calling create_method: Name='%s', ReturnType=%s, Lang=%s" % (METHOD_NAME, actual_return_type, lang_guid))
+
+    # Call the create_method method ON THE PARENT POU
+    new_method_object = parent_pou_object.create_method(
+        name=METHOD_NAME,
+        return_type=actual_return_type,
+        language=lang_guid # Pass None to use default
+    )
+
+    if new_method_object:
+        new_meth_name = getattr(new_method_object, 'get_name', lambda: METHOD_NAME)()
+        print("DEBUG: Method object created: %s" % new_meth_name)
+
+        # --- SAVE THE PROJECT TO PERSIST THE NEW METHOD OBJECT ---
+        try:
+            print("DEBUG: Saving Project (after method creation)...")
+            primary_project.save()
+            print("DEBUG: Project saved successfully after method creation.")
+        except Exception as save_err:
+            print("ERROR: Failed to save Project after creating method: %s" % save_err)
+            detailed_error = traceback.format_exc()
+            error_message = "Error saving Project after creating method '%s': %s\\n%s" % (METHOD_NAME, save_err, detailed_error)
+            print(error_message); print("SCRIPT_ERROR: %s" % error_message); sys.exit(1)
+        # --- END SAVING ---
+
+        print("Method Created: %s" % new_meth_name)
+        print("Parent POU: %s" % PARENT_POU_FULL_PATH)
+        print("Return Type: %s" % (RETURN_TYPE if RETURN_TYPE else "(None)"))
+        print("SCRIPT_SUCCESS: Method created successfully.")
+        sys.exit(0)
+    else:
+         error_message = "Failed to create method '%s' under '%s'. create_method returned None." % (METHOD_NAME, parent_pou_name)
+         print(error_message); print("SCRIPT_ERROR: %s" % error_message); sys.exit(1)
+
+except Exception as e:
+    detailed_error = traceback.format_exc()
+    error_message = "Error creating method '%s' under POU '%s' in project '%s': %s\\n%s" % (METHOD_NAME, PARENT_POU_FULL_PATH, PROJECT_FILE_PATH, e, detailed_error)
+    print(error_message); print("SCRIPT_ERROR: %s" % error_message); sys.exit(1)

package/dist/scripts/create_pou.py

@@ -0,0 +1,96 @@
+import sys, scriptengine as script_engine, os, traceback
+
+# Import ensure_project_open function from the template
+# This will be prepended by the script loader
+def ensure_project_open(target_project_path):
+    # Function implementation will be included from ensure_project_open.py
+    pass
+
+# Import find_object_by_path function from the template
+# This will be prepended by the script loader
+def find_object_by_path_robust(start_node, full_path, target_type_name="object"):
+    # Function implementation will be included from find_object_by_path.py
+    pass
+
+POU_NAME = "{POU_NAME}"
+POU_TYPE_STR = "{POU_TYPE_STR}" 
+IMPL_LANGUAGE_STR = "{IMPL_LANGUAGE_STR}"
+PARENT_PATH_REL = "{PARENT_PATH}"
+
+pou_type_map = { 
+    "Program": script_engine.PouType.Program, 
+    "FunctionBlock": script_engine.PouType.FunctionBlock, 
+    "Function": script_engine.PouType.Function 
+}
+# Map common language names to ImplementationLanguages attributes if needed (optional, None usually works)
+# lang_map = { "ST": script_engine.ImplementationLanguage.st, ... }
+
+try:
+    print("DEBUG: create_pou script: Name='%s', Type='%s', Lang='%s', ParentPath='%s', Project='%s'" % (POU_NAME, POU_TYPE_STR, IMPL_LANGUAGE_STR, PARENT_PATH_REL, PROJECT_FILE_PATH))
+    primary_project = ensure_project_open(PROJECT_FILE_PATH)
+    if not POU_NAME: raise ValueError("POU name empty.")
+    if not PARENT_PATH_REL: raise ValueError("Parent path empty.")
+
+    # Resolve POU Type Enum
+    pou_type_enum = pou_type_map.get(POU_TYPE_STR)
+    if not pou_type_enum: raise ValueError("Invalid POU type string: %s. Use Program, FunctionBlock, or Function." % POU_TYPE_STR)
+
+    # Find parent object using the robust function
+    parent_object = find_object_by_path_robust(primary_project, PARENT_PATH_REL, "parent container")
+    if not parent_object: raise ValueError("Parent object not found for path: %s" % PARENT_PATH_REL)
+
+    parent_name = getattr(parent_object, 'get_name', lambda: str(parent_object))()
+    print("DEBUG: Using parent object: %s (Type: %s)" % (parent_name, type(parent_object).__name__))
+
+    # Check if parent object supports creating POUs (should implement ScriptIecLanguageObjectContainer)
+    if not hasattr(parent_object, 'create_pou'):
+        raise TypeError("Parent object '%s' of type %s does not support create_pou." % (parent_name, type(parent_object).__name__))
+
+    # Set language GUID to None (let CODESYS default based on parent/settings)
+    lang_guid = None
+    print("DEBUG: Setting language to None (will use default).")
+    # Example if mapping language string: lang_guid = lang_map.get(IMPL_LANGUAGE_STR, None)
+
+    print("DEBUG: Calling parent_object.create_pou: Name='%s', Type=%s, Lang=%s" % (POU_NAME, pou_type_enum, lang_guid))
+
+    # Call create_pou using keyword arguments
+    new_pou = parent_object.create_pou(
+        name=POU_NAME,
+        type=pou_type_enum,
+        language=lang_guid # Pass None
+    )
+
+    print("DEBUG: parent_object.create_pou returned: %s" % new_pou)
+    if new_pou:
+        new_pou_name = getattr(new_pou, 'get_name', lambda: POU_NAME)()
+        print("DEBUG: POU object created: %s" % new_pou_name)
+
+        # --- SAVE THE PROJECT TO PERSIST THE NEW POU ---
+        try:
+            print("DEBUG: Saving Project...")
+            primary_project.save() # Save the overall project file
+            print("DEBUG: Project saved successfully after POU creation.")
+        except Exception as save_err:
+            print("ERROR: Failed to save Project after POU creation: %s" % save_err)
+            detailed_error = traceback.format_exc()
+            error_message = "Error saving Project after creating POU '%s': %s\\n%s" % (new_pou_name, save_err, detailed_error)
+            print(error_message); print("SCRIPT_ERROR: %s" % error_message); sys.exit(1)
+        # --- END SAVING ---
+
+        print("POU Created: %s" % new_pou_name)
+        print("Type: %s" % POU_TYPE_STR)
+        print("Language: %s (Defaulted)" % IMPL_LANGUAGE_STR)
+        print("Parent Path: %s" % PARENT_PATH_REL)
+        print("SCRIPT_SUCCESS: POU created successfully.")
+        sys.exit(0)
+    else:
+        error_message = "Failed to create POU '%s'. create_pou returned None." % POU_NAME
+        print(error_message)
+        print("SCRIPT_ERROR: %s" % error_message)
+        sys.exit(1)
+except Exception as e:
+    detailed_error = traceback.format_exc()
+    error_message = "Error creating POU '%s' in project '%s': %s\\n%s" % (POU_NAME, PROJECT_FILE_PATH, e, detailed_error)
+    print(error_message)
+    print("SCRIPT_ERROR: Error creating POU '%s': %s" % (POU_NAME, e))
+    sys.exit(1)