@codesys/mcp-toolkit 1.3.0 → 1.4.0

package/.claude/settings.local.json

@@ -18,7 +18,9 @@
       "Bash(npm publish:*)",
       "Bash(npm publish:*)",
       "Bash(ls:*)",
-      "Bash(ls:*)"
+      "Bash(ls:*)",
+      "Bash(mkdir:*)",
+      "Bash(mkdir:*)"
     ],
     "deny": []
   }

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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.4.0] - 2025-05-02
+### Added
+- Implemented persistent session management functionality
+- Added support for keeping CODESYS open between commands
+- Created file-based IPC for script execution in existing CODESYS instance
+- Improved session reliability with health checks and automatic recovery
+- Added session timeout after 10 minutes of inactivity
+- Created detailed documentation for session management features
+
+## [1.3.0] - 2025-05-02
+### Changed
+- Refactored codebase for improved reliability and maintainability
+- Enhanced error handling in Python script templates
+
 ## [1.2.4] - 2025-05-02 
 ### Fixed
 - Fully disabled session management to prevent operations appearing to succeed but not actually running

package/dist/scripts/session_status.py

@@ -1,4 +1,4 @@
-import sys, os, json, time
+import sys, os, json, time, traceback
 import tempfile
 
 # Define markers for script results
@@ -26,18 +26,24 @@ def check_session_status():
             return False
 
         # Read session state
-        with open(SESSION_STATE_FILE, 'r') as f:
-            try:
+        try:
+            with open(SESSION_STATE_FILE, 'r') as f:
                 session_state = json.load(f)
-            except json.JSONDecodeError:
-                print(f"{SCRIPT_ERROR_MARKER}: Invalid session state file")
-                return False
+        except json.JSONDecodeError:
+            print(f"{SCRIPT_ERROR_MARKER}: Invalid session state file")
+            return False
 
         # Check if session is active
         active = session_state.get('active', False)
         status = session_state.get('status', 'unknown')
         
+        # If the status indicates the session is not active, return immediately
+        if not active or status in ['stopped', 'error', 'stopping', 'timeout']:
+            print(f"{SCRIPT_SUCCESS_MARKER}: Session is not active (Status: {status})")
+            return False
+        
         # Check session lock file to see if it's been updated recently
+        lock_is_stale = False
         if os.path.exists(SESSION_LOCK_FILE):
             try:
                 with open(SESSION_LOCK_FILE, 'r') as f:
@@ -47,26 +53,33 @@ def check_session_status():
                     
                     # If lock file hasn't been updated in 30 seconds, session might be dead
                     if time_diff > 30:
-                        print(f"{SCRIPT_SUCCESS_MARKER}: Session appears to be inactive (lock file stale by {time_diff:.1f} seconds)")
-                        # But we'll leave the active flag as is, since it might just be busy
+                        print(f"WARNING: Session lock file is stale by {time_diff:.1f} seconds")
+                        lock_is_stale = True
             except Exception as e:
                 print(f"Error reading lock file: {e}")
+                lock_is_stale = True
+        else:
+            print("WARNING: Session lock file not found")
+            lock_is_stale = True
         
-        # Execute a ping test by sending a simple command
-        if active and status in ["running", "busy"]:
+        # If the lock file is stale but other checks suggest the session is active,
+        # we'll perform a ping test to be sure
+        ping_success = False
+        if status in ["running", "busy"]:
             # Try to ping the session
             try:
                 # Check if command file exists
                 if os.path.exists(COMMAND_FILE):
+                    print("Sending ping command to verify session...")
+                    
                     # Create ping command
                     ping_command = {
                         "id": f"ping_{int(time.time())}",
-                        "type": "execute_script",
-                        "script": "print('SCRIPT_SUCCESS: Ping successful')",
+                        "type": "ping",  # Use specific ping command type
                         "timestamp": time.time()
                     }
                     
-                    # Write command to file
+                    # Write command to file with pretty-printing
                     command_data = {
                         "status": "pending",
                         "command": ping_command,
@@ -74,12 +87,11 @@ def check_session_status():
                     }
                     
                     with open(COMMAND_FILE, 'w') as f:
-                        json.dump(command_data, f)
+                        json.dump(command_data, f, indent=2)
                     
                     # Wait for result (with short timeout)
                     timeout = 5  # seconds
                     start_time = time.time()
