@codesys/mcp-toolkit 1.0.0 → 1.0.3

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+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.0.3] - 2025-04-23
+
+### Fixed
+- Fixed path handling for CODESYS executable paths with spaces
+- Updated spawn method to use shell:true with quoted paths
+- Improved documentation and sample configuration
+
+## [1.0.2] - 2025-04-22
+
+### Added
+- Improved error handling for script execution
+- Better feedback in console logs
+
+## [1.0.1] - 2025-04-21
+
+### Fixed
+- Resolved issues with project path resolution
+- Fixed property accessor path handling
+
+## [1.0.0] - 2025-04-20
+
+### Added
+- Initial release of the MCP server for CODESYS
+- Command-line interface with configuration options
+- Project management functionality:
+  - Opening existing CODESYS projects
+  - Creating new CODESYS projects
+  - Saving projects
+- POU (Program Organization Unit) management:
+  - Creating POUs (Programs, Function Blocks, Functions)
+  - Setting POU code (declaration and implementation)
+  - Creating properties and methods for Function Blocks
+- Project compilation support
+- Resources for querying:
+  - Project status
+  - Project structure
+  - POU code
+- Documentation for installation and usage

package/CONTRIBUTING.md

@@ -0,0 +1,72 @@
+# Contributing to @codesys/mcp-toolkit
+
+Thank you for considering contributing to the CODESYS MCP Toolkit! This document provides guidelines and steps for contributing.
+
+## Code of Conduct
+
+Please be respectful and considerate of others when contributing to this project. We aim to foster an inclusive and welcoming community.
+
+## How Can I Contribute?
+
+### Reporting Bugs
+
+Bug reports help improve the project! When reporting bugs:
+
+1. Check if the bug has already been reported
+2. Use the bug report template
+3. Include detailed steps to reproduce the issue
+4. Describe the expected vs. actual behavior
+5. Include screenshots if applicable
+6. Provide environment details (OS, Node.js version, etc.)
+
+### Suggesting Features
+
+We welcome feature suggestions! When suggesting features:
+
+1. Describe the problem your feature would solve
+2. Explain how your feature would work
+3. Consider potential alternatives
+4. Provide examples of similar features in other projects (if applicable)
+
+### Pull Requests
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Run tests and ensure they pass
+5. Commit your changes (`git commit -m 'Add amazing feature'`)
+6. Push to your branch (`git push origin feature/amazing-feature`)
+7. Open a Pull Request
+
+## Development Setup
+
+1. Clone the repository
+   ```bash
+   git clone https://github.com/yourusername/codesys-mcp-toolkit.git
+   cd codesys-mcp-toolkit
+   ```
+
+2. Install dependencies
+   ```bash
+   npm install
+   ```
+
+3. Build the project
+   ```bash
+   npm run build
+   ```
+
+## Style Guidelines
+
+- Follow existing code formatting patterns
+- Use meaningful variable and function names
+- Add comments where necessary to explain complex logic
+- Update documentation when changing functionality
+
+## Testing
+
+- Add tests for new features
+- Ensure all tests pass before submitting a PR
+- Consider edge cases in your tests
+
+Thank you for contributing!

package/README.md

@@ -1,123 +1,79 @@
-# @codesys/mcp-toolkit
+# CODESYS MCP Toolkit
 
-This project provides a Model Context Protocol (MCP) server that allows interaction with a local CODESYS V3 development environment (tested with 3.5 SP21) via its scripting interface. It enables MCP clients like Claude Desktop to perform actions such as opening/creating/saving projects, creating POUs, adding code, and compiling projects.
+A Model Context Protocol (MCP) toolkit for interfacing between Claude and CODESYS programming environments.
 
-## Features
+## Overview
 
-Currently implemented features:
+This toolkit provides a bridge between Claude Desktop and CODESYS V3, allowing Claude to interact with CODESYS projects through a standardized Model Context Protocol (MCP).
 
-*   **Resources:**
-    *   `codesys://project/status`: Checks scripting status and if a project is open.
-    *   `codesys://project/structure`: Retrieves the structure of the open project as text.
-    *   `codesys://pou/{+pou_path}/code`: Reads the implementation or declaration code of a specific POU or DUT/GVL.
-*   **Tools:**
-    *   `open_project`: Opens a specified CODESYS project file (`.project`).
-    *   `create_project`: Creates a new CODESYS project file (`.project`), optionally from a template.
-    *   `save_project`: Saves the currently open CODESYS project.
-    *   `create_pou`: Creates a new POU (Program, Function Block, Function) with a specified language under a parent object in the project tree.
-    *   `add_code`: Sets the implementation code for a specified POU.
-    *   `compile_project`: Initiates the compilation of the open project.
+## Installation
 
-## Prerequisites
+```bash
+npm install @codesys/mcp-toolkit
+```
 
