@codesys/mcp-toolkit 1.1.5 → 1.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codesys/mcp-toolkit",
-  "version": "1.1.5",
+  "version": "1.1.7",
   "description": "Model Context Protocol (MCP) server for CODESYS automation platform",
   "main": "dist/server.js",
   "bin": {
@@ -8,7 +8,9 @@
   },
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
-    "build": "tsc",
+    "prebuild": "rm -rf dist",
+    "build": "tsc && npm run copy-scripts",
+    "copy-scripts": "mkdir -p dist/scripts && cp -r src/scripts/* dist/scripts/",
     "start": "node ./dist/server.js"
   },
   "keywords": [
@@ -33,6 +35,16 @@
   "engines": {
     "node": ">=18.0.0"
   },
+  "files": [
+    "dist/",
+    "src/scripts/",
+    "docs/",
+    "examples/",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "scriptDoc.txt"
+  ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.10.2",
     "axios": "^1.6.8",
@@ -41,8 +53,8 @@
     "zod": "^3.24.3"
   },
   "devDependencies": {
-    "@types/node": "^20.17.32",
+    "@types/node": "^20.14.1",
     "@types/yargs": "^17.0.33",
-    "typescript": "^5.5.3"
+    "typescript": "^5.8.3"
   }
 }

package/src/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/src/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/src/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/src/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)

package/src/scripts/create_project.py

@@ -0,0 +1,54 @@
+import sys, scriptengine as script_engine, os, shutil, time, traceback
+# Placeholders
+TEMPLATE_PROJECT_PATH = r'{TEMPLATE_PROJECT_PATH}' # Path to Standard.project
+PROJECT_FILE_PATH = r'{PROJECT_FILE_PATH}'    # Path for the new project (Target Path)
+try:
+    print("DEBUG: Python script create_project (copy from template):")
+    print("DEBUG:   Template Source = %s" % TEMPLATE_PROJECT_PATH)
+    print("DEBUG:   Target Path = %s" % PROJECT_FILE_PATH)
+    if not PROJECT_FILE_PATH: raise ValueError("Target project file path empty.")
+    if not TEMPLATE_PROJECT_PATH: raise ValueError("Template project file path empty.")
+    if not os.path.exists(TEMPLATE_PROJECT_PATH): raise IOError("Template project file not found: %s" % TEMPLATE_PROJECT_PATH)
+
+    # 1. Copy the template project file to the new location
+    target_dir = os.path.dirname(PROJECT_FILE_PATH)
+    if not os.path.exists(target_dir): print("DEBUG: Creating target directory: %s" % target_dir); os.makedirs(target_dir)
+    # Check if target file already exists
+    if os.path.exists(PROJECT_FILE_PATH): print("WARN: Target project file already exists, overwriting: %s" % PROJECT_FILE_PATH)
+
+    print("DEBUG: Copying '%s' to '%s'..." % (TEMPLATE_PROJECT_PATH, PROJECT_FILE_PATH))
+    shutil.copy2(TEMPLATE_PROJECT_PATH, PROJECT_FILE_PATH) # copy2 preserves metadata
+    print("DEBUG: File copy complete.")
+
+    # 2. Open the newly copied project file
+    print("DEBUG: Opening the copied project: %s" % PROJECT_FILE_PATH)
+    # Set flags for silent opening
+    update_mode = script_engine.VersionUpdateFlags.NoUpdates | script_engine.VersionUpdateFlags.SilentMode
+    # try:
+    #     update_mode = script_engine.VersionUpdateFlags.NoUpdates | script_engine.VersionUpdateFlags.SilentMode
+    # except AttributeError:
+    #     print("WARN: VersionUpdateFlags not found, using integer flags for open (1 | 2 = 3).")
+    #     update_mode = 3
+
+    project = script_engine.projects.open(PROJECT_FILE_PATH, update_flags=update_mode)
+    print("DEBUG: script_engine.projects.open returned: %s" % project)
+    if project:
+        print("DEBUG: Pausing briefly after open...")
+        time.sleep(1.0) # Allow CODESYS to potentially initialize things
+        try:
+            print("DEBUG: Explicitly saving project after opening copy...")
+            project.save();
+            print("DEBUG: Project save after opening copy succeeded.")
+        except Exception as save_err:
+             print("WARN: Explicit save after opening copy failed: %s" % save_err)
+             # Decide if this is critical - maybe not, but good to know.
+        print("Project Created from Template Copy at: %s" % PROJECT_FILE_PATH)
+        print("SCRIPT_SUCCESS: Project copied from template and opened successfully.")
+        sys.exit(0)
+    else:
+        error_message = "Failed to open project copy %s after copying template %s. projects.open returned None." % (PROJECT_FILE_PATH, TEMPLATE_PROJECT_PATH)
+        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 project '%s' from template '%s': %s\\n%s" % (PROJECT_FILE_PATH, TEMPLATE_PROJECT_PATH, e, detailed_error)
+    print(error_message); print("SCRIPT_ERROR: Error copying/opening template: %s" % e); sys.exit(1)