-                    ping_success = False
                     
                     while not ping_success and (time.time() - start_time) < timeout:
                         # Check if result file exists
@@ -95,16 +107,37 @@ def check_session_status():
                                     result = result_data.get("result")
                                     if result.get('id') == ping_command['id'] and result.get('success', False):
                                         ping_success = True
+                                        print("Ping successful, session is responsive")
                                         break
                         except Exception as e:
                             print(f"Error reading result: {e}")
                             time.sleep(0.5)
                     
                     if not ping_success:
-                        print(f"{SCRIPT_SUCCESS_MARKER}: Session appears to be unresponsive to ping")
-                        return False
+                        print(f"WARNING: Session did not respond to ping within {timeout} seconds")
+                        
+                        # Reset command file since ping failed
+                        try:
+                            command_data = {
+                                "status": "ready",
+                                "command": None,
+                                "timestamp": time.time()
+                            }
+                            
+                            with open(COMMAND_FILE, 'w') as f:
+                                json.dump(command_data, f, indent=2)
+                                
+                            print("Reset command file after failed ping")
+                        except Exception as e:
+                            print(f"Error resetting command file: {e}")
+                else:
+                    print("WARNING: Command file not found, cannot ping session")
             except Exception as e:
                 print(f"Error during ping test: {e}")
+                traceback.print_exc()
+        
+        # Make final determination based on all checks
+        session_active = active and (not lock_is_stale or ping_success) and status in ["running", "busy"]
         
         # Build status message
         project_info = ""
@@ -113,15 +146,39 @@ def check_session_status():
             project_path = session_state.get('project_path', 'Unknown')
             project_info = f", Project: {project_name} ({project_path})"
         
-        if active and status in ["running", "busy"]:
-            print(f"{SCRIPT_SUCCESS_MARKER}: Session is active (Status: {status}{project_info})")
+        # Include session info
+        session_id = session_state.get('session_id', 'Unknown')
+        start_time = session_state.get('start_time', 0)
+        uptime = time.time() - start_time if start_time else 0
+        uptime_str = f"{uptime:.0f} seconds" if uptime < 60 else f"{uptime/60:.1f} minutes"
+        
+        if session_active:
+            print(f"{SCRIPT_SUCCESS_MARKER}: Session is active (ID: {session_id}, Status: {status}, Uptime: {uptime_str}{project_info})")
             return True
         else:
-            print(f"{SCRIPT_SUCCESS_MARKER}: Session is not active (Status: {status})")
+            # If we get here, session may be in a state where files exist but process is dead
+            if active and status in ["running", "busy"] and lock_is_stale and not ping_success:
+                print(f"{SCRIPT_SUCCESS_MARKER}: Session appears to be zombie (ID: {session_id}, Status: {status} but unresponsive)")
+                # Update session state to error so it will be considered inactive
+                try:
+                    session_state['status'] = 'error'
+                    session_state['active'] = False
+                    session_state['error_reason'] = 'Unresponsive to ping'
+                    
+                    with open(SESSION_STATE_FILE, 'w') as f:
+                        json.dump(session_state, f, indent=2)
+                        
+                    print("Updated session state to error due to unresponsiveness")
+                except Exception as e:
+                    print(f"Error updating session state: {e}")
+            else:
+                print(f"{SCRIPT_SUCCESS_MARKER}: Session is not active (Status: {status})")
+                
             return False
 
     except Exception as e:
         print(f"{SCRIPT_ERROR_MARKER}: Error checking session status - {str(e)}")
+        traceback.print_exc()
         return False
 
 # Main script

package/dist/scripts/start_session.py

@@ -1,4 +1,4 @@
-import sys, os, json, time, tempfile
+import sys, os, json, time, tempfile, traceback
 import scriptengine as script_engine
 
 # Define markers for script results
@@ -11,43 +11,71 @@ SESSION_STATE_FILE = os.path.join(SESSION_DIR, "session_state.json")
 COMMAND_FILE = os.path.join(SESSION_DIR, "command.json")
 RESULT_FILE = os.path.join(SESSION_DIR, "result.json")
 SESSION_LOCK_FILE = os.path.join(SESSION_DIR, "session.lock")
-POLL_INTERVAL = 0.5  # seconds
+POLL_INTERVAL = 0.1  # seconds (faster polling for better responsiveness)
+MAX_INACTIVITY_TIME = 600  # seconds (10 minutes of inactivity before auto-shutdown)
 
 def setup_session_dir():
     """Create the session directory and initial files"""
     try:
+        # Clean up any existing session first
+        if os.path.exists(SESSION_DIR):
+            try:
+                # Try to read existing session state
+                if os.path.exists(SESSION_STATE_FILE):
+                    try:
+                        with open(SESSION_STATE_FILE, 'r') as f:
+                            old_state = json.load(f)
+                            print(f"Cleaning up previous session (ID: {old_state.get('session_id', 'unknown')})")
+                    except:
+                        pass
+                
+                # Remove all files in the directory
+                for filename in os.listdir(SESSION_DIR):
+                    filepath = os.path.join(SESSION_DIR, filename)
+                    try:
+                        if os.path.isfile(filepath):
+                            os.unlink(filepath)
+                    except Exception as e:
+                        print(f"Error removing file {filepath}: {e}")
+            except Exception as e:
+                print(f"Error cleaning up previous session: {e}")
+        
         # Create session directory
         if not os.path.exists(SESSION_DIR):
             os.makedirs(SESSION_DIR)
             
         # Initialize session state
+        session_id = str(time.time()) + "_" + str(os.getpid())
         session_state = {
             "active": True,
-            "session_id": str(time.time()),
+            "session_id": session_id,
             "start_time": time.time(),
+            "last_activity": time.time(),
             "status": "running",
             "project_open": False,
             "project_name": "",
-            "project_path": ""
+            "project_path": "",
+            "version": "1.0"
         }
         
         # Write session state
         with open(SESSION_STATE_FILE, 'w') as f:
-            json.dump(session_state, f)
+            json.dump(session_state, f, indent=2)
         
         # Create empty command file
         with open(COMMAND_FILE, 'w') as f:
-            json.dump({"status": "ready", "command": None, "timestamp": time.time()}, f)
+            json.dump({"status": "ready", "command": None, "timestamp": time.time()}, f, indent=2)
         
         # Create empty result file
         with open(RESULT_FILE, 'w') as f:
-            json.dump({"status": "none", "result": None, "timestamp": time.time()}, f)
+            json.dump({"status": "none", "result": None, "timestamp": time.time()}, f, indent=2)
         
         # Create lock file
         with open(SESSION_LOCK_FILE, 'w') as f:
             f.write(str(time.time()))
         
         print(f"Session directory setup at: {SESSION_DIR}")
+        print(f"Session ID: {session_id}")
         return True
     except Exception as e:
         print(f"Failed to set up session directory: {e}")
@@ -78,8 +106,19 @@ def update_session_state(status="running"):
                 project_name = "Unnamed (Path Error)"
         
         # Read current state file
-        with open(SESSION_STATE_FILE, 'r') as f:
-            session_state = json.load(f)
+        try:
+            with open(SESSION_STATE_FILE, 'r') as f:
+                session_state = json.load(f)
+        except (FileNotFoundError, json.JSONDecodeError):
+            # State file doesn't exist or is invalid, create a new one
+            session_id = str(time.time()) + "_" + str(os.getpid())
+            session_state = {
+                "active": True,
+                "session_id": session_id,
+                "start_time": time.time(),
+                "status": status,
+                "version": "1.0"
+            }
         
         # Update state
         session_state["project_open"] = project_open
@@ -90,11 +129,12 @@ def update_session_state(status="running"):
         
         # Write updated state
         with open(SESSION_STATE_FILE, 'w') as f:
-            json.dump(session_state, f)
+            json.dump(session_state, f, indent=2)
             
         return True
     except Exception as e:
         print(f"Failed to update session state: {e}")
+        traceback.print_exc()
         return False
 
 def execute_command(command_data):
@@ -114,6 +154,10 @@ def execute_command(command_data):
         if cmd_type == "execute_script" and script:
             # Execute the script in the current CODESYS context
             try:
+                # Create a temporary globals dictionary with the current globals
+                # This allows us to isolate the script execution somewhat
+                local_globals = globals().copy()
+                
                 # Capture output by redirecting stdout/stderr
                 import io
                 from contextlib import redirect_stdout, redirect_stderr
@@ -123,7 +167,7 @@ def execute_command(command_data):
                 
                 with redirect_stdout(stdout_buffer), redirect_stderr(stderr_buffer):
                     # Execute the script