-1.  **CODESYS V3 Installation:** A working CODESYS V3 installation (e.g., 3.5 SP21) with the **Scripting Engine** component enabled.
-2.  **Node.js:** Node.js (version 18 or later recommended) installed on your system. You can download it from [nodejs.org](https://nodejs.org/).
-3.  **MCP Client:** An MCP client application, such as **Claude Desktop**.
+## Configuration
+
+Add the following to your Claude Desktop configuration file (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "codesys_local": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@codesys/mcp-toolkit",
+        "--codesys-path", "C:\\Program Files\\CODESYS 3.5.21.0\\CODESYS\\Common\\CODESYS.exe",
+        "--codesys-profile", "CODESYS V3.5 SP21"
+      ]
+    }
+  }
+}
+```
 
-## Installation
+### Path Handling
 
-### Option 1: Install from npm (Recommended)
+The toolkit now properly handles paths with spaces when launching CODESYS. You don't need to add additional quotes in your configuration.
+
+## Available Tools
+
+This toolkit provides several MCP tools for interacting with CODESYS projects:
+
+- `open_project`: Open an existing CODESYS project
+- `create_project`: Create a new CODESYS project from a template
+- `save_project`: Save the current CODESYS project
+- `create_pou`: Create a new Program Organization Unit (POU)
+- `set_pou_code`: Set the declaration and implementation code for a POU
+- `create_property`: Create a property in a Function Block
+- `create_method`: Create a method in a Function Block
+- `compile_project`: Compile the current CODESYS project
+
+## Example Usage
+
+Claude can use these tools to perform complex CODESYS operations, for example:
 
-```bash
-npm install -g @codesys/mcp-toolkit
+```
+Create a new motor controller FB with properties for speed, state, and temperature
 ```
 
-This will install the server globally, making the `codesys-mcp-toolkit` command available in your terminal.
-
-### Option 2: Install from Source
-
-1. **Clone Repository:**
-   ```bash
-   git clone https://github.com/yourusername/codesys-mcp-server.git
-   cd codesys-mcp-server
-   ```
-
-2. **Install Dependencies:**
-   ```bash
-   npm install
-   ```
-
-3. **Build the Project:**
-   ```bash
-   npm run build
-   ```
-
-4. **Install Globally:**
-   ```bash
-   npm install -g .
-   ```
-
-## Running the Server (via Claude Desktop)
-
-This server is designed to be launched automatically by an MCP client like Claude Desktop using its stdio connection mechanism. You don't typically run it directly from the command line yourself.
-
-## Configuring Claude Desktop
-
-1.  **Locate Configuration File:** Find Claude Desktop's MCP configuration file. On Windows, it's typically located at:
-    `C:\Users\<YourUsername>\AppData\Roaming\Claude\claude_desktop_config.json`
-    (Replace `<YourUsername>` with your actual Windows username).
-2.  **Edit Configuration:** Open `claude_desktop_config.json` in a text editor.
-3.  **Add Server Entry:** Add an entry for the CODESYS server within the `mcpServers` object. Make sure to replace the example paths and profile name with your actual values.
-
-    ```json
-    {
-      "mcpServers": {
-        // ... other servers like puppeteer, filesystem ...
-
-        "codesys_local": {
-          "command": "npx",
-          "args": [
-            "-y",
-            "@codesys/mcp-toolkit",
-            "--codesys-path", "C:\\Program Files\\CODESYS 3.5.21.0\\CODESYS\\Common\\CODESYS.exe",
-            "--codesys-profile", "CODESYS V3.5 SP21"
-          ]
-        }
-      }
-    }
-    ```
-
-    **Important:**
-    *   Replace `C:/Users/ek6430/Desktop/codesys-mcp-server/dist/server.js` with the correct **absolute path** to the compiled `server.js` file on your system. Use forward slashes (`/`) for path separators within this JSON string.
-    *   Replace `"C:\\Program Files\\CODESYS 3.5.21.0\\CODESYS\\Common\\CODESYS.exe"` with the correct **absolute path** to your `CODESYS.exe`. Note the use of double backslashes (`\\`) because backslashes need to be escaped within JSON strings.
-    *   Replace `"CODESYS V3.5 SP21"` with the **exact name** of your CODESYS profile (the one with scripting enabled). Find this name when starting CODESYS or in its title bar.
-4.  **Save the File.**
-5.  **Restart Claude Desktop:** Close Claude Desktop completely and restart it. It will now read the updated configuration and attempt to launch the CODESYS server with the specified arguments.
-6.  **Verify Connection:** Claude Desktop should indicate that it has successfully connected to the "codesys_local" server. You might see the server listed in your available MCP integrations.
-7.  **Use Tools/Resources:** You can now interact with the server from within Claude. For example:
-    *   Ask Claude to "Use the `project-status` resource from the CODESYS Local server."
-    *   Ask Claude to "Use the `open_project` tool from CODESYS Local with filePath set to 'C:/Path/To/Your/Project.project'." (Replace with a real project path).
+Claude will then:
+1. Create a Function Block (FB) in your CODESYS project
+2. Add appropriate properties with getters and setters
+3. Add methods for control operations
+4. Implement the logic in Structured Text (ST)
 
 ## Troubleshooting
 
