@codesys/mcp-toolkit 1.2.4 → 1.4.0

package/dist/sessionManager.js

@@ -63,11 +63,12 @@ const scriptLoader_1 = require("./scriptLoader");
 const DEFAULT_SCRIPT_TIMEOUT = 60000; // 60 seconds
 const DEFAULT_SESSION_IDLE_TIMEOUT = 300000; // 5 minutes
 const DEFAULT_SESSION_POLL_INTERVAL = 1000; // 1 second
-// Session directory and pipe names
+// Session directory and file names
 const SESSION_DIR = path.join(os.tmpdir(), 'codesys_session');
-const COMMAND_PIPE = 'command_pipe';
-const RESULT_PIPE = 'result_pipe';
+const COMMAND_FILE = 'command.json';
+const RESULT_FILE = 'result.json';
 const STATE_FILE = 'session_state.json';
+const SESSION_LOCK_FILE = 'session.lock';
 // Define expected success/error markers from the Python scripts
 const SCRIPT_SUCCESS_MARKER = 'SCRIPT_SUCCESS';
 const SCRIPT_ERROR_MARKER = 'SCRIPT_ERROR';
@@ -120,11 +121,12 @@ class CodesysSessionManager extends events_1.EventEmitter {
         this.codesysProfileName = codesysProfileName;
         this.idleTimeoutMs = idleTimeoutMs;
         this.sessionId = (0, uuid_1.v4)();
-        // Set up session directory and pipes
+        // Set up session directory and files
         this.sessionDir = path.join(SESSION_DIR, this.sessionId);
-        this.commandPipePath = path.join(this.sessionDir, COMMAND_PIPE);
-        this.resultPipePath = path.join(this.sessionDir, RESULT_PIPE);
+        this.commandFilePath = path.join(this.sessionDir, COMMAND_FILE);
+        this.resultFilePath = path.join(this.sessionDir, RESULT_FILE);
         this.stateFilePath = path.join(this.sessionDir, STATE_FILE);
+        this.lockFilePath = path.join(this.sessionDir, SESSION_LOCK_FILE);
         // Log status changes through event emitter
         this.on(exports.SESSION_EVENTS.STARTED, () => {
             console.error(`SESSION_MANAGER: Session started successfully`);
@@ -247,8 +249,8 @@ class CodesysSessionManager extends events_1.EventEmitter {
                 // Interpolate parameters
                 const scriptContent = (0, scriptLoader_1.interpolateScript)(scriptTemplate, {
                     SESSION_DIR: this.sessionDir,
-                    COMMAND_PIPE: COMMAND_PIPE,
-                    RESULT_PIPE: RESULT_PIPE,
+                    COMMAND_FILE: COMMAND_FILE,
+                    RESULT_FILE: RESULT_FILE,
                     STATE_FILE: STATE_FILE,
                     SESSION_ID: this.sessionId,
                 });
@@ -319,10 +321,10 @@ class CodesysSessionManager extends events_1.EventEmitter {
             const startTime = Date.now();
             while (Date.now() - startTime < timeoutMs) {
                 try {
-                    // Check if pipes exist
-                    const commandPipeExists = fs.existsSync(this.commandPipePath);
-                    const resultPipeExists = fs.existsSync(this.resultPipePath);
-                    if (commandPipeExists && resultPipeExists) {
+                    // Check if files exist
+                    const commandFileExists = fs.existsSync(this.commandFilePath);
+                    const resultFileExists = fs.existsSync(this.resultFilePath);
+                    if (commandFileExists && resultFileExists) {
                         // Read state file to check if session is ready
                         const stateContent = yield (0, promises_1.readFile)(this.stateFilePath, 'utf8');
                         const stateData = JSON.parse(stateContent);
@@ -366,14 +368,14 @@ class CodesysSessionManager extends events_1.EventEmitter {
             }
             try {
                 // Check if we have a running session
-                if (fs.existsSync(this.sessionDir) && fs.existsSync(this.commandPipePath)) {
+                if (fs.existsSync(this.sessionDir) && fs.existsSync(this.commandFilePath)) {
                     // Load the stop_session script template
                     const scriptTemplate = yield (0, scriptLoader_1.loadScriptTemplate)('stop_session');
                     // Interpolate parameters
                     const scriptContent = (0, scriptLoader_1.interpolateScript)(scriptTemplate, {
                         SESSION_DIR: this.sessionDir,
-                        COMMAND_PIPE: COMMAND_PIPE,
-                        RESULT_PIPE: RESULT_PIPE,
+                        COMMAND_FILE: COMMAND_FILE,
+                        RESULT_FILE: RESULT_FILE,
                         STATE_FILE: STATE_FILE,
                         SESSION_ID: this.sessionId,
                     });
@@ -524,15 +526,15 @@ class CodesysSessionManager extends events_1.EventEmitter {
             this.resetIdleTimeout();
             // Mark the session as busy
             this.sessionState = exports.SessionState.BUSY;
-            // Check if the command pipe exists
-            if (!fs.existsSync(this.commandPipePath)) {
+            // Check if the command file exists
+            if (!fs.existsSync(this.commandFilePath)) {
                 this.sessionState = exports.SessionState.ERROR;
-                throw new Error(`Command pipe not found at ${this.commandPipePath}`);
+                throw new Error(`Command file not found at ${this.commandFilePath}`);
             }
-            // Check if the result pipe exists
-            if (!fs.existsSync(this.resultPipePath)) {
+            // Check if the result file exists
+            if (!fs.existsSync(this.resultFilePath)) {
                 this.sessionState = exports.SessionState.ERROR;
-                throw new Error(`Result pipe not found at ${this.resultPipePath}`);
+                throw new Error(`Result file not found at ${this.resultFilePath}`);
             }
             // Return a promise that will be resolved when script execution completes
             return new Promise((resolve, reject) => __awaiter(this, void 0, void 0, function* () {
@@ -571,15 +573,21 @@ class CodesysSessionManager extends events_1.EventEmitter {
                     // Create the command to send
                     const command = {
                         id: scriptId,
+                        type: "execute_script",
                         script: scriptContent,
                         timestamp: Date.now()
                     };
-                    // Send the command
-                    const commandString = JSON.stringify(command) + '\n';
-                    fs.writeFileSync(this.commandPipePath, commandString);
-                    console.error(`SESSION_MANAGER: Command sent to pipe`);
-                    // Start reading the result pipe
-                    this.readResultPipe(scriptId);
+                    // Prepare the command data
+                    const commandData = {
+                        status: "pending",
+                        command: command,
+                        timestamp: Date.now()
+                    };
+                    // Send the command by writing to the command file
+                    fs.writeFileSync(this.commandFilePath, JSON.stringify(commandData));
+                    console.error(`SESSION_MANAGER: Command written to file`);
+                    // Start reading the result file
+                    this.readResultFile(scriptId);
                 }
                 catch (error) {
                     console.error(`SESSION_MANAGER: Error executing script: ${error.message}`);
@@ -599,12 +607,12 @@ class CodesysSessionManager extends events_1.EventEmitter {
         });
     }
     /**
-     * Read the result pipe for a specific script execution
+     * Read the result file for a specific script execution
      * @param scriptId The script ID to read results for
      */
-    readResultPipe(scriptId) {
-        console.error(`SESSION_MANAGER: Starting to read result pipe for script ${scriptId}`);
-        // We'll use a polling approach to read from the pipe
+    readResultFile(scriptId) {
+        console.error(`SESSION_MANAGER: Starting to read result file for script ${scriptId}`);
+        // We'll use a polling approach to read from the file
         const pollInterval = setInterval(() => __awaiter(this, void 0, void 0, function* () {
             try {
                 if (!this.pendingScripts.has(scriptId)) {
@@ -612,21 +620,19 @@ class CodesysSessionManager extends events_1.EventEmitter {
                     clearInterval(pollInterval);
                     return;
                 }
-                // Check if the result pipe exists
-                if (!fs.existsSync(this.resultPipePath)) {
-                    console.error(`SESSION_MANAGER: Result pipe not found at ${this.resultPipePath}`);
+                // Check if the result file exists
+                if (!fs.existsSync(this.resultFilePath)) {
+                    console.error(`SESSION_MANAGER: Result file not found at ${this.resultFilePath}`);
                     return;
                 }
-                // Read the result pipe
-                const resultContent = yield (0, promises_1.readFile)(this.resultPipePath, 'utf8');
-                // Process all lines
-                const lines = resultContent.split('\n');
-                for (const line of lines) {
-                    if (!line.trim())
-                        continue;
-                    try {
-                        const result = JSON.parse(line);
-                        // Check if this result is for our script
+                // Read the result file
+                const resultContent = yield (0, promises_1.readFile)(this.resultFilePath, 'utf8');
+                try {
+                    // Parse the result data
+                    const resultData = JSON.parse(resultContent);
+                    // Check if the result is complete and for our script
+                    if (resultData.status === 'complete' && resultData.result) {
+                        const result = resultData.result;
                         if (result.id === scriptId) {
                             console.error(`SESSION_MANAGER: Found result for script ${scriptId}`);
                             // Remove from pending scripts
@@ -647,14 +653,13 @@ class CodesysSessionManager extends events_1.EventEmitter {
                             return;
                         }
                     }
-                    catch (parseError) {
-                        console.error(`SESSION_MANAGER: Error parsing result line: ${parseError}`);
-                        // Continue with the next line
-                    }
+                }
+                catch (parseError) {
+                    console.error(`SESSION_MANAGER: Error parsing result data: ${parseError}`);
                 }
             }
             catch (error) {
-                console.error(`SESSION_MANAGER: Error reading result pipe: ${error}`);
+                console.error(`SESSION_MANAGER: Error reading result file: ${error}`);
             }
         }), 100); // Poll every 100ms
         // Set a timeout to stop polling after the script timeout

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.2.4",
+  "version": "1.4.0",
   "description": "Model Context Protocol (MCP) server for CODESYS automation platform",
   "main": "dist/server.js",
   "bin": {