@codesys/mcp-toolkit 1.1.4 → 1.2.0

package/.claude/settings.local.json

@@ -0,0 +1,23 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(grep:*)",
+      "Bash(grep:*)",
+      "Bash(npm version:*)",
+      "Bash(npm version:*)",
+      "Bash(cat:*)",
+      "Bash(cat:*)",
+      "Bash(npm run build:*)",
+      "Bash(npm run build:*)",
+      "Bash(npm install:*)",
+      "Bash(npm install:*)",
+      "Bash(npx tsc:*)",
+      "Bash(npx tsc:*)",
+      "Bash(npm pack:*)",
+      "Bash(npm pack:*)",
+      "Bash(npm publish:*)",
+      "Bash(npm publish:*)"
+    ],
+    "deny": []
+  }
+}

package/CHANGELOG.md

@@ -1,26 +1,32 @@
-# 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.0] - 2025-04-23
-
-### 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
+# 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.2.0] - 2025-05-02
+### Added
+- Session management functionality with `start_session`, `stop_session`, and `session_status` commands
+- Persistent CODESYS sessions for improved performance with multiple operations
+- Documentation for session management
+
+## [1.0.0] - 2025-04-23
+
+### 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/CLAUDE.md

@@ -0,0 +1,26 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build Commands
+- `npm run build` - Compile TypeScript to JavaScript
+- `npm start` - Start the MCP server
+- `tsc` - Run TypeScript compiler manually
+
+## Coding Style Guidelines
+- **Imports**: Import 'os' first if needed, then group related imports
+- **Naming**: Use camelCase for variables/functions, PascalCase for classes/interfaces
+- **Types**: TypeScript with interfaces for structured data, avoid implicit 'any'
+- **Error Handling**: Check conditions early, throw meaningful errors with context
+- **Comments**: Add JSDoc comments for functions, especially exported ones
+- **Formatting**: Follow existing indentation (2 spaces) and code patterns
+- **Path Handling**: Use path.join() for cross-platform compatibility
+- **Promises**: Prefer async/await over raw promises when possible
+- **Logging**: Use console.error for diagnostic/debug messages
+
+## Project Structure
+- `/src` - TypeScript source files
+- `/scripts` - Python scripts for CODESYS integration
+- `/dist` - Compiled JavaScript (generated)
+- `/docs` - Documentation files
+- `/examples` - Example configurations and usage

package/CONTRIBUTING.md