-*   **Configuration Errors:** If Claude Desktop fails to connect, check its logs (often found in `C:\Users\<YourUsername>\AppData\Roaming\Claude\logs\`). Look for errors related to the `codesys_local` server.
-    *   Verify the paths and profile name in `claude_desktop_config.json` are absolutely correct. Pay attention to path separators (`/` for the script path, `\\` for the CODESYS path within the JSON string).
-    *   Ensure the profile name exactly matches the one in CODESYS.
-*   **Server Script Errors:** If the server starts but tools/resources fail, check the server's output in the Claude Desktop logs. The `executeCodesysScript` function in the server code includes `console.log` and `console.error` statements that might appear in the logs, providing clues about script execution issues.
-*   **Permissions:** The user account running Claude Desktop (and thus the Node.js server) needs permission to execute `CODESYS.exe` and write temporary files to the OS's temporary directory.
-*   **CODESYS Script Errors:** If a CODESYS script itself fails (e.g., invalid POU path, project not open), the error message from the script should be returned in the MCP tool/resource response. Check the `output` field in the response.
-*   **CODESYS Not Running/Responding:** The `executeCodesysScript` might time out or fail if the CODESYS scripting engine cannot be launched properly. Ensure CODESYS isn't already running in a conflicting way (though `--noUI` should help).
-
-## Future Enhancements (Based on Provided API Details)
-
-The detailed API information provided (especially `ScriptOnline`) opens up possibilities for significant future enhancements, such as:
-
-*   Connecting to a running PLC (`create_online_device`, `connect`).
-*   Logging into the PLC (`login`).
-*   Starting/Stopping applications (`start`, `stop`).
-*   Reading/Writing live variable values (`read_value`, `set_prepared_value`, `write_prepared_values`).
-*   Forcing/Unforcing values (`force_prepared_values`, `unforce_all_values`).
-*   Performing downloads and online changes (`login` with options).
-*   Managing PLC files (`download_file`, `upload_file`, `delete_file`).
-*   Handling PLC user management (`create_live_user_management`).
-*   License management (`activate_license`).
+### Path Issues
+
+If you encounter issues with paths:
+
+- Ensure your CODESYS path is correct in the configuration
+- Make sure the toolkit can locate your CODESYS installation
+- Verify the CODESYS profile name matches your installation
+
+### Common Error Messages
+
+- `C:\Program is not recognized...`: Update to the latest version of the toolkit which fixes path handling with spaces
+- `Failed to start CODESYS process`: Check if CODESYS is installed at the specified path

package/README.md.enhanced

@@ -0,0 +1,155 @@
+# @codesys/mcp-toolkit
+
+![npm](https://img.shields.io/npm/v/@codesys/mcp-toolkit)
+![License](https://img.shields.io/github/license/yourusername/codesys-mcp-toolkit)
+
+A Model Context Protocol (MCP) server for CODESYS V3 programming environments. This toolkit enables seamless interaction between MCP clients (like Claude Desktop) and CODESYS, allowing automation of project management, POU creation, code editing, and compilation tasks.
+
+<p align="center">
+  <img src="https://github.com/yourusername/codesys-mcp-toolkit/raw/main/docs/assets/diagram.png" alt="CODESYS MCP Toolkit Architecture" width="600">
+</p>
+
+## 🌟 Features
+
+- **Project Management**
+  - Open existing CODESYS projects
+  - Create new projects from templates
+  - Save project changes
+
+- **POU Management**
+  - Create Programs, Function Blocks, and Functions
+  - Set declaration and implementation code
+  - Create properties and methods for Function Blocks
+  - Compile projects
+
+- **MCP Resources**
+  - `codesys://project/status`: Check scripting status and project state
+  - `codesys://project/{+project_path}/structure`: Retrieve project structure
+  - `codesys://project/{+project_path}/pou/{+pou_path}/code`: Read POU code
+
+- **MCP Tools**
+  - `open_project`: Open specified CODESYS project
+  - `create_project`: Create new CODESYS project
+  - `save_project`: Save currently open project
+  - `create_pou`: Create new Program, Function Block, or Function
+  - `set_pou_code`: Update code for a specified POU
+  - `create_property`: Create property in a Function Block
+  - `create_method`: Create method in a Function Block
+  - `compile_project`: Compile the open project
+
+## 📋 Prerequisites
+
+- **CODESYS V3**: A working CODESYS V3 installation (tested with 3.5 SP21) with **Scripting Engine** component enabled
+- **Node.js**: Version 18 or later required
+- **MCP Client**: An MCP-enabled application (e.g., Claude Desktop)
+
+## 🚀 Installation
+
+### Option 1: Install from npm (Recommended)
+
+```bash
+npm install -g @codesys/mcp-toolkit
+```
+
+This installs the package globally, making the `codesys-mcp-toolkit` command available in your terminal.
+
+### Option 2: Install from Source
+
+```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 .
+```
+
+## 🔧 Configuration
+
+### Claude Desktop Configuration
+
+1. Locate your Claude Desktop configuration file:
+   - Windows: `C:\Users\<YourUsername>\AppData\Roaming\Claude\claude_desktop_config.json`
+
+2. Add the CODESYS MCP server entry:
+
+```json
+{
+  "mcpServers": {
+    "codesys_local": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@codesys/mcp-toolkit",
+        "--codesys-path", "C:\\Program Files\\CODESYS 3.5.21.0\\CODESYS\\Common\\CODESYS.exe",
+        "--codesys-profile", "CODESYS V3.5 SP21"
+      ]
+    }
+  }
+}
+```
+
+3. Customize the paths to match your CODESYS installation:
+   - `--codesys-path`: Path to your CODESYS.exe
+   - `--codesys-profile`: Your CODESYS profile name
+
+4. Restart Claude Desktop to apply the changes
+
+## 🛠️ Usage Examples
+
+### Creating a Function Block with Properties
+
+```
+Ask Claude: "Using the CODESYS Local server, please create a Motor Controller function block with Start and Stop methods, plus CurrentSpeed property."
+```
+
+Claude will execute these MCP tool calls:
+1. `create_pou` to create the MotorController Function Block
+2. `create_property` to add the CurrentSpeed property
+3. `create_method` to add Start and Stop methods
+4. `set_pou_code` to implement each method and property
+
+### Opening and Compiling a Project
+
+```
+Ask Claude: "Can you open the project at C:/MyProjects/TestProject.project using CODESYS Local and compile it?"
+```
+
+Claude will:
+1. Use `open_project` to open the specified file
+2. Use `compile_project` to build the application
+
+## 🔍 Troubleshooting
+
+### Common Issues
+
+- **Connection Failures**: Check Claude Desktop logs for error messages
+- **Path Issues**: Ensure CODESYS executable path is correct
+- **Profile Mismatch**: Verify profile name matches exactly
+- **Permission Problems**: Ensure Claude has appropriate permissions
+- **CODESYS Already Running**: Close other CODESYS instances
+
+### Debug Logs
+
+Check logs at:
+- Windows: `C:\Users\<YourUsername>\AppData\Roaming\Claude\logs\`
+
+## 🤝 Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+## 📝 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgements
+
+- The [CODESYS](https://www.codesys.com/) team for their scripting engine
+- [Model Context Protocol](https://github.com/m-ld/model-context-protocol) project
+- All contributors who have helped improve this toolkit

package/dist/codesys_interop - Copy.js

@@ -0,0 +1,180 @@
+"use strict";
+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.executeCodesysScript = executeCodesysScript;
+const child_process_1 = require("child_process");
+const promises_1 = require("fs/promises");
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+// Define expected success/error markers from the Python scripts
+const SCRIPT_SUCCESS_MARKER = 'SCRIPT_SUCCESS';
+const SCRIPT_ERROR_MARKER = 'SCRIPT_ERROR';
+/**
+ * Executes a CODESYS Python script using the command line interface.
+ *
+ * @param scriptContent The Python script code to execute.
+ * @param codesysExePath The full path to the CODESYS.exe executable.
+ * @param codesysProfileName The name of the CODESYS profile to use for scripting.
+ * @returns A promise resolving to an object containing the success status and the script's output.
+ */
+function executeCodesysScript(scriptContent, codesysExePath, codesysProfileName) {
+    return __awaiter(this, void 0, void 0, function* () {
+        // Validate arguments passed to the function
+        if (!codesysExePath) {
+            throw new Error('CODESYS executable path was not provided to executeCodesysScript.');
+        }
+        if (!codesysProfileName) {
+            throw new Error('CODESYS profile name was not provided to executeCodesysScript.');
+        }
+        // Create a temporary file for the script
+        const tempDir = os.tmpdir();
+        const tempFileName = `codesys_script_${Date.now()}_${Math.random().toString(36).substring(7)}.py`;
+        const tempFilePath = path.join(tempDir, tempFileName);
+        let output = '';
+        let success = false;
+        try {
+            // Normalize line endings to LF (\n)
+            const normalizedScriptContent = scriptContent.replace(/\r\n/g, '\n');
+            // Write the script content to the temporary file using latin1 encoding
+            yield (0, promises_1.writeFile)(tempFilePath, normalizedScriptContent, 'latin1'); // Explicitly use latin1
+            process.stderr.write(`Temporary script written to: ${tempFilePath} with latin1 encoding and LF line endings\n`); // Use process.stderr
+            // Add --additionalfolder argument
+            const additionalFolderPath = "C:\\Program Files\\CODESYS 3.5.21.0\\CODESYS\\AdditionalFolders\\Default"; // Assuming Default instance
+            // Fix: Use shell:true and pass the entire command as a single string without additionalfolder
+            const commandWithArgs = `"${codesysExePath}" --profile="${codesysProfileName}" --noUI --runscript="${tempFilePath}"`;
+            process.stderr.write(`Executing: ${commandWithArgs}\n`); // Log the command string
+            // Spawn the CODESYS process using shell:true for proper argument handling
+            const codesysProcess = (0, child_process_1.spawn)(commandWithArgs, {
+                stdio: ['ignore', 'pipe', 'pipe'], // Ignore stdin, pipe stdout and stderr
+                shell: true // Use shell to handle the command string properly
+            });
+            // Capture stdout
+            codesysProcess.stdout.on('data', (data) => {
+                const chunk = data.toString();
+                // console.error('CODESYS stdout:', chunk); // Optional: Original debug log
+                output += chunk;
+            });
+            // Capture stderr
+            codesysProcess.stderr.on('data', (data) => {
+                const chunk = data.toString();
+                process.stderr.write(`CODESYS stderr: ${chunk}\n`); // Use process.stderr
+                output += chunk; // Include stderr in the output for debugging
+            });
+            // Wait for the process to exit with a timeout
+            const exitCode = yield new Promise((resolve, reject) => {
+                // Add timeout handling
+                const timeoutMs = 30000; // 30 seconds
+                const timeout = setTimeout(() => {
+                    process.stderr.write(`TIMEOUT: CODESYS process did not complete in ${timeoutMs}ms\n`);
+                    // Force resolve with 0 to proceed with parsing output collected so far
+                    codesysProcess.kill();
+                    resolve(0);
+                }, timeoutMs);
+                codesysProcess.on('close', (code) => {
+                    clearTimeout(timeout);
+                    resolve(code !== null && code !== void 0 ? code : 0);
+                });
+                codesysProcess.on('error', (err) => {
+                    clearTimeout(timeout);
+                    // Error starting the process itself (e.g., command not found)
+                    process.stderr.write(`Failed to start CODESYS process: ${err.message}\n`); // Use process.stderr
+                    reject(err);
+                });
+            });
+            process.stderr.write(`CODESYS process exited with code: ${exitCode}\n`); // Use process.stderr
+            // Determine success based on exit code and output markers
+            // Note: CODESYS scripting might return exit code 0 even if the script had logical errors.
+            // Relying on specific output markers is more robust.
+            if (output.includes(SCRIPT_SUCCESS_MARKER)) {
+                success = true;
+            }
+            else if (output.includes(SCRIPT_ERROR_MARKER)) {
+                success = false;
+            }
+            else {
+                // If no markers found, fall back to exit code (less reliable)
+                success = exitCode === 0;
+                if (!success) {
+                    // Append the specific CODESYS error if available and no other marker found
+                    if (!output.includes(SCRIPT_ERROR_MARKER)) {
+                        output += `\nSCRIPT_ERROR: Process exited with non-zero code ${exitCode}. Check CODESYS stderr output above for details.`;
+                    }
+                    else {
+                        output += `\nSCRIPT_ERROR: Process exited with non-zero code ${exitCode}.`;
+                    }
+                }
+                else {
+                    // If exit code is 0 but no success marker, treat as potential issue or simple script
+                    console.error("Warning: CODESYS script finished with exit code 0 but no SCRIPT_SUCCESS marker found."); // Log warning to stderr
+                    // Optionally, you could treat this as success or failure depending on requirements
+                    // For now, let's assume success if exit code is 0 and no error marker.
+                    if (!output.includes(SCRIPT_ERROR_MARKER)) {
+                        success = true;
+                    }
+                }
+            }
+        }
+        catch (error) {
+            process.stderr.write(`Error executing CODESYS script: ${error}\n`); // Use process.stderr
+            output += `\nSCRIPT_ERROR: Failed to execute script process. ${error.message}`;
+            success = false;
+        }
+        finally {
+            // Clean up the temporary file
+            try {
+                yield (0, promises_1.unlink)(tempFilePath);
+                process.stderr.write(`Temporary script deleted: ${tempFilePath}\n`); // Use process.stderr
+            }
+            catch (cleanupError) {
+                process.stderr.write(`Failed to delete temporary script file ${tempFilePath}: ${cleanupError}\n`); // Use process.stderr
+                // Don't overwrite the original error if cleanup fails
+                if (success) { // Only add cleanup error if the main process didn't already fail
+                    output += `\nWARNING: Failed to delete temporary script file ${tempFilePath}. ${cleanupError.message}`;
+                }
+            }
+        }
+        process.stderr.write(`Final script output received:\n---\n${output}\n---\n`); // Use process.stderr
+        return { success, output }; // Revert return object
+    });
+}

package/dist/codesys_interop.js

@@ -73,90 +73,86 @@ function executeCodesysScript(scriptContent, codesysExePath, codesysProfileName)
         const tempFilePath = path.join(tempDir, tempFileName);
         let output = '';
         let success = false;
+        // Define timeout duration *before* the promise
+        const timeoutMs = 60000; // Increased timeout to 60 seconds (accessible below)
         try {
             // Normalize line endings to LF (\n)
             const normalizedScriptContent = scriptContent.replace(/\r\n/g, '\n');
             // Write the script content to the temporary file using latin1 encoding
             yield (0, promises_1.writeFile)(tempFilePath, normalizedScriptContent, 'latin1'); // Explicitly use latin1
-            process.stderr.write(`Temporary script written to: ${tempFilePath} with latin1 encoding and LF line endings\n`); // Use process.stderr
-            // Add --additionalfolder argument
-            const additionalFolderPath = "C:\\Program Files\\CODESYS 3.5.21.0\\CODESYS\\AdditionalFolders\\Default"; // Assuming Default instance
-            // Fix: Use shell:true and pass the entire command as a single string without additionalfolder
-            const commandWithArgs = `"${codesysExePath}" --profile="${codesysProfileName}" --noUI --runscript="${tempFilePath}"`;
-            process.stderr.write(`Executing: ${commandWithArgs}\n`); // Log the command string
-            // Spawn the CODESYS process using shell:true for proper argument handling
-            const codesysProcess = (0, child_process_1.spawn)(commandWithArgs, {
-                stdio: ['ignore', 'pipe', 'pipe'], // Ignore stdin, pipe stdout and stderr
-                shell: true // Use shell to handle the command string properly
+            process.stderr.write(`Temporary script written to: ${tempFilePath} with latin1 encoding and LF line endings\n`);
+            // Arguments for CODESYS.exe
+            const argsArray = [
+                `--profile=${codesysProfileName}`,
+                `--noUI`,
+                `--runscript=${tempFilePath}`
+            ];
+            process.stderr.write(`Executing: "${codesysExePath}" with args: ${JSON.stringify(argsArray)}\n`);
+            process.stderr.write('>>>> DEBUG: Attempting spawn with shell:true to handle paths with spaces. <<<<\n');
+            // Spawn the CODESYS process WITH shell:true to handle paths with spaces properly
+            const codesysProcess = (0, child_process_1.spawn)(`"${codesysExePath}"`, argsArray, {
+                stdio: ['ignore', 'pipe', 'pipe'],
+                shell: true
             });
-            // Capture stdout
+            // Capture stdout & stderr
             codesysProcess.stdout.on('data', (data) => {
                 const chunk = data.toString();
-                // console.error('CODESYS stdout:', chunk); // Optional: Original debug log
                 output += chunk;
             });
-            // Capture stderr
             codesysProcess.stderr.on('data', (data) => {
                 const chunk = data.toString();
-                process.stderr.write(`CODESYS stderr: ${chunk}\n`); // Use process.stderr
-                output += chunk; // Include stderr in the output for debugging
+                process.stderr.write(`CODESYS stderr: ${chunk}\n`);
+                output += chunk;
             });
             // Wait for the process to exit with a timeout
             const exitCode = yield new Promise((resolve, reject) => {
-                // Add timeout handling
-                const timeoutMs = 30000; // 30 seconds
+                // Note: timeoutMs is now defined in the outer scope
                 const timeout = setTimeout(() => {
-                    process.stderr.write(`TIMEOUT: CODESYS process did not complete in ${timeoutMs}ms\n`);
-                    // Force resolve with 0 to proceed with parsing output collected so far
-                    codesysProcess.kill();
-                    resolve(0);
-                }, timeoutMs);
+                    process.stderr.write(`TIMEOUT: CODESYS process did not complete in ${timeoutMs}ms. Killing process.\n`);
+                    codesysProcess.kill('SIGTERM');
+                    setTimeout(() => {
+                        if (!codesysProcess.killed) {
+                            process.stderr.write('Force killing CODESYS process after timeout.\n');
+                            codesysProcess.kill('SIGKILL');
+                        }
+                    }, 2000);
+                    resolve(999); // Use a distinct code for timeout
+                }, timeoutMs); // Use timeoutMs here
                 codesysProcess.on('close', (code) => {
                     clearTimeout(timeout);
                     resolve(code !== null && code !== void 0 ? code : 0);
                 });
                 codesysProcess.on('error', (err) => {
                     clearTimeout(timeout);
-                    // Error starting the process itself (e.g., command not found)
-                    process.stderr.write(`Failed to start CODESYS process: ${err.message}\n`); // Use process.stderr
+                    process.stderr.write(`Failed to start CODESYS process: ${err.message}\n`);
                     reject(err);
                 });
             });
-            process.stderr.write(`CODESYS process exited with code: ${exitCode}\n`); // Use process.stderr
+            process.stderr.write(`CODESYS process exited with code: ${exitCode}\n`);
             // Determine success based on exit code and output markers
-            // Note: CODESYS scripting might return exit code 0 even if the script had logical errors.
-            // Relying on specific output markers is more robust.
             if (output.includes(SCRIPT_SUCCESS_MARKER)) {
                 success = true;
             }
             else if (output.includes(SCRIPT_ERROR_MARKER)) {
                 success = false;
             }
-            else {
-                // If no markers found, fall back to exit code (less reliable)
-                success = exitCode === 0;
-                if (!success) {
-                    // Append the specific CODESYS error if available and no other marker found
-                    if (!output.includes(SCRIPT_ERROR_MARKER)) {
-                        output += `\nSCRIPT_ERROR: Process exited with non-zero code ${exitCode}. Check CODESYS stderr output above for details.`;
-                    }
-                    else {
-                        output += `\nSCRIPT_ERROR: Process exited with non-zero code ${exitCode}.`;
-                    }
+            else if (exitCode !== 0) {
+                success = false;
+                if (!output.includes(SCRIPT_ERROR_MARKER)) {
+                    // Use timeoutMs from outer scope here - NOW IT WORKS!
+                    const exitReason = exitCode === 999 ? `due to timeout (${timeoutMs}ms)` : `with non-zero code ${exitCode}`;
+                    output += `\nSCRIPT_ERROR: Process exited ${exitReason}. Check CODESYS stderr output above for details.`;
                 }
-                else {
-                    // If exit code is 0 but no success marker, treat as potential issue or simple script
-                    console.error("Warning: CODESYS script finished with exit code 0 but no SCRIPT_SUCCESS marker found."); // Log warning to stderr
-                    // Optionally, you could treat this as success or failure depending on requirements
-                    // For now, let's assume success if exit code is 0 and no error marker.
-                    if (!output.includes(SCRIPT_ERROR_MARKER)) {
-                        success = true;
-                    }
+            }
+            else {
+                if (!output.includes(SCRIPT_SUCCESS_MARKER)) {
+                    process.stderr.write("Warning: CODESYS script finished with exit code 0 but no SCRIPT_SUCCESS marker found.\n");
                 }
+                success = true;
             }
         }
         catch (error) {
-            process.stderr.write(`Error executing CODESYS script: ${error}\n`); // Use process.stderr
+            process.stderr.write(`Error executing CODESYS script: ${error}\n`);
             output += `\nSCRIPT_ERROR: Failed to execute script process. ${error.message}`;
             success = false;
         }
@@ -164,17 +160,16 @@ function executeCodesysScript(scriptContent, codesysExePath, codesysProfileName)
             // Clean up the temporary file
             try {
                 yield (0, promises_1.unlink)(tempFilePath);
-                process.stderr.write(`Temporary script deleted: ${tempFilePath}\n`); // Use process.stderr
+                process.stderr.write(`Temporary script deleted: ${tempFilePath}\n`);
             }
             catch (cleanupError) {
-                process.stderr.write(`Failed to delete temporary script file ${tempFilePath}: ${cleanupError}\n`); // Use process.stderr
-                // Don't overwrite the original error if cleanup fails
-                if (success) { // Only add cleanup error if the main process didn't already fail
+                process.stderr.write(`Warning: Failed to delete temporary script file ${tempFilePath}: ${cleanupError.message}\n`);
+                if (success) {
                     output += `\nWARNING: Failed to delete temporary script file ${tempFilePath}. ${cleanupError.message}`;
                 }
             }
         }
-        process.stderr.write(`Final script output received:\n---\n${output}\n---\n`); // Use process.stderr
-        return { success, output }; // Revert return object
+        // process.stderr.write(`Final script output received:\n---\n${output}\n---\n`);
+        return { success, output };
     });
 }

package/docs/configuration.md

@@ -0,0 +1,119 @@
+# Configuration Guide
+
+This guide explains how to configure the CODESYS MCP Toolkit with MCP clients.
+
+## Claude Desktop Configuration
+
+Claude Desktop is a popular MCP client that can use the CODESYS MCP Toolkit.
+
+### Finding the Configuration File
+
+The configuration file is located at:
+- Windows: `C:\Users\<YourUsername>\AppData\Roaming\Claude\claude_desktop_config.json`
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+### Adding the CODESYS MCP Server Entry
+
+Edit the configuration file and add the CODESYS MCP server to the `mcpServers` object:
+
+```json
+{
+  "mcpServers": {
+    "codesys_local": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@codesys/mcp-toolkit",
+        "--codesys-path", "C:\\Program Files\\CODESYS 3.5.21.0\\CODESYS\\Common\\CODESYS.exe",
+        "--codesys-profile", "CODESYS V3.5 SP21"
+      ]
+    }
+  }
+}
+```
+
+### Configuration Parameters
+
+- `command`: Use `npx` to execute the package
+- `args`: Array of arguments
+  - `-y`: Automatically accept npm install prompts
+  - `@codesys/mcp-toolkit`: The package name
+  - `--codesys-path`: Path to your CODESYS.exe
+  - `--codesys-profile`: Your CODESYS profile name
+
+### Customizing for Your Environment
+
+You must customize:
+1. `--codesys-path`: Set to the actual path of your CODESYS executable
+2. `--codesys-profile`: Set to the exact name of your CODESYS profile
+
+**Important Notes:**
+- Use double backslashes (`\\`) in Windows paths in JSON
+- The profile name must match exactly what appears in CODESYS
+
+### Applying Changes
+
+After modifying the configuration:
+1. Save the file
+2. Restart Claude Desktop completely
+3. Claude should now have access to the CODESYS MCP server
+
+## Command-Line Options
+
+When using the toolkit directly, the following options are available:
+
+```
+Usage: codesys-mcp-toolkit [options]
+
+Options:
+  -V, --version                     output the version number
+  -e, --codesys-path <path>         Path to CODESYS executable
+  -p, --codesys-profile <profile>   CODESYS profile name
+  -h, --help                        display help for command
+```
+
+## Verifying Configuration
+
+To verify your configuration:
+
+1. In Claude Desktop, ask:
+   ```
+   Can you please check the status of the CODESYS Local server?
+   ```
+
+2. Claude should use the `project-status` resource and return information about the CODESYS server connection.
+
+## Multiple CODESYS Installations
+
+If you have multiple CODESYS installations, you can create multiple server entries with different names:
+
+```json
+{
+  "mcpServers": {
+    "codesys_3_5_21": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@codesys/mcp-toolkit",
+        "--codesys-path", "C:\\Program Files\\CODESYS 3.5.21.0\\CODESYS\\Common\\CODESYS.exe",
+        "--codesys-profile", "CODESYS V3.5 SP21"
+      ]
+    },
+    "codesys_3_5_19": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@codesys/mcp-toolkit",
+        "--codesys-path", "C:\\Program Files\\CODESYS 3.5.19.0\\CODESYS\\Common\\CODESYS.exe",
+        "--codesys-profile", "CODESYS V3.5 SP19"
+      ]
+    }
+  }
+}
+```
+
+## Next Steps
+
+- Try some [basic examples](examples.md)
+- Learn about the [available tools and resources](api.md)
+- Check the [troubleshooting guide](troubleshooting.md) if you encounter issues

package/docs/index.md

@@ -0,0 +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)

package/docs/installation.md

@@ -0,0 +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.

package/examples/README.md

@@ -0,0 +1,78 @@
+# CODESYS MCP Toolkit Examples
+
+This directory contains examples of how to use the CODESYS MCP toolkit effectively.
+
+## Example Configuration Files
+
+### Basic MCP Configuration
+
+`claude_desktop_config.json` - Example configuration for Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "codesys_local": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@codesys/mcp-toolkit",
+        "--codesys-path", "C:\\Program Files\\CODESYS 3.5.21.0\\CODESYS\\Common\\CODESYS.exe",
+        "--codesys-profile", "CODESYS V3.5 SP21"
+      ]
+    }
+  }
+}
+```
+
+## Example Prompts
+
+Here are some example prompts you can use with Claude Desktop:
+
+### Create a Motor Controller Function Block
+
+```
+Using the CODESYS Local server, please create a MotorController function block with the following:
+
+1. Properties:
+   - SpeedSetpoint (INT)
+   - ActualSpeed (INT)
+   - IsRunning (BOOL)
+
+2. Methods:
+   - Start() - Sets IsRunning to TRUE
+   - Stop() - Sets IsRunning to FALSE
+   - SetSpeed(speed: INT) - Sets SpeedSetpoint to the given value
+
+Create this in a new project at C:/MyProjects/MotorControl.project
+```
+
+### Open and Analyze an Existing Project
+
+```
+Using the CODESYS Local server, please open the project at C:/MyProjects/ExistingProject.project and show me its structure. Then, show me the code for the main POU.
+```
+
+### Compile a Project
+
+```
+Using the CODESYS Local server, please open the project at C:/MyProjects/MyProject.project and compile it. Let me know if there are any errors.
+```
+
+## Programmatic Usage Examples
+
+If you're integrating directly with the server code, here are some examples:
+
+### CLI Usage
+
+Run the server directly:
+
+```bash
+codesys-mcp-toolkit --codesys-path "C:\Program Files\CODESYS 3.5.21.0\CODESYS\Common\CODESYS.exe" --codesys-profile "CODESYS V3.5 SP21"
+```
+
+## Use Cases
+
+* Automated PLC project creation
+* Standardized Function Block library management
+* Continuous integration for CODESYS projects
+* Documentation generation from CODESYS projects

