@codesys/mcp-toolkit 1.1.4 → 1.2.0

package/dist/sessionManager.js

@@ -0,0 +1,401 @@
+"use strict";
+/**
+ * sessionManager.ts
+ * Manages a persistent CODESYS session for improved performance
+ *
+ * This module implements a session management system that allows
+ * keeping a CODESYS instance running for multiple operations, rather
+ * than starting and stopping CODESYS for each command.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CodesysSessionManager = exports.SessionState = exports.SESSION_EVENTS = void 0;
+const child_process_1 = require("child_process");
+const promises_1 = require("fs/promises");
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const fs = __importStar(require("fs"));
+const events_1 = require("events");
+const uuid_1 = require("uuid");
+// Default timeout values
+const DEFAULT_SCRIPT_TIMEOUT = 60000; // 60 seconds
+const DEFAULT_SESSION_IDLE_TIMEOUT = 300000; // 5 minutes
+// Event names
+exports.SESSION_EVENTS = {
+    STARTED: 'session:started',
+    FAILED: 'session:failed',
+    STOPPED: 'session:stopped',
+    TIMEOUT: 'session:timeout',
+    SCRIPT_COMPLETE: 'script:complete',
+    SCRIPT_ERROR: 'script:error'
+};
+/**
+ * Session state constants
+ */
+exports.SessionState = {
+    IDLE: 'idle',
+    STARTING: 'starting',
+    RUNNING: 'running',
+    BUSY: 'busy',
+    STOPPING: 'stopping',
+    STOPPED: 'stopped',
+    ERROR: 'error'
+};
+/**
+ * Class to manage a persistent CODESYS session
+ */
+class CodesysSessionManager extends events_1.EventEmitter {
+    /**
+     * Creates a new CODESYS session manager
+     *
+     * @param codesysExePath Path to CODESYS.exe
+     * @param codesysProfileName CODESYS profile name
+     * @param idleTimeoutMs Optional idle timeout in milliseconds
+     */
+    constructor(codesysExePath, codesysProfileName, idleTimeoutMs = DEFAULT_SESSION_IDLE_TIMEOUT) {
+        super();
+        this.codesysProcess = null;
+        this.sessionState = exports.SessionState.STOPPED;
+        this.idleTimeout = null;
+        this.pendingScripts = new Map();
+        if (!codesysExePath)
+            throw new Error('CODESYS executable path was not provided.');
+        if (!codesysProfileName)
+            throw new Error('CODESYS profile name was not provided.');
+        if (!fs.existsSync(codesysExePath)) {
+            throw new Error(`CODESYS executable not found at provided path: ${codesysExePath}`);
+        }
+        this.codesysExePath = codesysExePath;
+        this.codesysProfileName = codesysProfileName;
+        this.idleTimeoutMs = idleTimeoutMs;
+        // Log status changes through event emitter
+        this.on(exports.SESSION_EVENTS.STARTED, () => {
+            console.error(`SESSION_MANAGER: Session started successfully`);
+            this.sessionState = exports.SessionState.RUNNING;
+            this.resetIdleTimeout();
+        });
+        this.on(exports.SESSION_EVENTS.FAILED, (error) => {
+            console.error(`SESSION_MANAGER: Session failed to start: ${error.message}`);
+            this.sessionState = exports.SessionState.ERROR;
+        });
+        this.on(exports.SESSION_EVENTS.STOPPED, () => {
+            console.error(`SESSION_MANAGER: Session stopped`);
+            this.sessionState = exports.SessionState.STOPPED;
+        });
+        this.on(exports.SESSION_EVENTS.TIMEOUT, () => {
+            console.error(`SESSION_MANAGER: Session timed out due to inactivity`);
+            this.stopSession();
+        });
+    }
+    /**
+     * Get current session state
+     */
+    getState() {
+        return this.sessionState;
+    }
+    /**
+     * Start a CODESYS session
+     * @returns Promise that resolves when the session is started
+     */
+    startSession() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.sessionState !== exports.SessionState.STOPPED && this.sessionState !== exports.SessionState.ERROR) {
+                console.error(`SESSION_MANAGER: Cannot start session - already in state: ${this.sessionState}`);
+                return Promise.resolve(); // Session already running
+            }
+            this.sessionState = exports.SessionState.STARTING;
+            return new Promise((resolve, reject) => {
+                try {
+                    console.error(`SESSION_MANAGER: Starting CODESYS session with profile: ${this.codesysProfileName}`);
+                    // Create a keep-alive script that keeps CODESYS running
+                    const keepAliveScript = this.createKeepAliveScript();
+                    // Prepare CODESYS process
+                    const codesysDir = path.dirname(this.codesysExePath);
+                    const quotedExePath = `"${this.codesysExePath}"`;
+                    const profileArg = `--profile="${this.codesysProfileName}"`;
+                    // Start CODESYS with the keep-alive script - in "visible" mode so we can see it's running
+                    const fullCommandString = `${quotedExePath} ${profileArg} --runscript="${keepAliveScript}"`;
+                    // Create a modified environment with CODESYS bin dir in PATH
+                    const spawnEnv = Object.assign({}, process.env);
+                    const pathSeparator = os.platform() === 'win32' ? ';' : ':';
+                    const originalPath = spawnEnv.PATH || '';
+                    spawnEnv.PATH = `${codesysDir}${pathSeparator}${originalPath}`;
+                    // Spawn the process
+                    this.codesysProcess = (0, child_process_1.spawn)(fullCommandString, [], {
+                        windowsHide: false, // Make visible to user
+                        cwd: codesysDir,
+                        env: spawnEnv,
+                        shell: true
+                    });
+                    // Handle process events
+                    this.codesysProcess.on('error', (error) => {
+                        console.error(`SESSION_MANAGER: Error starting CODESYS: ${error.message}`);
+                        this.emit(exports.SESSION_EVENTS.FAILED, error);
+                        reject(error);
+                    });
+                    // Give it a small delay to start properly
+                    setTimeout(() => {
+                        if (this.codesysProcess && !this.codesysProcess.killed) {
+                            this.emit(exports.SESSION_EVENTS.STARTED);
+                            this.resetIdleTimeout();
+                            resolve();
+                        }
+                        else {
+                            const error = new Error('CODESYS process failed to start');
+                            this.emit(exports.SESSION_EVENTS.FAILED, error);
+                            reject(error);
+                        }
+                    }, 2000); // 2 second delay to let CODESYS initialize
+                }
+                catch (error) {
+                    console.error(`SESSION_MANAGER: Error during session start: ${error.message}`);
+                    this.emit(exports.SESSION_EVENTS.FAILED, error);
+                    reject(error);
+                }
+            });
+        });
+    }
+    /**
+     * Stop the CODESYS session
+     */
+    stopSession() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.sessionState === exports.SessionState.STOPPED) {
+                console.error('SESSION_MANAGER: Session already stopped');
+                return Promise.resolve();
+            }
+            this.sessionState = exports.SessionState.STOPPING;
+            // Clear idle timeout if it exists
+            if (this.idleTimeout) {
+                clearTimeout(this.idleTimeout);
+                this.idleTimeout = null;
+            }
+            // Reject any pending scripts
+            for (const [id, pending] of this.pendingScripts.entries()) {
+                clearTimeout(pending.timeout);
+                pending.reject(new Error('Session was stopped while script was pending'));
+                this.pendingScripts.delete(id);
+            }
+            return new Promise((resolve) => {
+                if (this.codesysProcess && !this.codesysProcess.killed) {
+                    console.error('SESSION_MANAGER: Stopping CODESYS process');
+                    // First try SIGTERM
+                    this.codesysProcess.kill('SIGTERM');
+                    // Set a timeout to force kill if needed
+                    setTimeout(() => {
+                        if (this.codesysProcess && !this.codesysProcess.killed) {
+                            console.error('SESSION_MANAGER: SIGTERM failed, using SIGKILL');
+                            this.codesysProcess.kill('SIGKILL');
+                        }
+                        this.codesysProcess = null;
+                        this.emit(exports.SESSION_EVENTS.STOPPED);
+                        resolve();
+                    }, 2000); // Give it 2 seconds to terminate gracefully
+                }
+                else {
+                    this.codesysProcess = null;
+                    this.emit(exports.SESSION_EVENTS.STOPPED);
+                    resolve();
+                }
+            });
+        });
+    }
+    /**
+     * Execute a script in the persistent CODESYS session
+     *
+     * @param scriptContent The Python script to execute
+     * @param timeoutMs Optional timeout for the script execution
+     * @returns Promise with script execution result
+     */
+    executeScript(scriptContent_1) {
+        return __awaiter(this, arguments, void 0, function* (scriptContent, timeoutMs = DEFAULT_SCRIPT_TIMEOUT) {
+            // Generate a unique ID for this script execution
+            const scriptId = (0, uuid_1.v4)();
+            // Make sure we have an active session
+            const isActiveSession = this.sessionState === exports.SessionState.RUNNING ||
+                this.sessionState === exports.SessionState.BUSY;
+            if (!isActiveSession) {
+                if (this.sessionState === exports.SessionState.STARTING) {
+                    // Wait for session to start
+                    console.error('SESSION_MANAGER: Waiting for session to complete starting');
+                    yield new Promise((resolve) => {
+                        const checkInterval = setInterval(() => {
+                            if (this.sessionState === exports.SessionState.RUNNING ||
+                                this.sessionState === exports.SessionState.ERROR ||
+                                this.sessionState === exports.SessionState.STOPPED) {
+                                clearInterval(checkInterval);
+                                resolve();
+                            }
+                        }, 200);
+                    });
+                    const isNowActive = this.sessionState === exports.SessionState.RUNNING ||
+                        this.sessionState === exports.SessionState.BUSY;
+                    if (!isNowActive) {
+                        throw new Error(`Session is in ${this.sessionState} state, not running. Cannot execute script.`);
+                    }
+                }
+                else {
+                    throw new Error(`Session is in ${this.sessionState} state, not running. Cannot execute script.`);
+                }
+            }
+            // Reset idle timeout since we're about to do work
+            this.resetIdleTimeout();
+            // Mark the session as busy
+            this.sessionState = exports.SessionState.BUSY;
+            // Return a promise that will be resolved when script execution completes
+            return new Promise((resolve, reject) => __awaiter(this, void 0, void 0, function* () {
+                try {
+                    // Create a temp file for the script
+                    const tempDir = os.tmpdir();
+                    const tempFileName = `codesys_script_${Date.now()}_${Math.random().toString(36).substring(2, 9)}.py`;
+                    const tempFilePath = path.join(tempDir, tempFileName);
+                    // Write the script to the temp file
+                    yield (0, promises_1.writeFile)(tempFilePath, scriptContent, 'latin1');
+                    console.error(`SESSION_MANAGER: Script ${scriptId} created at ${tempFilePath}`);
+                    // Set up a timeout for this script execution
+                    const scriptTimeout = setTimeout(() => {
+                        if (this.pendingScripts.has(scriptId)) {
+                            const pending = this.pendingScripts.get(scriptId);
+                            this.pendingScripts.delete(scriptId);
+                            pending.reject(new Error(`Script execution timed out after ${timeoutMs}ms`));
+                        }
+                    }, timeoutMs);
+                    // Add to pending scripts
+                    this.pendingScripts.set(scriptId, {
+                        resolve: (result) => {
+                            // Clean up the temp file
+                            (0, promises_1.unlink)(tempFilePath).catch(err => {
+                                console.error(`SESSION_MANAGER: Error deleting temp file ${tempFilePath}: ${err.message}`);
+                            });
+                            resolve(result);
+                            // Check if we have more pending scripts
+                            if (this.pendingScripts.size === 0) {
+                                this.sessionState = exports.SessionState.RUNNING;
+                            }
+                        },
+                        reject: (error) => {
+                            // Clean up the temp file
+                            (0, promises_1.unlink)(tempFilePath).catch(err => {
+                                console.error(`SESSION_MANAGER: Error deleting temp file ${tempFilePath}: ${err.message}`);
+                            });
+                            reject(error);
+                            // Check if we have more pending scripts
+                            if (this.pendingScripts.size === 0) {
+                                this.sessionState = exports.SessionState.RUNNING;
+                            }
+                        },
+                        timeout: scriptTimeout
+                    });
+                    // TODO: Implement the actual execution of the script in the running CODESYS instance
+                    // For now, we'll just simulate it with a timeout
+                    setTimeout(() => {
+                        if (this.pendingScripts.has(scriptId)) {
+                            const pending = this.pendingScripts.get(scriptId);
+                            clearTimeout(pending.timeout);
+                            this.pendingScripts.delete(scriptId);
+                            // Return a mocked result
+                            const result = {
+                                id: scriptId,
+                                success: true,
+                                output: "SCRIPT_SUCCESS: This is a mock implementation of script execution!"
+                            };
+                            pending.resolve(result);
+                        }
+                    }, 1000); // 1 second delay for mock result
+                }
+                catch (error) {
+                    reject(error);
+                    // Check if we have more pending scripts
+                    if (this.pendingScripts.size === 0) {
+                        this.sessionState = exports.SessionState.RUNNING;
+                    }
+                }
+            }));
+        });
+    }
+    /**
+     * Reset the idle timeout
+     */
+    resetIdleTimeout() {
+        // Clear existing timeout if any
+        if (this.idleTimeout) {
+            clearTimeout(this.idleTimeout);
+            this.idleTimeout = null;
+        }
+        // Set new timeout
+        if (this.idleTimeoutMs > 0) {
+            this.idleTimeout = setTimeout(() => {
+                console.error(`SESSION_MANAGER: Idle timeout (${this.idleTimeoutMs}ms) reached`);
+                this.emit(exports.SESSION_EVENTS.TIMEOUT);
+            }, this.idleTimeoutMs);
+        }
+    }
+    /**
+     * Create a keep-alive script that keeps CODESYS running
+     * This is a placeholder for now - we'll need to implement
+     * a proper mechanism to keep CODESYS running while allowing
+     * additional scripts to be executed
+     */
+    createKeepAliveScript() {
+        // This is a placeholder - we need a real implementation
+        // that keeps CODESYS running and allows for executing other scripts
+        const tempScript = `
+    import time
+    
+    # This is a placeholder keep-alive script
+    # In a real implementation, we would:
+    # 1. Set up a communication channel (named pipe, socket, etc.)
+    # 2. Listen for script execution requests
+    # 3. Execute them and return results
+    
+    print("Keep-alive script running...")
+    
+    # Just keep running for now
+    while True:
+      time.sleep(1)
+    `;
+        return tempScript;
+    }
+}
+exports.CodesysSessionManager = CodesysSessionManager;