-                    exec(script, globals())
+                    exec(script, local_globals)
                 
                 # Get the captured output
                 stdout_output = stdout_buffer.getvalue()
@@ -143,8 +187,9 @@ def execute_command(command_data):
                     result["error"] = stderr_output
             
             except Exception as e:
+                traceback.print_exc()
                 result["success"] = False
-                result["error"] = f"Error executing script: {str(e)}"
+                result["error"] = f"Error executing script: {str(e)}\n{traceback.format_exc()}"
                 result["output"] = f"{SCRIPT_ERROR_MARKER}: {str(e)}"
         
         elif cmd_type == "stop":
@@ -158,6 +203,11 @@ def execute_command(command_data):
             # Return the result and signal to stop the loop
             return result, True
         
+        elif cmd_type == "ping":
+            # Simple ping command to check if session is alive
+            result["success"] = True
+            result["output"] = f"{SCRIPT_SUCCESS_MARKER}: Session is active"
+        
         else:
             result["success"] = False
             result["error"] = f"Unknown command type: {cmd_type}"
@@ -169,19 +219,31 @@ def execute_command(command_data):
         return result, False
         
     except Exception as e:
+        traceback.print_exc()
         return {
             "id": command_data.get("id", "unknown"),
             "success": False,
             "output": f"{SCRIPT_ERROR_MARKER}: Command execution failed",
-            "error": str(e)
+            "error": f"{str(e)}\n{traceback.format_exc()}"
         }, False
 
 def check_command():
     """Check if there is a new command to execute"""
     try:
+        # If command file doesn't exist, return immediately
+        if not os.path.exists(COMMAND_FILE):
+            return False
+            
         # Read the command file
-        with open(COMMAND_FILE, 'r') as f:
-            command_data = json.load(f)
+        try:
+            with open(COMMAND_FILE, 'r') as f:
+                command_data = json.load(f)
+        except json.JSONDecodeError:
+            # If command file is corrupted, reset it
+            command_data = {"status": "ready", "command": None, "timestamp": time.time()}
+            with open(COMMAND_FILE, 'w') as f:
+                json.dump(command_data, f, indent=2)
+            return False
         
         # Check if there's a new command
         if command_data.get("status") == "pending" and command_data.get("command"):
@@ -191,7 +253,10 @@ def check_command():
             # Mark as processing
             command_data["status"] = "processing"
             with open(COMMAND_FILE, 'w') as f:
-                json.dump(command_data, f)
+                json.dump(command_data, f, indent=2)
+            
+            # Update session state to busy
+            update_session_state("busy")
             
             # Execute the command
             result, stop_requested = execute_command(command)
@@ -204,7 +269,7 @@ def check_command():
             }
             
             with open(RESULT_FILE, 'w') as f:
-                json.dump(result_data, f)
+                json.dump(result_data, f, indent=2)
             
             # Reset command file
             command_data = {
@@ -214,18 +279,60 @@ def check_command():
             }
             
             with open(COMMAND_FILE, 'w') as f:
-                json.dump(command_data, f)
+                json.dump(command_data, f, indent=2)
+            
+            # Update session state to running again
+            if not stop_requested:
+                update_session_state("running")
+            
+            # Update last activity time
+            update_last_activity()
             
             return stop_requested
         
         return False
     except Exception as e:
         print(f"Error checking command: {e}")
+        traceback.print_exc()
+        return False
+
+def update_last_activity():
+    """Update the last activity timestamp in the session state"""
+    try:
+        if os.path.exists(SESSION_STATE_FILE):
+            with open(SESSION_STATE_FILE, 'r') as f:
+                state = json.load(f)
+            
+            state["last_activity"] = time.time()
+            
+            with open(SESSION_STATE_FILE, 'w') as f:
+                json.dump(state, f, indent=2)
+    except Exception as e:
+        print(f"Error updating last activity: {e}")
+
+def check_inactivity_timeout():
+    """Check if session has been inactive for too long"""
+    try:
+        if os.path.exists(SESSION_STATE_FILE):
+            with open(SESSION_STATE_FILE, 'r') as f:
+                state = json.load(f)
+            
+            last_activity = state.get("last_activity", state.get("start_time", time.time()))
+            current_time = time.time()
+            
+            if (current_time - last_activity) > MAX_INACTIVITY_TIME:
+                print(f"Session inactive for {current_time - last_activity:.1f} seconds, shutting down")
+                return True
+        
+        return False
+    except Exception as e:
+        print(f"Error checking inactivity timeout: {e}")
         return False
 
 def command_loop():
     """Main loop to check for and execute commands"""
     stop_requested = False