package/examples/sample_config.json

@@ -0,0 +1,33 @@
+{
+  "mcpServers": {
+    "codesys_local": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@codesys/mcp-toolkit",
+        "--codesys-path", "C:\\Program Files\\CODESYS 3.5.21.0\\CODESYS\\Common\\CODESYS.exe",
+        "--codesys-profile", "CODESYS V3.5 SP21"
+      ]
+      // Note: Path with spaces is handled by the toolkit now. No need for additional quotes.
+    },
+    "filesystem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "C:/MyProjects"
+      ]
+    },
+    "memory": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-memory"
+      ]
+    },
+    "puppeteer": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codesys/mcp-toolkit",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "main": "dist/server.js",
   "bin": {
     "codesys-mcp-toolkit": "./dist/bin.js"
@@ -24,11 +24,11 @@
   "description": "Model Context Protocol (MCP) server for CODESYS automation platform",
   "repository": {
     "type": "git",
-    "url": "https://github.com/yourusername/codesys-mcp-server.git"
+    "url": "git+https://github.com/johannesPettersson80/codesys-mcp-toolkit.git"
   },
-  "homepage": "https://github.com/yourusername/codesys-mcp-server",
+  "homepage": "https://github.com/johannesPettersson80/codesys-mcp-toolkit#readme",
   "bugs": {
-    "url": "https://github.com/yourusername/codesys-mcp-server/issues"
+    "url": "https://github.com/johannesPettersson80/codesys-mcp-toolkit/issues"
   },
   "engines": {
     "node": ">=14.0.0"