package/docs/index.md

@@ -1,26 +1,26 @@
-# CODESYS MCP Toolkit Documentation
-
-Welcome to the documentation for the CODESYS MCP Toolkit!
-
-## Overview
-
-The CODESYS MCP Toolkit provides a bridge between Model Context Protocol (MCP) clients and CODESYS V3 programming environments. This toolkit enables seamless interaction for automating project management, POU creation, code editing, and compilation tasks.
-
-## Components
-
-- **MCP Server**: Core component that handles MCP protocol communication
-- **CODESYS Script Integration**: Interface with CODESYS scripting engine
-- **Command-Line Interface**: For direct usage and configuration
-
-## Getting Started
-
-- [Installation](installation.md)
-- [Configuration](configuration.md)
-- [Usage Examples](examples.md)
-- [API Reference](api.md)
-
-## Advanced Topics
-
-- [Contributing Guidelines](../CONTRIBUTING.md)
-- [Troubleshooting](troubleshooting.md)
-- [Custom Extensions](extensions.md)
+# CODESYS MCP Toolkit Documentation
+
+Welcome to the documentation for the CODESYS MCP Toolkit!
+
+## Overview
+
+The CODESYS MCP Toolkit provides a bridge between Model Context Protocol (MCP) clients and CODESYS V3 programming environments. This toolkit enables seamless interaction for automating project management, POU creation, code editing, and compilation tasks.
+
+## Components
+
+- **MCP Server**: Core component that handles MCP protocol communication
+- **CODESYS Script Integration**: Interface with CODESYS scripting engine
+- **Command-Line Interface**: For direct usage and configuration
+
+## Getting Started
+
+- [Installation](installation.md)
+- [Configuration](configuration.md)
+- [Usage Examples](examples.md)
+- [API Reference](api.md)
+
+## Advanced Topics
+
+- [Contributing Guidelines](../CONTRIBUTING.md)
+- [Troubleshooting](troubleshooting.md)
+- [Custom Extensions](extensions.md)