+    last_state_update = time.time()
     
     print(f"Starting command loop...")
     print(f"Command file: {COMMAND_FILE}")
@@ -240,11 +347,24 @@ def command_loop():
             # Check for new commands
             stop_requested = check_command()
             
+            # Check for inactivity timeout
+            if check_inactivity_timeout():
+                print("Session timeout due to inactivity")
+                update_session_state("timeout")
+                stop_requested = True
+                
+            # Periodically update session state (every 30 seconds)
+            current_time = time.time()
+            if (current_time - last_state_update) > 30:
+                update_session_state()
+                last_state_update = current_time
+            
             # Sleep for a bit
             time.sleep(POLL_INTERVAL)
         
         except Exception as e:
             print(f"Error in command loop: {e}")
+            traceback.print_exc()
             # Sleep for a bit
             time.sleep(POLL_INTERVAL)
     
@@ -272,6 +392,7 @@ def main():
     except Exception as e:
         print(f"Error in session: {e}")
         print(f"{SCRIPT_ERROR_MARKER}: Session failed - {str(e)}")
+        traceback.print_exc()
         sys.exit(1)
 
 if __name__ == "__main__":

package/dist/scripts/stop_session.py

@@ -1,4 +1,4 @@
-import sys, os, json, time
+import sys, os, json, time, traceback
 import tempfile
 
 # Define markers for script results
@@ -26,15 +26,15 @@ def stop_session():
             return False
 
         # Read session state
-        with open(SESSION_STATE_FILE, 'r') as f:
-            try:
+        try:
+            with open(SESSION_STATE_FILE, 'r') as f:
                 session_state = json.load(f)
-            except json.JSONDecodeError:
-                print(f"{SCRIPT_ERROR_MARKER}: Invalid session state file")
-                return False
+        except json.JSONDecodeError:
+            print(f"{SCRIPT_ERROR_MARKER}: Invalid session state file")
+            return False
 
         # Check if session is active
-        if not session_state.get('active', False):
+        if not session_state.get('active', False) or session_state.get('status') == 'stopped':
             print(f"{SCRIPT_SUCCESS_MARKER}: Session is already stopped")
             return True
 
@@ -43,6 +43,19 @@ def stop_session():
             print(f"{SCRIPT_ERROR_MARKER}: Command file not found at {COMMAND_FILE}")
             return False
 
+        # Try to read the lock file to check if session is still alive
+        lock_time = 0
+        try:
+            if os.path.exists(SESSION_LOCK_FILE):
+                with open(SESSION_LOCK_FILE, 'r') as f:
+                    lock_time = float(f.read().strip())
+                    
+                current_time = time.time()
+                if (current_time - lock_time) > 30:
+                    print(f"WARNING: Session lock file is stale ({current_time - lock_time:.1f} seconds old). Session may have crashed.")
+        except Exception as e:
+            print(f"Warning: Error reading lock file: {e}")
+
         # Create stop command
         stop_command = {
             "id": f"stop_{int(time.time())}",
@@ -50,7 +63,7 @@ def stop_session():
             "timestamp": time.time()
         }
 
-        # Write command to file
+        # Write command to file with pretty-printing
         command_data = {
             "status": "pending",
             "command": stop_command,
@@ -58,12 +71,12 @@ def stop_session():
         }
 
         with open(COMMAND_FILE, 'w') as f:
-            json.dump(command_data, f)
+            json.dump(command_data, f, indent=2)
 
         print(f"Stop command sent to session")
 
         # Wait for result (with timeout)
-        timeout = 10  # seconds
+        timeout = 15  # seconds (increased timeout for more reliability)
         start_time = time.time()
         result_received = False
 
@@ -87,26 +100,46 @@ def stop_session():
                 print(f"Error reading result: {e}")
                 time.sleep(0.5)
 
-        # Update session state to indicate it's stopped
-        with open(SESSION_STATE_FILE, 'r') as f:
-            session_state = json.load(f)
-            
-        session_state['active'] = False
-        session_state['status'] = "stopped"
-        session_state['end_time'] = time.time()
+        # Update session state to indicate it's stopped regardless of result
+        try:
+            with open(SESSION_STATE_FILE, 'r') as f:
+                session_state = json.load(f)
+                
+            session_state['active'] = False
+            session_state['status'] = "stopped"
+            session_state['end_time'] = time.time()
 
