@codesys/mcp-toolkit 1.1.8 → 1.1.10

package/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.10] - 2025-05-06
+
+### Fixed
+- Improved handling of Windows paths in `get_project_structure` and `ensure_project_open` functions
+- Enhanced error handling and debugging for project structure tool
+- Added more detailed logging to help diagnose connection issues with CODESYS
+
+## [1.1.9] - 2025-05-06
+
+### Added
+- Added three new MCP tools that were previously only available as resources:
+  - `check_status`: Tool to check CODESYS environment and open project status
+  - `get_project_structure`: Tool to retrieve the structure of a CODESYS project
+  - `get_pou_code`: Tool to retrieve code from a specific POU
+- These tools allow Claude and other AI assistants to directly access project inspection functionality
+
 ## [1.1.8] - 2025-05-06
 
 ### Fixed

package/dist/scripts/ensure_project_open.py

@@ -8,10 +8,31 @@ import traceback
 MAX_RETRIES = 3
 RETRY_DELAY = 2.0 # seconds (use float for time.sleep)
 
+# Special handling for Windows paths
+def sanitize_windows_path(path_str):
+    """Properly sanitize Windows paths for CODESYS scripting"""
+    # If it's already a Python raw string literal, return it as is
+    if path_str.startswith('r"') or path_str.startswith("r'"):
+        return path_str
+        
+    # Make Windows paths with backslashes work correctly when passed to CODESYS
+    # We use actual backslashes (which will be doubled by Python raw string)
+    sanitized = path_str.replace('\\', '\\\\')
+    
+    # Clean up any extraneous quotes
+    sanitized = sanitized.strip('"\'')
+    
+    print(f"DEBUG: Sanitized path from '{path_str}' to '{sanitized}'")
+    return sanitized
+
 def ensure_project_open(target_project_path):
     print("DEBUG: Ensuring project is open: %s" % target_project_path)
+    
+    # First sanitize the path for proper Windows path handling
+    sanitized_path = sanitize_windows_path(target_project_path)
+    
     # Normalize target path once
-    normalized_target_path = os.path.normcase(os.path.abspath(target_project_path))
+    normalized_target_path = os.path.normcase(os.path.abspath(sanitized_path))
 
     for attempt in range(MAX_RETRIES):
         print("DEBUG: Ensure project attempt %d/%d for %s" % (attempt + 1, MAX_RETRIES, normalized_target_path))
@@ -100,8 +121,12 @@ def ensure_project_open(target_project_path):
                          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)
+                         try: 
+                             recheck_primary = script_engine.projects.primary
+                             print(f"DEBUG: Recheck primary project type: {type(recheck_primary).__name__}")
+                         except Exception as recheck_primary_err: 
+                             print("WARN: Error getting primary project after reopen: %s" % recheck_primary_err)
+                             traceback.print_exc() # Print full trace for primary project access issue
 
                          if recheck_primary:
                               recheck_path = ""

package/dist/scripts/get_project_structure.py

@@ -8,9 +8,14 @@ def ensure_project_open(target_project_path):
 
 def get_object_structure(obj, indent=0, max_depth=10): # Add max_depth
     lines = []; indent_str = "  " * indent
+    if obj is None:
+        lines.append("%s- ERROR: Null object received" % indent_str)
+        return lines
+        
     if indent > max_depth:
         lines.append("%s- Max recursion depth reached." % indent_str)
         return lines
+        
     try:
         name = "Unnamed"; obj_type = type(obj).__name__
         guid_str = ""
@@ -37,10 +42,10 @@ def get_object_structure(obj, indent=0, max_depth=10): # Add max_depth
         if can_have_children:
             try:
                 children = obj.get_children(False)
-                # print("DEBUG: %s has %d children" % (name, len(children))) # Verbose
+                print("DEBUG: '%s' has %d children" % (name, len(children)))
             except Exception as get_child_err:
                 lines.append("%s  ERROR getting children: %s" % (indent_str, get_child_err))
-                # traceback.print_exc() # Optional
+                traceback.print_exc() # Now print detailed error
 
         for child in children:
             lines.extend(get_object_structure(child, indent + 1, max_depth)) # Recurse
@@ -49,15 +54,63 @@ def get_object_structure(obj, indent=0, max_depth=10): # Add max_depth
         lines.append("%s- Error processing node: %s" % (indent_str, e))
         traceback.print_exc() # Print detailed error for this node
     return lines