package/docs/installation.md

@@ -1,84 +1,84 @@
-# Installation Guide
-
-This guide covers how to install the CODESYS MCP Toolkit on your system.
-
-## Prerequisites
-
-Before installing, ensure you have:
-
-1. **Node.js**: Version 18 or later
-   - Download from [nodejs.org](https://nodejs.org/)
-   - Verify installation with `node --version`
-
-2. **CODESYS V3**: A working CODESYS V3 installation 
-   - Tested with version 3.5 SP21
-   - Must have the **Scripting Engine** component enabled
-   - Verify by opening CODESYS and checking if scripting commands are available
-
-3. **MCP Client**: An MCP-enabled application (e.g., Claude Desktop)
-
-## Installation Methods
-
-### Method 1: Install from npm (Recommended)
-
-The simplest way to install is directly from npm:
-
-```bash
-npm install -g @codesys/mcp-toolkit
-```
-
-This installs the package globally on your system, making the `codesys-mcp-toolkit` command available in your terminal.
-
-Verify the installation by running:
-
-```bash
-codesys-mcp-toolkit --version
-```
-
-### Method 2: Install from Source
-
-For development or to get the latest unreleased changes:
-
-```bash
-# Clone the repository
-git clone https://github.com/yourusername/codesys-mcp-toolkit.git
-cd codesys-mcp-toolkit
-
-# Install dependencies
-npm install
-
-# Build the project
-npm run build
-
-# Install globally
-npm install -g .
-```
-
-Verify the installation using the same command as above.
-
-## Next Steps
-
-After installation:
-
-1. [Configure your MCP client](configuration.md) to use the CODESYS MCP Toolkit
-2. Try some [basic examples](examples.md)
-3. Learn about the [available tools and resources](api.md)
-
-## Troubleshooting Installation Issues
-
-### Common Issues
-
-- **Permission errors**: You may need to run npm with administrative privileges
-  ```bash
-  sudo npm install -g @codesys/mcp-toolkit  # On Linux/macOS
-  # or use PowerShell as Administrator on Windows
-  ```
-
-- **Path issues**: Ensure the npm global bin directory is in your PATH
-
-- **Node.js version**: Verify you have Node.js 18 or later
-  ```bash
-  node --version
-  ```
-
-If you encounter other issues, please check the [troubleshooting guide](troubleshooting.md) or [open an issue](https://github.com/yourusername/codesys-mcp-toolkit/issues) on GitHub.
+# Installation Guide
+
+This guide covers how to install the CODESYS MCP Toolkit on your system.
+
+## Prerequisites
+
+Before installing, ensure you have:
+
+1. **Node.js**: Version 18 or later
+   - Download from [nodejs.org](https://nodejs.org/)
+   - Verify installation with `node --version`
+
+2. **CODESYS V3**: A working CODESYS V3 installation 
+   - Tested with version 3.5 SP21
+   - Must have the **Scripting Engine** component enabled
+   - Verify by opening CODESYS and checking if scripting commands are available
+
+3. **MCP Client**: An MCP-enabled application (e.g., Claude Desktop)
+
+## Installation Methods
+
+### Method 1: Install from npm (Recommended)
+
+The simplest way to install is directly from npm:
+
+```bash
+npm install -g @codesys/mcp-toolkit
+```
+
+This installs the package globally on your system, making the `codesys-mcp-toolkit` command available in your terminal.
+
+Verify the installation by running:
+
+```bash
+codesys-mcp-toolkit --version
+```
+
+### Method 2: Install from Source
+
+For development or to get the latest unreleased changes:
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/codesys-mcp-toolkit.git
+cd codesys-mcp-toolkit
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Install globally
+npm install -g .
+```
+
+Verify the installation using the same command as above.
+
+## Next Steps
+
+After installation:
+
+1. [Configure your MCP client](configuration.md) to use the CODESYS MCP Toolkit
+2. Try some [basic examples](examples.md)
+3. Learn about the [available tools and resources](api.md)
+
+## Troubleshooting Installation Issues
+
+### Common Issues
+
+- **Permission errors**: You may need to run npm with administrative privileges
+  ```bash
+  sudo npm install -g @codesys/mcp-toolkit  # On Linux/macOS
+  # or use PowerShell as Administrator on Windows
+  ```
+
+- **Path issues**: Ensure the npm global bin directory is in your PATH
+
+- **Node.js version**: Verify you have Node.js 18 or later
+  ```bash
+  node --version
+  ```
+
+If you encounter other issues, please check the [troubleshooting guide](troubleshooting.md) or [open an issue](https://github.com/yourusername/codesys-mcp-toolkit/issues) on GitHub.