@codesys/mcp-toolkit 1.5.7 → 2.0.0-alpha.0

package/docs/configuration.md

@@ -1,141 +0,0 @@
-# Configuration Guide
-
-This guide explains how to configure the CODESYS MCP Toolkit for use with MCP clients, specifically focusing on Claude Desktop.
-
-## 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 typically located at:
-*   **Windows:** `C:\Users\<YourUsername>\AppData\Roaming\Claude\settings.json` (or `claude_desktop_config.json` in older versions)
-*   **macOS:** `~/Library/Application Support/Claude/settings.json` (or `claude_desktop_config.json`)
-*   **Linux:** `~/.config/Claude/settings.json` (or `claude_desktop_config.json`)
-
-*(If you can't find `settings.json`, look for `claude_desktop_config.json`)*
-
-### Recommended Configuration: 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 Claude Desktop to run the installed command `codesys-mcp-tool` **directly**.
-
-Edit the configuration file and add the CODESYS MCP server to the `mcpServers` object:
-
-```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", // Customize this path!
-        "--codesys-profile", "Your CODESYS Profile Name" // Customize this profile name!
-        // Optional: Add --workspace "/path/to/your/projects" if needed
-      ]
-    }
-    // ... other servers ...
-  }
-}
-```
-
-### Why Direct Command is Recommended
-
-Launching with `npx` (`"command": "npx"`) has been observed to cause errors (`'C:\Program' is not recognized...` or profile errors) when run from within applications like Claude Desktop. This is likely due to `npx` altering the execution environment (like the `PATH` variable) in a way that interferes with how CODESYS finds its own components or parses arguments when run non-interactively. Using the globally installed `codesys-mcp-tool` command directly avoids this interference.
-
-### Customizing for Your Environment
-
-You **must** customize:
-1.  `--codesys-path`: Set this value to the **full and correct path** of your specific `CODESYS.exe` executable file.
-2.  `--codesys-profile`: Set this value to the **exact name** of the CODESYS profile you want to use (this name is visible in the CODESYS UI or start menu).
-
-**Important Notes:**
-*   Use double backslashes (`\\`) for paths in the JSON file if you are on Windows.
-*   The profile name must match *exactly*, including capitalization and spacing.
-*   Ensure `codesys-mcp-tool` is accessible in the system PATH where Claude Desktop runs. Global installation via `npm install -g` usually handles this.
-
-### Applying Changes
-
-After modifying the configuration:
-1.  Save the `settings.json` file.
-2.  **Restart Claude Desktop completely** (ensure it's fully closed and reopened).
-3.  Claude should now attempt to connect to the CODESYS MCP server using the direct command.
-
-### Alternative (Not Recommended): Using `npx`
-
-If you cannot use the direct command method for some reason, you can try `npx`, but be aware of the potential issues mentioned above.
-
-```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"
-        // Optional: "--workspace", "/path/to/your/projects"
-      ]
-    }
-  }
-}
-```
-*If you encounter errors with `npx`, switch to the recommended Direct Command method.*
-
-## Command-Line Options (for `codesys-mcp-tool`)
-
-When running `codesys-mcp-tool` directly or configuring it in your MCP client, 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.
-*   `-V, --version`: Output the version number.
-*   `-h, --help`: Display help for command.
-
-## Verifying Configuration
-
-To verify your configuration within Claude Desktop:
-
-1.  After restarting Claude with the correct configuration, wait for the server to connect (check logs if needed).
-2.  Ask Claude:
-    ```
-    Can you please check the status of the CODESYS Local server?
-    ```
-    (Replace `CODESYS Local` if you used a different key in `mcpServers`).
-
-3.  Claude should use the `codesys://project/status` resource. A successful response will show information like `Scripting OK: true`, `Project Open: ...`, etc. An error indicates a problem with the connection, CODESYS setup, or the script execution itself (check logs).
-
-## Multiple CODESYS Installations
-
-If you have multiple CODESYS installations, you can create multiple server entries in `mcpServers` with different keys (names) and point each to the specific installation:
-
-```json
-{
-  "mcpServers": {
-    "codesys_sp21": { // Unique key for this server
-      "command": "codesys-mcp-tool", // Direct command
-      "args": [
-        "--codesys-path", "C:\\Program Files\\CODESYS 3.5.21.0\\CODESYS\\Common\\CODESYS.exe",
-        "--codesys-profile", "CODESYS V3.5 SP21"
-      ]
-    },
-    "codesys_sp19": { // Unique key for this server
-      "command": "codesys-mcp-tool", // Direct command
-      "args": [
-        "--codesys-path", "C:\\Program Files\\CODESYS 3.5.19.0\\CODESYS\\Common\\CODESYS.exe",
-        "--codesys-profile", "CODESYS V3.5 SP19"
-      ]
-    }
-    // ... other servers ...
-  }
-}
-```
-
-## 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

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

package/docs/installation.md

@@ -1,84 +0,0 @@
-# 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/docs/session_management.md

@@ -1,110 +0,0 @@
-# Session Management in CODESYS MCP Toolkit
-
-## Overview
-
-Starting from version 1.4.0, the CODESYS MCP Toolkit supports persistent sessions. This feature significantly improves performance by allowing a single instance of CODESYS to stay open while multiple commands are executed, then closing it when explicitly requested or after a period of inactivity.
-
-## Benefits
-
-- **Faster execution**: Eliminates the overhead of starting and stopping CODESYS for each command
-- **Shared context**: Commands executed in the same session share the same CODESYS runtime context
-- **Resource efficiency**: Reduces CPU and memory usage by avoiding repeated process creation
-- **Automatic timeout**: Sessions automatically shut down after a period of inactivity (10 minutes by default)
-
-## Session Management Commands
-
-The toolkit provides three specific commands for managing sessions:
-
-### 1. `start_session`
-
-Starts a new persistent CODESYS session. If a session is already running, this command reports that fact without starting another.
-
-**Example**:
-```
-/mcp codesys_local start_session
-```
-
-### 2. `session_status`
-
-Checks if a session is currently active and returns information about it, including:
-- Current state (running, busy, stopped, etc.)
-- How long the session has been running
-- Which project is open in the session (if any)
-
-**Example**:
-```
-/mcp codesys_local session_status
-```
-
-### 3. `stop_session`
-
-Stops an active session and cleans up session resources. If no session is running, this command reports that fact without taking any action.
-
-**Example**:
-```
-/mcp codesys_local stop_session
-```
-
-## How to Use Session Management
-
-### Recommended Workflow
-
-1. Start a session at the beginning of your work:
-   ```
-   /mcp codesys_local start_session
-   ```
-
-2. Execute all your commands normally - they will automatically use the active session:
-   ```
-   /mcp codesys_local open_project --filePath "C:/path/to/project.project"
-   /mcp codesys_local create_pou --projectFilePath "C:/path/to/project.project" --name "MyPOU" --type "FunctionBlock" --language "ST" --parentPath "Application"
-   ```
-
-3. When you're done working, stop the session:
-   ```
-   /mcp codesys_local stop_session
-   ```
-
-If you forget to stop the session, it will automatically time out after 10 minutes of inactivity.
-
-### Session Behavior
-
-- All commands automatically use an active session if one exists
-- If no session exists when a command is run, it will execute without a session (traditional mode)
-- You can explicitly start a session before running commands to improve performance
-- Sessions maintain state between commands, including open projects
-
-## Troubleshooting
-
-### Common Issues
-
-#### Session Won't Start
-
-If you can't start a session, check:
-- Make sure CODESYS is properly installed and accessible at the path specified in your configuration
-- Verify that the CODESYS profile exists and is valid
-- Check if there are any error messages in the client's output
-
-#### Session Appears Unresponsive
-
-If a session seems stuck:
-1. Check its status: `/mcp codesys_local session_status`
-2. If it reports as active but not responding, try stopping it: `/mcp codesys_local stop_session`
-3. If it still doesn't respond, the toolkit includes a forced cleanup mechanism that will activate automatically when you try to stop a non-responsive session
-
-#### Session Files Remain After Stopping
-
-Session state is stored in a temporary directory (`[temp]/codesys_session/`). These files should be cleaned up automatically when a session stops, but in rare cases (like if the process is killed abruptly), they might remain. The toolkit will clean up old files when starting a new session.
-
-## Technical Details
-
-The session management system works by:
-
-1. Starting a CODESYS instance with a special Python script that enters a command loop
-2. Maintaining session state in files within a temporary directory
-3. Communicating with the running session via file-based IPC (Inter-Process Communication)
-4. Executing scripts within the context of the running CODESYS instance
-5. Automatically detecting and handling session health issues
-
-Session files are stored in the system's temporary directory in a subfolder called `codesys_session`.
-EOF < /dev/null

package/examples/README.md

@@ -1,78 +0,0 @@
-# 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 +0,0 @@
-{
-  "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/replacements_session_status.txt

@@ -1,16 +0,0 @@
-f"{SCRIPT_ERROR_MARKER}: Invalid session state file" | "{0}: Invalid session state file".format(SCRIPT_ERROR_MARKER)
-f"{SCRIPT_SUCCESS_MARKER}: Session is not active (Status: {status})" | "{0}: Session is not active (Status: {1})".format(SCRIPT_SUCCESS_MARKER, status)
-f"WARNING: Session lock file is stale by {time_diff:.1f} seconds" | "WARNING: Session lock file is stale by {0:.1f} seconds".format(time_diff)
-f"Error reading lock file: {e}" | "Error reading result: {0}".format(e)
-f"ping_{int(time.time())}" | "ping_{0}".format(int(time.time()))
-f"WARNING: Session did not respond to ping within {timeout} seconds" | "WARNING: Session did not respond to ping within {0} seconds".format(timeout)
-f"Error resetting command file: {e}" | "Error resetting command file: {0}".format(e)
-f"Error during ping test: {e}" | "Error during ping test: {0}".format(e)
-f", Project: {project_name} ({project_path})" | ", Project: {0} ({1})".format(project_name, project_path)
-f"{uptime:.0f} seconds" | "{0:.0f} seconds".format(uptime)
-f"{uptime/60:.1f} minutes" | "{0:.1f} minutes".format(uptime/60)
-f"{SCRIPT_SUCCESS_MARKER}: Session is active (ID: {session_id}, Status: {status}, Uptime: {uptime_str}{project_info})" | "{0}: Session is active (ID: {1}, Status: {2}, Uptime: {3}{4})".format(SCRIPT_SUCCESS_MARKER, session_id, status, uptime_str, project_info)
-f"{SCRIPT_SUCCESS_MARKER}: Session appears to be zombie (ID: {session_id}, Status: {status} but unresponsive)" | "{0}: Session appears to be zombie (ID: {1}, Status: {2} but unresponsive)".format(SCRIPT_SUCCESS_MARKER, session_id, status)
-f"Error updating session state: {e}" | "Error updating session state: {0}".format(e)
-f"{SCRIPT_SUCCESS_MARKER}: Session is not active (Status: {status})" | "{0}: Session is not active (Status: {1})".format(SCRIPT_SUCCESS_MARKER, status)
-f"{SCRIPT_ERROR_MARKER}: Error checking session status - {str(e)}" | "{0}: Error checking session status - {1}".format(SCRIPT_ERROR_MARKER, str(e))