@@ -1,72 +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!
+# 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/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 CODESYS MCP Server Contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 CODESYS MCP Server Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,145 +1,152 @@
-
-# @codesys/mcp-toolkit
-
-![npm](https://img.shields.io/npm/v/@codesys/mcp-toolkit)
-![License](https://img.shields.io/github/license/johannesPettersson80/codesys-mcp-toolkit)
-![Node Version](https://img.shields.io/node/v/@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 via the CODESYS Scripting Engine.
-
-## 🌟 Features
-
-- **Project Management**
-  - Open existing CODESYS projects (`open_project`)
-  - Create new projects from standard templates (`create_project`)
-  - Save project changes (`save_project`)
-
-- **POU Management**
-  - Create Programs, Function Blocks, and Functions (`create_pou`)
-  - Set declaration and implementation code (`set_pou_code`)
-  - Create properties for Function Blocks (`create_property`)
-  - Create methods for Function Blocks (`create_method`)
-  - Compile projects (`compile_project`)
-
-- **MCP Resources**
-  - `codesys://project/status`: Check scripting status and currently open project state.
-  - `codesys://project/{+project_path}/structure`: Retrieve the object structure of a specified project.
-  - `codesys://project/{+project_path}/pou/{+pou_path}/code`: Read the declaration and implementation code for a specified POU, Method, or Property accessor.
-
-## 📋 Prerequisites
-
-- **CODESYS V3**: A working CODESYS V3 installation (tested with 3.5 SP21) with the **Scripting Engine** component enabled during installation.
-- **Node.js**: Version 18.0.0 or later is recommended.
-- **MCP Client**: An MCP-enabled application (e.g., Claude Desktop).
-
-*(Note: CODESYS uses Python 2.7 internally for its scripting engine, but this toolkit handles the interaction; you do not need to manage Python separately.)*
-
-## 🚀 Installation
-
-The recommended way to install is globally using npm:
-
-```bash
-npm install -g @codesys/mcp-toolkit
-```
-
-This installs the package globally, making the `codesys-mcp-tool` command available in your system's terminal PATH.
-
-*(Advanced users can also install from source for development - see CONTRIBUTING.md if available).*
-
-## 🔧 Configuration (IMPORTANT!)
-
-This toolkit needs to know where your CODESYS installation is and which profile to use. Configuration is typically done within your MCP Client application (like Claude Desktop).
-
-### Recommended Configuration Method (Direct Command)
-
-Due to potential environment variable issues (especially with `PATH`) when launching Node.js tools via wrappers like `npx` within certain host applications (e.g., Claude Desktop), it is **strongly recommended** to configure your MCP client to run the installed command `codesys-mcp-tool` **directly**.
-
-**Example for Claude Desktop (`settings.json` -> `mcpServers`):**
-
-```json
-{
-  "mcpServers": {
-    // ... other servers ...
-    "codesys_local": {
-      "command": "codesys-mcp-tool", // <<< Use the direct command name
-      "args": [
-        // Pass arguments directly to the tool using flags
-        "--codesys-path", "C:\\Program Files\\Path\\To\\Your\\CODESYS\\Common\\CODESYS.exe",
-        "--codesys-profile", "Your CODESYS Profile Name"
-        // Optional: Add --workspace "/path/to/your/projects" if needed
-      ]
-    }
-    // ... other servers ...
-  }
-}
-```
-
-**Key Steps:**
-1.  Replace `"C:\\Program Files\\Path\\To\\Your\\CODESYS\\Common\\CODESYS.exe"` with the **full, correct path** to your specific `CODESYS.exe` file.
-2.  Replace `"Your CODESYS Profile Name"` with the **exact name** of the CODESYS profile you want to use (visible in the CODESYS UI).
-3.  Ensure the `codesys-mcp-tool` command is accessible in the system PATH where the MCP Client application runs. Global installation via `npm install -g` usually handles this.
-4.  Restart your MCP Client application (e.g., Claude Desktop) to apply the settings changes.
-
-### Alternative Configuration (Using `npx` - Not Recommended)
-
-Launching with `npx` has been observed to cause immediate errors (`'C:\Program' is not recognized...`) in some environments, likely due to how `npx` handles the execution environment. **Use the Direct Command method above if possible.** If you must use `npx`:
-
-```json
-// Example using npx (POTENTIALLY PROBLEMATIC - USE WITH CAUTION):
-{
-  "mcpServers": {
-    "codesys_local": {
-      "command": "npx",
-      "args": [
-        "-y", // Tells npx to install temporarily if not found globally
-        "@codesys/mcp-toolkit",
-        // Arguments for the tool MUST come AFTER the package name
-        "--codesys-path", "C:\\Program Files\\Path\\To\\Your\\CODESYS\\Common\\CODESYS.exe",
-        "--codesys-profile", "Your CODESYS Profile Name"
-      ]
-    }
-  }
-}
-```
-*(Note: The `--` separator after the package name might sometimes help `npx` but is not guaranteed to fix the environment issue.)*
-
-## 🛠️ Command-Line Arguments
-
-When running `codesys-mcp-tool` directly or configuring it, you can use these arguments:
-
-*   `-p, --codesys-path <path>`: Full path to `CODESYS.exe`. (Required, overrides `CODESYS_PATH` env var, has a default but relying on it is not recommended).
-*   `-f, --codesys-profile <profile>`: Name of the CODESYS profile. (Required, overrides `CODESYS_PROFILE` env var, has a default but relying on it is not recommended).
-*   `-w, --workspace <dir>`: Workspace directory for resolving relative project paths passed to tools. Defaults to the directory where the command was launched (which might be unpredictable when run by another application). Setting this explicitly might be needed if using relative paths.
-*   `-h, --help`: Show help message.
-*   `--version`: Show package version.
-
-## 🔍 Troubleshooting
-
-*   **`'C:\Program' is not recognized...` error immediately after connection:**
-    *   **Cause:** This typically happens when the tool is launched via `npx` within an environment like Claude Desktop. The execution environment (`PATH` variable) provided to the process likely causes an internal CODESYS command (like running Python) to fail.
-    *   **Solution:** Configure your MCP Client to run the command **directly** (`"command": "codesys-mcp-tool"`) instead of using `"command": "npx"`. See the **Recommended Configuration Method** section above.
-
-*   **Tool Fails / Errors in Output:**
-    *   Check the logs from your MCP Client application (e.g., Claude Desktop logs). Look for `INTEROP:` messages or Python `DEBUG:` / `ERROR:` messages printed to stderr from the CODESYS script execution.
-    *   Ensure the `--codesys-path` and `--codesys-profile` arguments passed to the command are correct and point to a valid CODESYS installation with scripting enabled.
-    *   Verify the project paths and object paths you are passing to tools are correct (use forward slashes `/`).
-    *   Make sure no other CODESYS instances are running in conflicting ways (e.g., holding a lock on the profile).
-
-*   **`command not found: codesys-mcp-tool`:**
-    *   Ensure the package was installed globally (`npm install -g @codesys/mcp-toolkit`).
-    *   Ensure the npm global bin directory is in your system's `PATH` environment variable. Find it with `npm config get prefix` and add the `bin` subdirectory (or the main directory itself on Windows) to your PATH.
-
-*   **Check Logs:**
-    *   Claude Desktop logs: `C:\Users\<YourUsername>\AppData\Roaming\Claude\logs\` (Windows)
-
-## 🤝 Contributing
-Contributions, issues, and feature requests are welcome! Feel free to check the issues page. (Optionally add a CONTRIBUTING.md file with more details).
-
-## 📝 License
-This project is licensed under the MIT License - see the LICENSE file for details.
-
-## 🙏 Acknowledgements
-- The CODESYS GmbH team for the powerful CODESYS platform and its scripting engine.
-- The Model Context Protocol project for defining the interaction standard.
-- All contributors and users who help improve this toolkit.
-
+
+# @codesys/mcp-toolkit
+
+![npm](https://img.shields.io/npm/v/@codesys/mcp-toolkit)
+![License](https://img.shields.io/github/license/johannesPettersson80/codesys-mcp-toolkit)
+![Node Version](https://img.shields.io/node/v/@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 via the CODESYS Scripting Engine.
+
+## 🌟 Features
+
+- **Project Management**
+  - Open existing CODESYS projects (`open_project`)
+  - Create new projects from standard templates (`create_project`)
+  - Save project changes (`save_project`)
+
+- **POU Management**
+  - Create Programs, Function Blocks, and Functions (`create_pou`)
+  - Set declaration and implementation code (`set_pou_code`)
+  - Create properties for Function Blocks (`create_property`)
+  - Create methods for Function Blocks (`create_method`)
+  - Compile projects (`compile_project`)
+
+- **Session Management** (New!)
+  - Start a persistent CODESYS session (`start_session`)
+  - Execute multiple operations without restarting CODESYS
+  - Check session status (`session_status`)
+  - Close the session when finished (`stop_session`)
+  - See [Session Management Documentation](docs/session_management.md) for details
+
+- **MCP Resources**
+  - `codesys://project/status`: Check scripting status and currently open project state.
+  - `codesys://project/{+project_path}/structure`: Retrieve the object structure of a specified project.
+  - `codesys://project/{+project_path}/pou/{+pou_path}/code`: Read the declaration and implementation code for a specified POU, Method, or Property accessor.
+
+## 📋 Prerequisites
+
+- **CODESYS V3**: A working CODESYS V3 installation (tested with 3.5 SP21) with the **Scripting Engine** component enabled during installation.
+- **Node.js**: Version 18.0.0 or later is recommended.
+- **MCP Client**: An MCP-enabled application (e.g., Claude Desktop).
+
+*(Note: CODESYS uses Python 2.7 internally for its scripting engine, but this toolkit handles the interaction; you do not need to manage Python separately.)*
+
+## 🚀 Installation
+
+The recommended way to install is globally using npm:
+
+```bash
+npm install -g @codesys/mcp-toolkit
+```
+
+This installs the package globally, making the `codesys-mcp-tool` command available in your system's terminal PATH.
+
+*(Advanced users can also install from source for development - see CONTRIBUTING.md if available).*
+
+## 🔧 Configuration (IMPORTANT!)
+
+This toolkit needs to know where your CODESYS installation is and which profile to use. Configuration is typically done within your MCP Client application (like Claude Desktop).
+
+### Recommended Configuration Method (Direct Command)
+
+Due to potential environment variable issues (especially with `PATH`) when launching Node.js tools via wrappers like `npx` within certain host applications (e.g., Claude Desktop), it is **strongly recommended** to configure your MCP client to run the installed command `codesys-mcp-tool` **directly**.
+
+**Example for Claude Desktop (`settings.json` -> `mcpServers`):**
+
+```json
+{
+  "mcpServers": {
+    // ... other servers ...
+    "codesys_local": {
+      "command": "codesys-mcp-tool", // <<< Use the direct command name
+      "args": [
+        // Pass arguments directly to the tool using flags
+        "--codesys-path", "C:\\Program Files\\Path\\To\\Your\\CODESYS\\Common\\CODESYS.exe",
+        "--codesys-profile", "Your CODESYS Profile Name"
+        // Optional: Add --workspace "/path/to/your/projects" if needed
+      ]
+    }
+    // ... other servers ...
+  }
+}
+```
+
+**Key Steps:**
+1.  Replace `"C:\\Program Files\\Path\\To\\Your\\CODESYS\\Common\\CODESYS.exe"` with the **full, correct path** to your specific `CODESYS.exe` file.
+2.  Replace `"Your CODESYS Profile Name"` with the **exact name** of the CODESYS profile you want to use (visible in the CODESYS UI).
+3.  Ensure the `codesys-mcp-tool` command is accessible in the system PATH where the MCP Client application runs. Global installation via `npm install -g` usually handles this.
+4.  Restart your MCP Client application (e.g., Claude Desktop) to apply the settings changes.
+
+### Alternative Configuration (Using `npx` - Not Recommended)
+
+Launching with `npx` has been observed to cause immediate errors (`'C:\Program' is not recognized...`) in some environments, likely due to how `npx` handles the execution environment. **Use the Direct Command method above if possible.** If you must use `npx`:
+
+```json
+// Example using npx (POTENTIALLY PROBLEMATIC - USE WITH CAUTION):
+{
+  "mcpServers": {
+    "codesys_local": {
+      "command": "npx",
+      "args": [
+        "-y", // Tells npx to install temporarily if not found globally
+        "@codesys/mcp-toolkit",
+        // Arguments for the tool MUST come AFTER the package name
+        "--codesys-path", "C:\\Program Files\\Path\\To\\Your\\CODESYS\\Common\\CODESYS.exe",
+        "--codesys-profile", "Your CODESYS Profile Name"
+      ]
+    }
+  }
+}
+```
+*(Note: The `--` separator after the package name might sometimes help `npx` but is not guaranteed to fix the environment issue.)*
+
+## 🛠️ Command-Line Arguments
+
+When running `codesys-mcp-tool` directly or configuring it, you can use these arguments:
+
+*   `-p, --codesys-path <path>`: Full path to `CODESYS.exe`. (Required, overrides `CODESYS_PATH` env var, has a default but relying on it is not recommended).
+*   `-f, --codesys-profile <profile>`: Name of the CODESYS profile. (Required, overrides `CODESYS_PROFILE` env var, has a default but relying on it is not recommended).
+*   `-w, --workspace <dir>`: Workspace directory for resolving relative project paths passed to tools. Defaults to the directory where the command was launched (which might be unpredictable when run by another application). Setting this explicitly might be needed if using relative paths.
+*   `-h, --help`: Show help message.
+*   `--version`: Show package version.
+
+## 🔍 Troubleshooting
+
+*   **`'C:\Program' is not recognized...` error immediately after connection:**
+    *   **Cause:** This typically happens when the tool is launched via `npx` within an environment like Claude Desktop. The execution environment (`PATH` variable) provided to the process likely causes an internal CODESYS command (like running Python) to fail.
+    *   **Solution:** Configure your MCP Client to run the command **directly** (`"command": "codesys-mcp-tool"`) instead of using `"command": "npx"`. See the **Recommended Configuration Method** section above.
+
+*   **Tool Fails / Errors in Output:**
+    *   Check the logs from your MCP Client application (e.g., Claude Desktop logs). Look for `INTEROP:` messages or Python `DEBUG:` / `ERROR:` messages printed to stderr from the CODESYS script execution.
+    *   Ensure the `--codesys-path` and `--codesys-profile` arguments passed to the command are correct and point to a valid CODESYS installation with scripting enabled.
+    *   Verify the project paths and object paths you are passing to tools are correct (use forward slashes `/`).
+    *   Make sure no other CODESYS instances are running in conflicting ways (e.g., holding a lock on the profile).
+
+*   **`command not found: codesys-mcp-tool`:**
+    *   Ensure the package was installed globally (`npm install -g @codesys/mcp-toolkit`).
+    *   Ensure the npm global bin directory is in your system's `PATH` environment variable. Find it with `npm config get prefix` and add the `bin` subdirectory (or the main directory itself on Windows) to your PATH.
+
+*   **Check Logs:**
+    *   Claude Desktop logs: `C:\Users\<YourUsername>\AppData\Roaming\Claude\logs\` (Windows)
+
+## 🤝 Contributing
+Contributions, issues, and feature requests are welcome! Feel free to check the issues page. (Optionally add a CONTRIBUTING.md file with more details).
+
+## 📝 License
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## 🙏 Acknowledgements
+- The CODESYS GmbH team for the powerful CODESYS platform and its scripting engine.
+- The Model Context Protocol project for defining the interaction standard.
+- All contributors and users who help improve this toolkit.
+