-        with open(SESSION_STATE_FILE, 'w') as f:
-            json.dump(session_state, f)
+            with open(SESSION_STATE_FILE, 'w') as f:
+                json.dump(session_state, f, indent=2)
+        except Exception as e:
+            print(f"Warning: Failed to update session state file: {e}")
 
         if result_received:
             print(f"{SCRIPT_SUCCESS_MARKER}: Session stopped successfully")
+            return True
         else:
-            print(f"{SCRIPT_ERROR_MARKER}: Timeout waiting for session to stop")
-
-        return result_received
+            # If we didn't get a response, the session may be hung
+            # Force a cleanup by removing session files
+            print(f"Warning: Session did not respond to stop command. Forcing cleanup.")
+            try:
+                # Try to remove all session files to ensure a clean state for next session
+                for filename in os.listdir(SESSION_DIR):
+                    filepath = os.path.join(SESSION_DIR, filename)
+                    try:
+                        if os.path.isfile(filepath):
+                            os.unlink(filepath)
+                    except Exception as e:
+                        print(f"Error removing file {filepath}: {e}")
+                
+                print(f"{SCRIPT_SUCCESS_MARKER}: Session files cleaned up forcefully")
+                return True
+            except Exception as e:
+                print(f"{SCRIPT_ERROR_MARKER}: Failed to force cleanup - {str(e)}")
+                return False
 
     except Exception as e:
         print(f"{SCRIPT_ERROR_MARKER}: Error stopping session - {str(e)}")
+        traceback.print_exc()
         return False
 
 # Main script

package/docs/session_management.md

@@ -1,89 +1,110 @@
-# CODESYS MCP Session Management (Not Yet Implemented)
-
-> **IMPORTANT:** Session management is currently disabled in version 1.2.4. 
-> The `start_session` and `stop_session` commands exist but are non-functional.
-> All operations will run in standard mode (starting and stopping CODESYS for each operation).
-> This feature will be fully implemented in a future release.
+# Session Management in CODESYS MCP Toolkit
 
 ## Overview
 
-The CODESYS MCP Toolkit now supports persistent sessions, which significantly improves performance when executing multiple operations in sequence. This document explains how to use the session management functionality.
-
-## Why Session Management?
+Starting from version 1.4.0, the CODESYS MCP Toolkit supports persistent sessions. This feature significantly improves performance by allowing a single instance of CODESYS to stay open while multiple commands are executed, then closing it when explicitly requested or after a period of inactivity.
 
-Previously, each MCP command would start a new CODESYS process, execute the operation, and then shut down the process. This approach is inefficient when performing multiple operations, such as:
+## Benefits
 
-- Creating multiple POUs
-- Editing multiple code sections
-- Complex project setup with many steps
+- **Faster execution**: Eliminates the overhead of starting and stopping CODESYS for each command
+- **Shared context**: Commands executed in the same session share the same CODESYS runtime context
+- **Resource efficiency**: Reduces CPU and memory usage by avoiding repeated process creation
+- **Automatic timeout**: Sessions automatically shut down after a period of inactivity (10 minutes by default)
 
-With session management, you can:
-1. Start a CODESYS session once
-2. Execute multiple operations without restarting CODESYS
-3. Close the session when you're finished
+## Session Management Commands
 
-This can reduce execution time from minutes to seconds for complex tasks.
+The toolkit provides three specific commands for managing sessions:
 
-## Using Session Management with Claude
+### 1. `start_session`
 
-You can now use the `start_session` and `stop_session` commands in your Claude interactions with CODESYS:
-
-### Starting a Session
+Starts a new persistent CODESYS session. If a session is already running, this command reports that fact without starting another.
 
+**Example**:
 ```
-Using the CODESYS Local server, run the start_session command to open a persistent CODESYS session.
+/mcp codesys_local start_session
 ```
 
-### Using the Session
+### 2. `session_status`
 
-Once the session is started, all subsequent operations will use the persistent session automatically:
+Checks if a session is currently active and returns information about it, including:
+- Current state (running, busy, stopped, etc.)
+- How long the session has been running
+- Which project is open in the session (if any)
 