+
+# Normalize Windows paths for CODESYS scripting
+def normalize_path(path_str):
+    # Replace backslashes with double backslashes for Python string in CODESYS
+    normalized = path_str.replace('\\', '\\\\')
+    # Remove any quotes that might be present
+    normalized = normalized.strip('"\'')
+    print(f"DEBUG: Normalized path from '{path_str}' to '{normalized}'")
+    return normalized
     
 try:
-    print("DEBUG: Getting structure for: %s" % PROJECT_FILE_PATH)
-    primary_project = ensure_project_open(PROJECT_FILE_PATH)
-    project_name = os.path.basename(PROJECT_FILE_PATH)
-    print("DEBUG: Getting structure for project: %s" % project_name)
+    # Normalize the project path for CODESYS
+    normalized_path = normalize_path(PROJECT_FILE_PATH)
+    print("DEBUG: Getting structure for project path: '%s'" % normalized_path)
+    
+    # First confirm that CODESYS is running properly
+    print("DEBUG: CODESYS version info:")
+    try:
+        version_info = script_engine.get_version_info()
+        print(f"DEBUG: CODESYS Version: {version_info}")
+    except Exception as v_err:
+        print(f"DEBUG: Error getting CODESYS version: {v_err}")
+    
+    print("DEBUG: Opening project...")
+    primary_project = ensure_project_open(normalized_path)
+    
+    if primary_project is None:
+        print("DEBUG: ERROR - Project object is None after ensure_project_open")
+        raise ValueError(f"Failed to open project: {normalized_path} - project object is None")
+        
+    print("DEBUG: Project object type: %s" % type(primary_project).__name__)
+    project_name = os.path.basename(normalized_path)
+    
+    if hasattr(primary_project, 'get_name'):
+        print("DEBUG: Project name from object: %s" % primary_project.get_name())
+    else:
+        print("DEBUG: Project object does not have get_name() method")
+        
+    # Check if project has useful methods
+    if hasattr(primary_project, 'get_children'):
+        print("DEBUG: Project has get_children method")
+    else:
+        print("DEBUG: WARNING - Project does not have get_children method")
+        
+    if hasattr(primary_project, 'active_application'):
+        print("DEBUG: Project has active_application property")
+        app = primary_project.active_application
+        if app:
+            print("DEBUG: Active application name: %s" % getattr(app, 'get_name', lambda: "Unknown")())
+    else:
+        print("DEBUG: WARNING - Project does not have active_application property")
+        
     # Use the project object obtained from ensure_project_open
-    structure_list = get_object_structure(primary_project, max_depth=15) # Set a reasonable depth
+    print("DEBUG: Starting recursion for project structure with max_depth=15")
+    structure_list = get_object_structure(primary_project, max_depth=15)
     structure_output = "\\n".join(structure_list)
+    
     # Ensure markers are printed distinctly
     print("\\n--- PROJECT STRUCTURE START ---")
     print(structure_output)

package/dist/server.js

@@ -619,6 +619,153 @@ function startMcpServer(config) {
                 };
             }
         }));