package/src/scripts/create_property.py

@@ -0,0 +1,78 @@
+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"
+PROPERTY_NAME = "{PROPERTY_NAME}"
+PROPERTY_TYPE = "{PROPERTY_TYPE}"
+# Optional: Language for Getter/Setter (usually defaults to ST)
+# LANG_GUID_STR = "{LANG_GUID_STR}" # Example if needed
+
+try:
+    print("DEBUG: create_property script: ParentPOU='%s', Name='%s', Type='%s', Project='%s'" % (PARENT_POU_FULL_PATH, PROPERTY_NAME, PROPERTY_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 PROPERTY_NAME: raise ValueError("Property name empty.")
+    if not PROPERTY_TYPE: raise ValueError("Property type 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 properties (should implement ScriptIecLanguageMemberContainer)
+    if not hasattr(parent_pou_object, 'create_property'):
+         raise TypeError("Parent object '%s' of type %s does not support create_property." % (parent_pou_name, type(parent_pou_object).__name__))
+
+    # Default language to None (usually ST)
+    lang_guid = None
+    print("DEBUG: Calling create_property: Name='%s', Type='%s', Lang=%s" % (PROPERTY_NAME, PROPERTY_TYPE, lang_guid))
+
+    # Call the create_property method ON THE PARENT POU
+    new_property_object = parent_pou_object.create_property(
+        name=PROPERTY_NAME,
+        return_type=PROPERTY_TYPE,
+        language=lang_guid # Pass None to use default
+    )
+
+    if new_property_object:
+        new_prop_name = getattr(new_property_object, 'get_name', lambda: PROPERTY_NAME)()
+        print("DEBUG: Property object created: %s" % new_prop_name)
+
+        # --- SAVE THE PROJECT TO PERSIST THE NEW PROPERTY OBJECT ---
+        try:
+            print("DEBUG: Saving Project (after property creation)...")
+            primary_project.save()
+            print("DEBUG: Project saved successfully after property creation.")
+        except Exception as save_err:
+            print("ERROR: Failed to save Project after creating property: %s" % save_err)
+            detailed_error = traceback.format_exc()
+            error_message = "Error saving Project after creating property '%s': %s\\n%s" % (PROPERTY_NAME, save_err, detailed_error)
+            print(error_message); print("SCRIPT_ERROR: %s" % error_message); sys.exit(1)
+        # --- END SAVING ---
+
+        print("Property Created: %s" % new_prop_name)
+        print("Parent POU: %s" % PARENT_POU_FULL_PATH)
+        print("Type: %s" % PROPERTY_TYPE)
+        print("SCRIPT_SUCCESS: Property created successfully.")
+        sys.exit(0)
+    else:
+         error_message = "Failed to create property '%s' under '%s'. create_property returned None." % (PROPERTY_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 property '%s' under POU '%s' in project '%s': %s\\n%s" % (PROPERTY_NAME, PARENT_POU_FULL_PATH, PROJECT_FILE_PATH, e, detailed_error)
+    print(error_message); print("SCRIPT_ERROR: %s" % error_message); sys.exit(1)

package/src/scripts/ensure_project_open.py

@@ -0,0 +1,154 @@
+import sys
+import scriptengine as script_engine
+import os
+import time
+import traceback
+
+# --- Function to ensure the correct project is open ---
+MAX_RETRIES = 3
+RETRY_DELAY = 2.0 # seconds (use float for time.sleep)
+
+def ensure_project_open(target_project_path):
+    print("DEBUG: Ensuring project is open: %s" % target_project_path)
+    # Normalize target path once
+    normalized_target_path = os.path.normcase(os.path.abspath(target_project_path))
+
+    for attempt in range(MAX_RETRIES):
+        print("DEBUG: Ensure project attempt %d/%d for %s" % (attempt + 1, MAX_RETRIES, normalized_target_path))
+        primary_project = None
+        try:
+            # Getting primary project might fail if CODESYS instance is unstable
+            primary_project = script_engine.projects.primary
+        except Exception as primary_err:
+             print("WARN: Error getting primary project: %s. Assuming none." % primary_err)
+             # traceback.print_exc() # Optional: Print stack trace for this error
+             primary_project = None
+
+        current_project_path = ""
+        project_ok = False # Flag to check if target is confirmed primary and accessible
+
+        if primary_project:
+            try:
+                # Getting path should be relatively safe if primary_project object exists
+                current_project_path = os.path.normcase(os.path.abspath(primary_project.path))
+                print("DEBUG: Current primary project path: %s" % current_project_path)
+                if current_project_path == normalized_target_path:
+                    # Found the right project as primary, now check if it's usable
+                    print("DEBUG: Target project path matches primary. Checking access...")
+                    try:
+                         # Try a relatively safe operation to confirm object usability
+                         # Getting children count is a reasonable check
+                         _ = len(primary_project.get_children(False))
+                         print("DEBUG: Target project '%s' is primary and accessible." % target_project_path)
+                         project_ok = True
+                         return primary_project # SUCCESS CASE 1: Already open and accessible
+                    except Exception as access_err:
+                         # Project found, but accessing it failed. Might be unstable.
+                         print("WARN: Primary project access check failed for '%s': %s. Will attempt reopen." % (current_project_path, access_err))
+                         # traceback.print_exc() # Optional: Print stack trace
+                         primary_project = None # Force reopen by falling through
+                else:
+                    # A *different* project is primary
+                     print("DEBUG: Primary project is '%s', not the target '%s'." % (current_project_path, normalized_target_path))
+                     # Consider closing the wrong project if causing issues, but for now, just open target
+                     # try:
+                     #     print("DEBUG: Closing incorrect primary project '%s'..." % current_project_path)
+                     #     primary_project.close() # Be careful with unsaved changes
+                     # except Exception as close_err:
+                     #     print("WARN: Failed to close incorrect primary project: %s" % close_err)
+                     primary_project = None # Force open target project
+
+            except Exception as path_err:
+                 # Failed even to get the path of the supposed primary project
+                 print("WARN: Could not get path of current primary project: %s. Assuming not the target." % path_err)
+                 # traceback.print_exc() # Optional: Print stack trace
+                 primary_project = None # Force open target project
+
+        # If target project not confirmed as primary and accessible, attempt to open/reopen
+        if not project_ok:
+            # Log clearly whether we are opening initially or reopening
+            if primary_project is None and current_project_path == "":
+                print("DEBUG: No primary project detected. Attempting to open target: %s" % target_project_path)
+            elif primary_project is None and current_project_path != "":
+                 print("DEBUG: Primary project was '%s' but failed access check or needed close. Attempting to open target: %s" % (current_project_path, target_project_path))
+            else: # Includes cases where wrong project was open
+                print("DEBUG: Target project not primary or initial check failed. Attempting to open/reopen: %s" % target_project_path)
+
+            try:
+                # Set flags for silent opening, handle potential attribute errors
+                update_mode = script_engine.VersionUpdateFlags.NoUpdates | script_engine.VersionUpdateFlags.SilentMode
+                # try:
+                #     update_mode = script_engine.VersionUpdateFlags.NoUpdates | script_engine.VersionUpdateFlags.SilentMode
+                # except AttributeError:
+                #     print("WARN: VersionUpdateFlags not found, using integer flags for open (1 | 2 = 3).")
+                #     update_mode = 3 # 1=NoUpdates, 2=SilentMode
+
+                opened_project = None
+                try:
+                     # The actual open call
+                     print("DEBUG: Calling script_engine.projects.open('%s', update_flags=%s)..." % (target_project_path, update_mode))
+                     opened_project = script_engine.projects.open(target_project_path, update_flags=update_mode)
+
+                     if not opened_project:
+                         # This is a critical failure if open returns None without exception
+                         print("ERROR: projects.open returned None for %s on attempt %d" % (target_project_path, attempt + 1))
+                         # Allow retry loop to continue
+                     else:
+                         # Open call returned *something*, let's verify
+                         print("DEBUG: projects.open call returned an object for: %s" % target_project_path)
+                         print("DEBUG: Pausing for stabilization after open...")
+                         time.sleep(RETRY_DELAY) # Give CODESYS time
+                         # Re-verify: Is the project now primary and accessible?
+                         recheck_primary = None
+                         try: recheck_primary = script_engine.projects.primary
+                         except Exception as recheck_primary_err: print("WARN: Error getting primary project after reopen: %s" % recheck_primary_err)
+
+                         if recheck_primary:
+                              recheck_path = ""
+                              try: # Getting path might fail
+                                  recheck_path = os.path.normcase(os.path.abspath(recheck_primary.path))
+                              except Exception as recheck_path_err:
+                                  print("WARN: Failed to get path after reopen: %s" % recheck_path_err)
+
+                              if recheck_path == normalized_target_path:
+                                   print("DEBUG: Target project confirmed as primary after reopening.")
+                                   try: # Final sanity check
+                                       _ = len(recheck_primary.get_children(False))
+                                       print("DEBUG: Reopened project basic access confirmed.")
+                                       return recheck_primary # SUCCESS CASE 2: Successfully opened/reopened
+                                   except Exception as access_err_reopen:
+                                        print("WARN: Reopened project (%s) basic access check failed: %s." % (normalized_target_path, access_err_reopen))
+                                        # traceback.print_exc() # Optional
+                                        # Allow retry loop to continue
+                              else:
+                                   print("WARN: Different project is primary after reopening! Expected '%s', got '%s'." % (normalized_target_path, recheck_path))
+                                   # Allow retry loop to continue, maybe it fixes itself
+                         else:
+                               print("WARN: No primary project found after reopening attempt %d!" % (attempt+1))
+                               # Allow retry loop to continue
+
+                except Exception as open_err:
+                     # Catch errors during the open call itself
+                     print("ERROR: Exception during projects.open call on attempt %d: %s" % (attempt + 1, open_err))
+                     traceback.print_exc() # Crucial for diagnosing open failures
+                     # Allow retry loop to continue
+
+            except Exception as outer_open_err:
+                 # Catch errors in the flag setup etc.
+                 print("ERROR: Unexpected error during open setup/logic attempt %d: %s" % (attempt + 1, outer_open_err))
+                 traceback.print_exc()
+
+        # If we didn't return successfully in this attempt, wait before retrying
+        if attempt < MAX_RETRIES - 1:
+            print("DEBUG: Ensure project attempt %d did not succeed. Waiting %f seconds..." % (attempt + 1, RETRY_DELAY))
+            time.sleep(RETRY_DELAY)
+        else: # Last attempt failed
+             print("ERROR: Failed all ensure_project_open attempts for %s." % normalized_target_path)
+
+
+    # If all retries fail after the loop
+    raise RuntimeError("Failed to ensure project '%s' is open and accessible after %d attempts." % (target_project_path, MAX_RETRIES))
+# --- End of function ---
+
+# Placeholder for the project file path (must be set in scripts using this snippet)
+PROJECT_FILE_PATH = r"{PROJECT_FILE_PATH}"