+**Example**:
 ```
-Using the CODESYS Local server, create a new project at C:/MyProjects/Test.project
+/mcp codesys_local session_status
 ```
 
-```
-Using the CODESYS Local server, add a POU named MainProgram of type Program with ST language
-```
+### 3. `stop_session`
 
-### Checking Session Status
+Stops an active session and cleans up session resources. If no session is running, this command reports that fact without taking any action.
 
+**Example**:
 ```
-Using the CODESYS Local server, run the session_status command to check the current state of the CODESYS session.
+/mcp codesys_local stop_session
 ```
 
-### Stopping the Session
+## How to Use Session Management
 
-When you're done with all operations, you should close the session to free up resources:
+### Recommended Workflow
 
-```
-Using the CODESYS Local server, run the stop_session command to close the CODESYS session.
-```
+1. Start a session at the beginning of your work:
+   ```
+   /mcp codesys_local start_session
+   ```
+
+2. Execute all your commands normally - they will automatically use the active session:
+   ```
+   /mcp codesys_local open_project --filePath "C:/path/to/project.project"
+   /mcp codesys_local create_pou --projectFilePath "C:/path/to/project.project" --name "MyPOU" --type "FunctionBlock" --language "ST" --parentPath "Application"
+   ```
 
-## Recommended Workflow
+3. When you're done working, stop the session:
+   ```
+   /mcp codesys_local stop_session
+   ```
 
-For the best performance, we recommend the following workflow when working with CODESYS projects:
+If you forget to stop the session, it will automatically time out after 10 minutes of inactivity.
 
-1. Start the session: `Using the CODESYS Local server, run the start_session command to open a persistent CODESYS session.`
-2. Execute all required operations (create project, create POUs, edit code, etc.)
-3. Stop the session: `Using the CODESYS Local server, run the stop_session command to close the CODESYS session.`
+### Session Behavior
 
-## Technical Notes
+- All commands automatically use an active session if one exists
+- If no session exists when a command is run, it will execute without a session (traditional mode)
+- You can explicitly start a session before running commands to improve performance
+- Sessions maintain state between commands, including open projects
 
-- Sessions will automatically close after 5 minutes of inactivity to prevent resource leaks
-- The session status can be in one of the following states: `IDLE`, `STARTING`, `RUNNING`, `BUSY`, `STOPPING`, `STOPPED`, or `ERROR`
-- If a session operation fails, the system will automatically fall back to the standard one-time execution mode
+## Troubleshooting
 
-## Limitations
+### Common Issues
 
-- The session management is still experimental and may not work with all CODESYS operations
-- Only one session can be active at a time per MCP server instance
-- Some operations that modify the CODESYS environment itself may require restarting the session
+#### Session Won't Start
 
-## Troubleshooting
+If you can't start a session, check:
+- Make sure CODESYS is properly installed and accessible at the path specified in your configuration
+- Verify that the CODESYS profile exists and is valid
+- Check if there are any error messages in the client's output
+
+#### Session Appears Unresponsive
+
+If a session seems stuck:
+1. Check its status: `/mcp codesys_local session_status`
+2. If it reports as active but not responding, try stopping it: `/mcp codesys_local stop_session`
+3. If it still doesn't respond, the toolkit includes a forced cleanup mechanism that will activate automatically when you try to stop a non-responsive session
+
+#### Session Files Remain After Stopping
+
+Session state is stored in a temporary directory (`[temp]/codesys_session/`). These files should be cleaned up automatically when a session stops, but in rare cases (like if the process is killed abruptly), they might remain. The toolkit will clean up old files when starting a new session.
+
+## Technical Details
+
+The session management system works by:
 
-If you encounter issues with session management:
+1. Starting a CODESYS instance with a special Python script that enters a command loop
+2. Maintaining session state in files within a temporary directory
+3. Communicating with the running session via file-based IPC (Inter-Process Communication)
+4. Executing scripts within the context of the running CODESYS instance
+5. Automatically detecting and handling session health issues
 
-1. Check the session status: `Using the CODESYS Local server, run the session_status command`
-2. If the status is `ERROR`, try stopping the session and starting a new one
-3. If problems persist, fall back to using standard operations without explicit session management
+Session files are stored in the system's temporary directory in a subfolder called `codesys_session`.
+EOF < /dev/null

package/package.json

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