+        server.tool("check_status", "Checks the status of the CODESYS environment and any open project", {}, () => __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c, _d;
+            console.error(`Tool call: check_status`);
+            try {
+                const scriptContent = yield (0, scriptLoader_1.loadScriptTemplate)('check_status');
+                const result = yield (0, codesys_interop_1.executeCodesysScript)(scriptContent, codesysExePath, codesysProfileName);
+                if (!result.success) {
+                    return {
+                        content: [{ type: "text", text: `Failed to check CODESYS status: ${result.output}` }],
+                        isError: true
+                    };
+                }
+                const outputLines = result.output.split(/[\r\n]+/).filter(line => line.trim());
+                const statusData = {};
+                outputLines.forEach(line => {
+                    const match = line.match(/^([^:]+):\s*(.*)$/);
+                    if (match) {
+                        statusData[match[1].trim()] = match[2].trim();
+                    }
+                });
+                const statusText = `CODESYS Status:\n - Scripting OK: ${(_a = statusData['Scripting OK']) !== null && _a !== void 0 ? _a : 'Unknown'}\n - Project Open: ${(_b = statusData['Project Open']) !== null && _b !== void 0 ? _b : 'Unknown'}\n - Project Name: ${(_c = statusData['Project Name']) !== null && _c !== void 0 ? _c : 'Unknown'}\n - Project Path: ${(_d = statusData['Project Path']) !== null && _d !== void 0 ? _d : 'N/A'}`;
+                return {
+                    content: [{ type: "text", text: statusText }],
+                    isError: false
+                };
+            }
+            catch (error) {
+                console.error(`Error checking status:`, error);
+                return {
+                    content: [{ type: "text", text: `Failed to check CODESYS status: ${error.message}` }],
+                    isError: true
+                };
+            }
+        }));
+        server.tool("get_pou_code", "Retrieves the code (declaration and implementation) of a POU from a CODESYS project", {
+            projectFilePath: zod_1.z.string().describe("Path to the CODESYS project file."),
+            pouPath: zod_1.z.string().describe("Path to the POU within the project (e.g., 'Application/MyFB').")
+        }, (args) => __awaiter(this, void 0, void 0, function* () {
+            const { projectFilePath, pouPath } = args;
+            let absPath = path.normalize(path.isAbsolute(projectFilePath) ? projectFilePath : path.join(WORKSPACE_DIR, projectFilePath));
+            const sanitizedPouPath = String(pouPath).replace(/\\/g, '/').replace(/^\/+|\/+$/g, '');
+            console.error(`Tool call: get_pou_code: Project='${absPath}', POU='${sanitizedPouPath}'`);
+            try {
+                // Load script template and prepare parameters
+                const scriptTemplate = yield (0, scriptLoader_1.loadScriptTemplate)('get_pou_code');
+                const ensureProjectOpenTemplate = yield (0, scriptLoader_1.loadScriptTemplate)('ensure_project_open');
+                const findObjectByPathTemplate = yield (0, scriptLoader_1.loadScriptTemplate)('find_object_by_path');
+                const combinedScript = ensureProjectOpenTemplate + '\n\n' + findObjectByPathTemplate + '\n\n' + scriptTemplate;
+                const scriptContent = (0, scriptLoader_1.interpolateScript)(combinedScript, {
+                    'PROJECT_FILE_PATH': absPath.replace(/\\/g, '\\\\'),
+                    'POU_FULL_PATH': sanitizedPouPath
+                });
+                const result = yield (0, codesys_interop_1.executeCodesysScript)(scriptContent, codesysExePath, codesysProfileName);
+                if (!result.success) {
+                    return {
+                        content: [{ type: "text", text: `Failed to get POU code: ${result.output}` }],
+                        isError: true
+                    };
+                }
+                const declStartMarker = "### POU DECLARATION START ###";
+                const declEndMarker = "### POU DECLARATION END ###";
+                const implStartMarker = "### POU IMPLEMENTATION START ###";
+                const implEndMarker = "### POU IMPLEMENTATION END ###";
+                const declStartIdx = result.output.indexOf(declStartMarker);
+                const declEndIdx = result.output.indexOf(declEndMarker);
+                const implStartIdx = result.output.indexOf(implStartMarker);
+                const implEndIdx = result.output.indexOf(implEndMarker);
+                let declaration = "/* Declaration not found in output */";
+                let implementation = "/* Implementation not found in output */";
+                let isError = false;
+                if (declStartIdx !== -1 && declEndIdx !== -1 && declStartIdx < declEndIdx) {
+                    declaration = result.output.substring(declStartIdx + declStartMarker.length, declEndIdx).replace(/\\n/g, '\n').trim();
+                }
+                else {
+                    console.error(`WARN: Declaration markers not found correctly for ${sanitizedPouPath}`);
+                    isError = true;
+                }
+                if (implStartIdx !== -1 && implEndIdx !== -1 && implStartIdx < implEndIdx) {
+                    implementation = result.output.substring(implStartIdx + implStartMarker.length, implEndIdx).replace(/\\n/g, '\n').trim();
+                }
+                else {
+                    console.error(`WARN: Implementation markers not found correctly for ${sanitizedPouPath}`);
+                    isError = true;
+                }
+                const codeText = `// ----- Declaration -----\n${declaration}\n\n// ----- Implementation -----\n${implementation}`;
+                return {
+                    content: [{ type: "text", text: codeText }],
+                    isError: isError
+                };
+            }
+            catch (error) {
+                console.error(`Error getting POU code:`, error);
+                return {
+                    content: [{ type: "text", text: `Failed to get POU code for '${pouPath}' in '${projectFilePath}': ${error.message}` }],
+                    isError: true
+                };
+            }
+        }));
+        server.tool("get_project_structure", "Retrieves the structure of a CODESYS project including its POUs, methods, properties, etc.", {
+            projectFilePath: zod_1.z.string().describe("Path to the CODESYS project file to examine.")
+        }, (args) => __awaiter(this, void 0, void 0, function* () {
+            const { projectFilePath } = args;
+            let absPath = path.normalize(path.isAbsolute(projectFilePath) ? projectFilePath : path.join(WORKSPACE_DIR, projectFilePath));
+            console.error(`Tool call: get_project_structure: ${absPath}`);
+            try {
+                // Load the script templates and prepare with parameters
+                const scriptTemplate = yield (0, scriptLoader_1.loadScriptTemplate)('get_project_structure');
+                const ensureProjectOpenTemplate = yield (0, scriptLoader_1.loadScriptTemplate)('ensure_project_open');
+                const combinedScript = ensureProjectOpenTemplate + '\n\n' + scriptTemplate;
+                const scriptContent = (0, scriptLoader_1.interpolateScript)(combinedScript, {
+                    'PROJECT_FILE_PATH': absPath.replace(/\\/g, '\\\\')
+                });
+                const result = yield (0, codesys_interop_1.executeCodesysScript)(scriptContent, codesysExePath, codesysProfileName);
+                if (!result.success) {
+                    return {
+                        content: [{ type: "text", text: `Failed to get project structure: ${result.output}` }],
+                        isError: true
+                    };
+                }
+                // Extract the structure from the output
+                let structureText = '';
+                const startMarker = "--- PROJECT STRUCTURE START ---";
+                const endMarker = "--- PROJECT STRUCTURE END ---";
+                const startIndex = result.output.indexOf(startMarker);
+                const endIndex = result.output.indexOf(endMarker);
+                if (startIndex !== -1 && endIndex !== -1 && startIndex < endIndex) {
+                    structureText = result.output.substring(startIndex + startMarker.length, endIndex).replace(/\\n/g, '\n').trim();
+                    return {
+                        content: [{ type: "text", text: structureText }],
+                        isError: false
+                    };
+                }
+                else {
+                    return {
+                        content: [{ type: "text", text: `Could not parse structure markers in output for ${absPath}.\n\nOutput:\n${result.output}` }],
+                        isError: true
+                    };
+                }
+            }
+            catch (error) {
+                console.error(`Error tool get_project_structure:`, error);
+                return {
+                    content: [{ type: "text", text: `Failed to get project structure for '${projectFilePath}': ${error.message}` }],
+                    isError: true
+                };
+            }
+        }));
         server.tool("compile_project", "Compiles (Builds) the primary application within a CODESYS project.", {
             projectFilePath: zod_1.z.string().describe("Path to the project file containing the application to compile (e.g., 'C:/Projects/MyPLC.project').")
         }, (args) => __awaiter(this, void 0, void 0, function* () {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codesys/mcp-toolkit",
-  "version": "1.1.8",
+  "version": "1.1.10",
   "description": "Model Context Protocol (MCP) server for CODESYS automation platform",
   "main": "dist/server.js",
   "bin": {

package/src/scripts/ensure_project_open.py

@@ -8,10 +8,31 @@ import traceback
 MAX_RETRIES = 3
 RETRY_DELAY = 2.0 # seconds (use float for time.sleep)
 
+# Special handling for Windows paths
+def sanitize_windows_path(path_str):
+    """Properly sanitize Windows paths for CODESYS scripting"""
+    # If it's already a Python raw string literal, return it as is
+    if path_str.startswith('r"') or path_str.startswith("r'"):
+        return path_str
+        
+    # Make Windows paths with backslashes work correctly when passed to CODESYS
+    # We use actual backslashes (which will be doubled by Python raw string)
+    sanitized = path_str.replace('\\', '\\\\')
+    
+    # Clean up any extraneous quotes
+    sanitized = sanitized.strip('"\'')
+    
+    print(f"DEBUG: Sanitized path from '{path_str}' to '{sanitized}'")
+    return sanitized
+
 def ensure_project_open(target_project_path):
     print("DEBUG: Ensuring project is open: %s" % target_project_path)
+    
+    # First sanitize the path for proper Windows path handling
+    sanitized_path = sanitize_windows_path(target_project_path)
+    
     # Normalize target path once
-    normalized_target_path = os.path.normcase(os.path.abspath(target_project_path))
+    normalized_target_path = os.path.normcase(os.path.abspath(sanitized_path))
 
     for attempt in range(MAX_RETRIES):
         print("DEBUG: Ensure project attempt %d/%d for %s" % (attempt + 1, MAX_RETRIES, normalized_target_path))
@@ -100,8 +121,12 @@ def ensure_project_open(target_project_path):
                          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)
+                         try: 
+                             recheck_primary = script_engine.projects.primary
+                             print(f"DEBUG: Recheck primary project type: {type(recheck_primary).__name__}")
+                         except Exception as recheck_primary_err: 
+                             print("WARN: Error getting primary project after reopen: %s" % recheck_primary_err)
+                             traceback.print_exc() # Print full trace for primary project access issue
 
                          if recheck_primary:
                               recheck_path = ""

package/src/scripts/get_project_structure.py

@@ -8,9 +8,14 @@ def ensure_project_open(target_project_path):
 
 def get_object_structure(obj, indent=0, max_depth=10): # Add max_depth
     lines = []; indent_str = "  " * indent
+    if obj is None:
+        lines.append("%s- ERROR: Null object received" % indent_str)
+        return lines
+        
     if indent > max_depth:
         lines.append("%s- Max recursion depth reached." % indent_str)
         return lines
+        
     try:
         name = "Unnamed"; obj_type = type(obj).__name__
         guid_str = ""
@@ -37,10 +42,10 @@ def get_object_structure(obj, indent=0, max_depth=10): # Add max_depth
         if can_have_children:
             try:
                 children = obj.get_children(False)
-                # print("DEBUG: %s has %d children" % (name, len(children))) # Verbose
+                print("DEBUG: '%s' has %d children" % (name, len(children)))
             except Exception as get_child_err:
                 lines.append("%s  ERROR getting children: %s" % (indent_str, get_child_err))
-                # traceback.print_exc() # Optional
+                traceback.print_exc() # Now print detailed error
 
         for child in children:
             lines.extend(get_object_structure(child, indent + 1, max_depth)) # Recurse
@@ -49,15 +54,63 @@ def get_object_structure(obj, indent=0, max_depth=10): # Add max_depth
         lines.append("%s- Error processing node: %s" % (indent_str, e))
         traceback.print_exc() # Print detailed error for this node
     return lines
+
+# Normalize Windows paths for CODESYS scripting
+def normalize_path(path_str):
+    # Replace backslashes with double backslashes for Python string in CODESYS
+    normalized = path_str.replace('\\', '\\\\')
+    # Remove any quotes that might be present
+    normalized = normalized.strip('"\'')
+    print(f"DEBUG: Normalized path from '{path_str}' to '{normalized}'")
+    return normalized
     
 try:
-    print("DEBUG: Getting structure for: %s" % PROJECT_FILE_PATH)
-    primary_project = ensure_project_open(PROJECT_FILE_PATH)
-    project_name = os.path.basename(PROJECT_FILE_PATH)
-    print("DEBUG: Getting structure for project: %s" % project_name)
+    # Normalize the project path for CODESYS
+    normalized_path = normalize_path(PROJECT_FILE_PATH)
+    print("DEBUG: Getting structure for project path: '%s'" % normalized_path)
+    
+    # First confirm that CODESYS is running properly
+    print("DEBUG: CODESYS version info:")
+    try:
+        version_info = script_engine.get_version_info()
+        print(f"DEBUG: CODESYS Version: {version_info}")
+    except Exception as v_err:
+        print(f"DEBUG: Error getting CODESYS version: {v_err}")
+    
+    print("DEBUG: Opening project...")
+    primary_project = ensure_project_open(normalized_path)
+    
+    if primary_project is None:
+        print("DEBUG: ERROR - Project object is None after ensure_project_open")
+        raise ValueError(f"Failed to open project: {normalized_path} - project object is None")
+        
+    print("DEBUG: Project object type: %s" % type(primary_project).__name__)
+    project_name = os.path.basename(normalized_path)
+    
+    if hasattr(primary_project, 'get_name'):
+        print("DEBUG: Project name from object: %s" % primary_project.get_name())
+    else:
+        print("DEBUG: Project object does not have get_name() method")
+        
+    # Check if project has useful methods
+    if hasattr(primary_project, 'get_children'):
+        print("DEBUG: Project has get_children method")
+    else:
+        print("DEBUG: WARNING - Project does not have get_children method")
+        
+    if hasattr(primary_project, 'active_application'):
+        print("DEBUG: Project has active_application property")
+        app = primary_project.active_application
+        if app:
+            print("DEBUG: Active application name: %s" % getattr(app, 'get_name', lambda: "Unknown")())
+    else:
+        print("DEBUG: WARNING - Project does not have active_application property")
+        
     # Use the project object obtained from ensure_project_open
-    structure_list = get_object_structure(primary_project, max_depth=15) # Set a reasonable depth
+    print("DEBUG: Starting recursion for project structure with max_depth=15")
+    structure_list = get_object_structure(primary_project, max_depth=15)
     structure_output = "\\n".join(structure_list)
+    
     # Ensure markers are printed distinctly
     print("\\n--- PROJECT STRUCTURE START ---")
     print(structure_output)