@codesys/mcp-toolkit 1.0.3 → 1.0.4

package/CHANGELOG.md

@@ -1,45 +1,26 @@
-# 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
+# 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

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,79 +1,254 @@
-# CODESYS MCP Toolkit
-
-A Model Context Protocol (MCP) toolkit for interfacing between Claude and CODESYS programming environments.
-
-## Overview
-
-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).
-
-## Installation
-
-```bash
-npm install @codesys/mcp-toolkit
-```
-
-## 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"
-      ]
-    }
-  }
-}
-```
-
-### Path Handling
-
-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:
-
-```
-Create a new motor controller FB with properties for speed, state, and temperature
-```
-
-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
-
-### 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
+# @codesys/mcp-toolkit
+
+![npm](https://img.shields.io/npm/v/@codesys/mcp-toolkit)
+![License](https://img.shields.io/github/license/johannesPettersson80/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.
+
+## 🌟 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/johannesPettersson80/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\`
+
+## 📖 Detailed OOP Workflow Guide
+
+When creating object-oriented structures with this toolkit, follow this step-by-step workflow for best results:
+
+### Creating Function Blocks with Properties and Methods
+
+1. **Create the Function Block**
+   ```
+   create_pou(
+     projectFilePath: "path/to/project.project",
+     name: "PumpController", 
+     type: "FunctionBlock",
+     language: "ST",
+     parentPath: "Application"
+   )
+   ```
+
+2. **Create Properties**
+   ```
+   create_property(
+     projectFilePath: "path/to/project.project",
+     parentPouPath: "Application/PumpController",
+     propertyName: "SpeedSetpoint",
+     propertyType: "INT"
+   )
+   ```
+
+3. **Create Methods**
+   ```
+   create_method(
+     projectFilePath: "path/to/project.project",
+     parentPouPath: "Application/PumpController",
+     methodName: "Start",
+     returnType: "" // Empty for no return value
+   )
+   ```
+
+4. **Implement Methods**
+   ```
+   set_pou_code(
+     projectFilePath: "path/to/project.project",
+     pouPath: "Application/PumpController/Start",
+     implementationCode: "isRunning := TRUE;"
+   )
+   ```
+
+5. **Declare Backing Variables**
+   ```
+   set_pou_code(
+     projectFilePath: "path/to/project.project",
+     pouPath: "Application/PumpController",
+     declarationCode: "VAR PRIVATE\n  _speedSetpoint : INT;\n  _isRunning : BOOL;\nEND_VAR"
+   )
+   ```
+
+6. **Implement Property Accessors**
+   - For GET accessor:
+     ```
+     set_pou_code(
+       projectFilePath: "path/to/project.project",
+       pouPath: "Application/PumpController/SpeedSetpoint/Get",
+       implementationCode: "SpeedSetpoint := _speedSetpoint;"
+     )
+     ```
+   - For SET accessor:
+     ```
+     set_pou_code(
+       projectFilePath: "path/to/project.project",
+       pouPath: "Application/PumpController/SpeedSetpoint/Set",
+       implementationCode: "_speedSetpoint := SpeedSetpoint;"
+     )
+     ```
+
+7. **Save Project**
+   ```
+   save_project(
+     projectFilePath: "path/to/project.project"
+   )
+   ```
+
+### Important Path Usage Notes
+
+- Use forward slashes (`/`) in all object paths
+- Ensure paths are precise and target the specific object
+- For property accessors, always specify the full path including `/Get` or `/Set`
+
+### CODESYS Naming Conventions
+
+- **POUs** (Programs, FBs, Functions): PascalCase (e.g., `MotorControl`)
+- **Interfaces**: PascalCase with I_ prefix (e.g., `I_AxisCommands`)
+- **DUTs** (Structs, Enums): PascalCase (e.g., `MachineState`, `E_OperationMode`)
+- **Variables**: camelCase (e.g., `motorSpeed`)
+- **Backing variables**: camelCase with _ prefix (e.g., `_speedSetpoint`)
+- **Constants**: UPPER_SNAKE_CASE (e.g., `MAX_RPM`)
+- **Properties & Methods**: PascalCase with descriptive names
+
+### Recommended Property Naming
+
+- Control values: Add `Setpoint` suffix (e.g., `SpeedSetpoint`)
+- Measured values: Add `Actual` suffix (e.g., `TemperatureActual`)
+- Status indicators: Use `Is` or `Has` prefix (e.g., `IsRunning`, `HasError`)
+- Configuration: Use descriptive prefixes (e.g., `MaxSpeed`, `MinPressure`)
+
+## 🤝 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