@codesys/mcp-toolkit 1.1.4 → 1.2.1

package/docs/session_management.md

@@ -0,0 +1,84 @@
+# CODESYS MCP Session Management
+
+## Overview
+
+The CODESYS MCP Toolkit now supports persistent sessions, which significantly improves performance when executing multiple operations in sequence. This document explains how to use the session management functionality.
+
+## Why Session Management?
+
+Previously, each MCP command would start a new CODESYS process, execute the operation, and then shut down the process. This approach is inefficient when performing multiple operations, such as:
+
+- Creating multiple POUs
+- Editing multiple code sections
+- Complex project setup with many steps
+
+With session management, you can:
+1. Start a CODESYS session once
+2. Execute multiple operations without restarting CODESYS
+3. Close the session when you're finished
+
+This can reduce execution time from minutes to seconds for complex tasks.
+
+## Using Session Management with Claude
+
+You can now use the `start_session` and `stop_session` commands in your Claude interactions with CODESYS:
+
+### Starting a Session
+
+```
+Using the CODESYS Local server, run the start_session command to open a persistent CODESYS session.
+```
+
+### Using the Session
+
+Once the session is started, all subsequent operations will use the persistent session automatically:
+
+```
+Using the CODESYS Local server, create a new project at C:/MyProjects/Test.project
+```
+
+```
+Using the CODESYS Local server, add a POU named MainProgram of type Program with ST language
+```
+
+### Checking Session Status
+
+```
+Using the CODESYS Local server, run the session_status command to check the current state of the CODESYS session.
+```
+
+### Stopping the Session
+
+When you're done with all operations, you should close the session to free up resources:
+
+```
+Using the CODESYS Local server, run the stop_session command to close the CODESYS session.
+```
+
+## Recommended Workflow
+
+For the best performance, we recommend the following workflow when working with CODESYS projects:
+
+1. Start the session: `Using the CODESYS Local server, run the start_session command to open a persistent CODESYS session.`
+2. Execute all required operations (create project, create POUs, edit code, etc.)
+3. Stop the session: `Using the CODESYS Local server, run the stop_session command to close the CODESYS session.`
+
+## Technical Notes
+
+- Sessions will automatically close after 5 minutes of inactivity to prevent resource leaks
+- The session status can be in one of the following states: `IDLE`, `STARTING`, `RUNNING`, `BUSY`, `STOPPING`, `STOPPED`, or `ERROR`
+- If a session operation fails, the system will automatically fall back to the standard one-time execution mode
+
+## Limitations
+
+- The session management is still experimental and may not work with all CODESYS operations
+- Only one session can be active at a time per MCP server instance
+- Some operations that modify the CODESYS environment itself may require restarting the session
+
+## Troubleshooting
+
+If you encounter issues with session management:
+
+1. Check the session status: `Using the CODESYS Local server, run the session_status command`
+2. If the status is `ERROR`, try stopping the session and starting a new one
+3. If problems persist, fall back to using standard operations without explicit session management

package/examples/README.md

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

@@ -1,32 +1,32 @@
-{
-  "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"
-      ]
-    },
-    "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"]
-    }
-  }
-}
+{
+  "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"
+      ]
+    },
+    "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,48 +1,51 @@
-{
-  "name": "@codesys/mcp-toolkit",
-  "version": "1.1.4",
-  "description": "Model Context Protocol (MCP) server for CODESYS automation platform",
-  "main": "dist/server.js",
-  "bin": {
-    "codesys-mcp-tool": "./dist/bin.js"
-  },
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "build": "tsc",
-    "start": "node ./dist/server.js"
-  },
-  "keywords": [
-    "codesys",
-    "mcp",
-    "modelcontextprotocol",
-    "plc",
-    "automation",
-    "programming"
-  ],
-  "author": "Your Name <your.email@example.com>",
-  "license": "MIT",
-  "type": "commonjs",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/johannesPettersson80/codesys-mcp-toolkit.git"
-  },
-  "homepage": "https://github.com/johannesPettersson80/codesys-mcp-toolkit#readme",
-  "bugs": {
-    "url": "https://github.com/johannesPettersson80/codesys-mcp-toolkit/issues"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.10.2",
-    "axios": "^1.6.8",
-    "commander": "^11.1.0",
-    "yargs": "^17.7.2",
-    "zod": "^3.24.3"
-  },
-  "devDependencies": {
-    "@types/node": "^20.14.1",
-    "@types/yargs": "^17.0.33",
-    "typescript": "^5.5.3"
-  }
-}
+{
+  "name": "@codesys/mcp-toolkit",
+  "version": "1.2.1",
+  "description": "Model Context Protocol (MCP) server for CODESYS automation platform",
+  "main": "dist/server.js",
+  "bin": {
+    "codesys-mcp-tool": "./dist/bin.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "tsc && node scripts/build.js",
+    "start": "node ./dist/server.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "codesys",
+    "mcp",
+    "modelcontextprotocol",
+    "plc",
+    "automation",
+    "programming"
+  ],
+  "author": "Your Name <your.email@example.com>",
+  "license": "MIT",
+  "type": "commonjs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/johannesPettersson80/codesys-mcp-toolkit.git"
+  },
+  "homepage": "https://github.com/johannesPettersson80/codesys-mcp-toolkit#readme",
+  "bugs": {
+    "url": "https://github.com/johannesPettersson80/codesys-mcp-toolkit/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.10.2",
+    "axios": "^1.6.8",
+    "commander": "^11.1.0",
+    "uuid": "^9.0.0",
+    "yargs": "^17.7.2",
+    "zod": "^3.24.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.1",
+    "@types/uuid": "^9.0.0",
+    "@types/yargs": "^17.0.33",
+    "typescript": "^5.5.3"
+  }
+}