@codesys/mcp-toolkit 1.1.2 → 1.1.3

package/dist/server.js

@@ -6,7 +6,7 @@
  *
  * IMPORTANT: This server receives configuration as parameters from bin.ts,
  * which helps avoid issues with command-line argument passing in different execution environments.
- * (Incorporates script templates from v1.6.9)
+ * (Incorporates script templates from v1.6.9 and improved tool descriptions)
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -122,7 +122,11 @@ function startMcpServer(config) {
         const server = new mcp_js_1.McpServer({
             name: "CODESYS Control MCP Server",
             version: "1.7.1", // Update version as needed
-            capabilities: { resources: {}, tools: {} }
+            capabilities: {
+                // Explicitly declare capabilities - enables listChanged notifications if supported by SDK
+                resources: { listChanged: true }, // Assuming you might want to notify if resources change dynamically
+                tools: { listChanged: true } // Assuming you might want to notify if tools change dynamically (less common)
+            }
         });
         console.error("SERVER.TS: McpServer instance created.");
         // --- End MCP Server Initialization ---
@@ -1165,27 +1169,31 @@ except Exception as e:
         }));
         // --- End Resources ---
         // --- Tools ---
-        server.tool("open_project", { filePath: zod_1.z.string().describe("Path to the project file.") }, (args) => __awaiter(this, void 0, void 0, function* () {
+        server.tool("open_project", // Tool Name
+        "Opens an existing CODESYS project file.", // Tool Description
+        {
+            filePath: zod_1.z.string().describe("Path to the project file (e.g., 'C:/Projects/MyPLC.project' or '/Users/user/projects/my_project.project').")
+        }, (args) => __awaiter(this, void 0, void 0, function* () {
             const { filePath } = args;
             let absPath = path.normalize(path.isAbsolute(filePath) ? filePath : path.join(WORKSPACE_DIR, filePath));
             console.error(`Tool call: open_project: ${absPath}`);
             try {
                 const escapedPath = absPath.replace(/\\/g, '\\\\');
-                // *** DEFINE script ***
                 const script = OPEN_PROJECT_SCRIPT_TEMPLATE.replace("{PROJECT_FILE_PATH}", escapedPath);
-                // *** END DEFINE script ***
                 const result = yield (0, codesys_interop_1.executeCodesysScript)(script, codesysExePath, codesysProfileName);
                 const success = result.success && result.output.includes("SCRIPT_SUCCESS");
-                // **** RETURN MCP STRUCTURE ****
                 return { content: [{ type: "text", text: success ? `Project opened: ${absPath}` : `Failed open project ${absPath}. Output:\n${result.output}` }], isError: !success };
             }
             catch (e) {
                 console.error(`Error open_project ${absPath}: ${e}`);
-                // **** RETURN MCP STRUCTURE ****
                 return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
             }
         }));
-        server.tool("create_project", { filePath: zod_1.z.string().describe("Path for new project.") }, (args) => __awaiter(this, void 0, void 0, function* () {
+        server.tool("create_project", // Tool Name
+        "Creates a new CODESYS project from the standard template.", // Tool Description
+        {
+            filePath: zod_1.z.string().describe("Path where the new project file should be created (e.g., 'C:/Projects/NewPLC.project' or '/Users/user/projects/new_project.project').")
+        }, (args) => __awaiter(this, void 0, void 0, function* () {
             const { filePath } = args;
             let absPath = path.normalize(path.isAbsolute(filePath) ? filePath : path.join(WORKSPACE_DIR, filePath));
             console.error(`Tool call: create_project (copy template): ${absPath}`);
@@ -1222,56 +1230,53 @@ except Exception as e:
             }
             catch (e) {
                 console.error(`Template Error: ${e.message}`);
-                // **** RETURN MCP STRUCTURE ****
                 return { content: [{ type: "text", text: `Template Error: ${e.message}` }], isError: true };
             }
             try {
                 const escProjPath = absPath.replace(/\\/g, '\\\\');
                 const escTmplPath = templatePath.replace(/\\/g, '\\\\');
-                // *** DEFINE script ***
                 const script = CREATE_PROJECT_SCRIPT_TEMPLATE
                     .replace("{PROJECT_FILE_PATH}", escProjPath)
                     .replace("{TEMPLATE_PROJECT_PATH}", escTmplPath);
-                // *** END DEFINE script ***
                 console.error(">>> create_project (copy-then-open): PREPARED SCRIPT:", script.substring(0, 500) + "...");
                 const result = yield (0, codesys_interop_1.executeCodesysScript)(script, codesysExePath, codesysProfileName);
                 console.error(">>> create_project (copy-then-open): EXECUTION RESULT:", JSON.stringify(result));
                 const success = result.success && result.output.includes("SCRIPT_SUCCESS");
-                // **** RETURN MCP STRUCTURE ****
                 return { content: [{ type: "text", text: success ? `Project created from template: ${absPath}` : `Failed create project ${absPath} from template. Output:\n${result.output}` }], isError: !success };
             }
             catch (e) {
                 console.error(`Error create_project ${absPath}: ${e}`);
-                // **** RETURN MCP STRUCTURE ****
                 return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
             }
         }));
-        server.tool("save_project", { projectFilePath: zod_1.z.string().describe("Path to project.") }, (args) => __awaiter(this, void 0, void 0, function* () {
+        server.tool("save_project", // Tool Name
+        "Saves the currently open CODESYS project.", // Tool Description
+        {
+            projectFilePath: zod_1.z.string().describe("Path to the project file to ensure is open before saving (e.g., 'C:/Projects/MyPLC.project').")
+        }, (args) => __awaiter(this, void 0, void 0, function* () {
             const { projectFilePath } = args;
             let absPath = path.normalize(path.isAbsolute(projectFilePath) ? projectFilePath : path.join(WORKSPACE_DIR, projectFilePath));
             console.error(`Tool call: save_project: ${absPath}`);
             try {
                 const escapedPath = absPath.replace(/\\/g, '\\\\');
-                // *** DEFINE script ***
                 const script = SAVE_PROJECT_SCRIPT_TEMPLATE.replace("{PROJECT_FILE_PATH}", escapedPath);
-                // *** END DEFINE script ***
                 const result = yield (0, codesys_interop_1.executeCodesysScript)(script, codesysExePath, codesysProfileName);
                 const success = result.success && result.output.includes("SCRIPT_SUCCESS");
-                // **** RETURN MCP STRUCTURE ****
                 return { content: [{ type: "text", text: success ? `Project saved: ${absPath}` : `Failed save project ${absPath}. Output:\n${result.output}` }], isError: !success };
             }
             catch (e) {
                 console.error(`Error save_project ${absPath}: ${e}`);
-                // **** RETURN MCP STRUCTURE ****
                 return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
             }
         }));
-        server.tool("create_pou", {
-            projectFilePath: zod_1.z.string().describe("Path to project."),
-            name: zod_1.z.string().describe("Name for the new POU."),
+        server.tool("create_pou", // Tool Name
+        "Creates a new Program, Function Block, or Function POU within the specified CODESYS project.", // Tool Description
+        {
+            projectFilePath: zod_1.z.string().describe("Path to the project file (e.g., 'C:/Projects/MyPLC.project')."),
+            name: zod_1.z.string().describe("Name for the new POU (must be a valid IEC identifier)."),
             type: PouTypeEnum.describe("Type of POU (Program, FunctionBlock, Function)."),
-            language: ImplementationLanguageEnum.describe("Implementation language (ST, LD, FBD, etc.). Will use default if not directly supported/mapped by script."),
-            parentPath: zod_1.z.string().describe("Relative path under project/application (e.g., 'Application' or 'MyFolder/SubFolder').")
+            language: ImplementationLanguageEnum.describe("Implementation language (ST, LD, FBD, etc.). CODESYS default will be used if specific language is not set or directly supported by scripting for this POU type."),
+            parentPath: zod_1.z.string().describe("Relative path under project root or application where the POU should be created (e.g., 'Application' or 'MyFolder/SubFolder').")
         }, (args) => __awaiter(this, void 0, void 0, function* () {
             const { projectFilePath, name, type, language, parentPath } = args;
             let absPath = path.normalize(path.isAbsolute(projectFilePath) ? projectFilePath : path.join(WORKSPACE_DIR, projectFilePath));
@@ -1280,31 +1285,29 @@ except Exception as e:
             console.error(`Tool call: create_pou: Name='${sanName}', Type='${type}', Lang='${language}', Parent='${sanParentPath}', Project='${absPath}'`);
             try {
                 const escProjPath = absPath.replace(/\\/g, '\\\\');
-                // *** DEFINE script ***
                 let script = CREATE_POU_SCRIPT_TEMPLATE.replace("{PROJECT_FILE_PATH}", escProjPath);
                 script = script.replace("{POU_NAME}", sanName);
                 script = script.replace("{POU_TYPE_STR}", type);
                 script = script.replace("{IMPL_LANGUAGE_STR}", language);
                 script = script.replace("{PARENT_PATH}", sanParentPath);
-                // *** END DEFINE script ***
                 console.error(">>> create_pou: PREPARED SCRIPT:", script.substring(0, 500) + "...");
                 const result = yield (0, codesys_interop_1.executeCodesysScript)(script, codesysExePath, codesysProfileName);
                 console.error(">>> create_pou: EXECUTION RESULT:", JSON.stringify(result));
                 const success = result.success && result.output.includes("SCRIPT_SUCCESS");
-                // **** RETURN MCP STRUCTURE ****
                 return { content: [{ type: "text", text: success ? `POU '${sanName}' created in '${sanParentPath}' of ${absPath}. Project saved.` : `Failed create POU '${sanName}'. Output:\n${result.output}` }], isError: !success };
             }
             catch (e) {
                 console.error(`Error create_pou ${sanName} in ${absPath}: ${e}`);
-                // **** RETURN MCP STRUCTURE ****
                 return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
             }
         }));
-        server.tool("set_pou_code", {
-            projectFilePath: zod_1.z.string().describe("Path to project."),
-            pouPath: zod_1.z.string().describe("Relative POU/Method/Property path (e.g., 'Application/MyPOU' or 'MyFolder/MyFB/MyMethod')."),
-            declarationCode: zod_1.z.string().describe("Code for the declaration part (VAR...END_VAR).").optional(),
-            implementationCode: zod_1.z.string().describe("Code for the implementation logic part.").optional()
+        server.tool("set_pou_code", // Tool Name
+        "Sets the declaration and/or implementation code for a specific POU, Method, or Property.", // Tool Description
+        {
+            projectFilePath: zod_1.z.string().describe("Path to the project file (e.g., 'C:/Projects/MyPLC.project')."),
+            pouPath: zod_1.z.string().describe("Full relative path to the target object (e.g., 'Application/MyPOU', 'MyFolder/MyFB/MyMethod', 'MyFolder/MyFB/MyProperty')."),
+            declarationCode: zod_1.z.string().describe("Code for the declaration part (VAR...END_VAR). If omitted, the declaration is not changed.").optional(),
+            implementationCode: zod_1.z.string().describe("Code for the implementation logic part. If omitted, the implementation is not changed.").optional()
         }, (args) => __awaiter(this, void 0, void 0, function* () {
             const { projectFilePath, pouPath, declarationCode, implementationCode } = args;
             if (declarationCode === undefined && implementationCode === undefined) {
@@ -1318,29 +1321,28 @@ except Exception as e:
                 // Escape content for Python triple-quoted strings
                 const sanDeclCode = (declarationCode !== null && declarationCode !== void 0 ? declarationCode : "").replace(/\\/g, '\\\\').replace(/"""/g, '\\"\\"\\"');
                 const sanImplCode = (implementationCode !== null && implementationCode !== void 0 ? implementationCode : "").replace(/\\/g, '\\\\').replace(/"""/g, '\\"\\"\\"');
-                // *** DEFINE script ***
                 let script = SET_POU_CODE_SCRIPT_TEMPLATE.replace("{PROJECT_FILE_PATH}", escProjPath);
                 script = script.replace("{POU_FULL_PATH}", sanPouPath);
                 script = script.replace("{DECLARATION_CONTENT}", sanDeclCode);
                 script = script.replace("{IMPLEMENTATION_CONTENT}", sanImplCode);
-                // *** END DEFINE script ***
                 console.error(">>> set_pou_code: PREPARED SCRIPT:", script.substring(0, 500) + "...");
                 const result = yield (0, codesys_interop_1.executeCodesysScript)(script, codesysExePath, codesysProfileName);
                 console.error(">>> set_pou_code: EXECUTION RESULT:", JSON.stringify(result));
                 const success = result.success && result.output.includes("SCRIPT_SUCCESS");
-                // **** RETURN MCP STRUCTURE ****
                 return { content: [{ type: "text", text: success ? `Code set for '${sanPouPath}' in ${absPath}. Project saved.` : `Failed set code for '${sanPouPath}'. Output:\n${result.output}` }], isError: !success };
             }
             catch (e) {
                 console.error(`Error set_pou_code ${sanPouPath} in ${absPath}: ${e}`);
-                // **** RETURN MCP STRUCTURE ****
                 return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
             }
         }));
-        server.tool("create_property", {
-            projectFilePath: zod_1.z.string().describe("Path to the project file."),
-            parentPouPath: zod_1.z.string().describe("Relative path to the parent POU (e.g., 'Application/MyFB')."),
-            propertyName: zod_1.z.string().describe("Name of the new property."),
+        server.tool("create_property", // Tool Name
+        "Creates a new Property within a specific Function Block POU.", // Tool Description
+        {
+            projectFilePath: zod_1.z.string().describe("Path to the project file (e.g., 'C:/Projects/MyPLC.project')."),
+            // Assuming properties can only be added to FBs in standard CODESYS scripting
+            parentPouPath: zod_1.z.string().describe("Relative path to the parent Function Block POU (e.g., 'Application/MyFB')."),
+            propertyName: zod_1.z.string().describe("Name for the new property (must be a valid IEC identifier)."),
             propertyType: zod_1.z.string().describe("Data type of the property (e.g., 'BOOL', 'INT', 'MyDUT').")
         }, (args) => __awaiter(this, void 0, void 0, function* () {
             const { projectFilePath, parentPouPath, propertyName, propertyType } = args;
@@ -1350,22 +1352,18 @@ except Exception as e:
             const sanPropType = propertyType.trim();
             console.error(`Tool call: create_property: Name='${sanPropName}', Type='${sanPropType}', ParentPOU='${sanParentPath}', Project='${absPath}'`);
             if (!sanPropName || !sanPropType) {
-                // **** RETURN MCP STRUCTURE ****
                 return { content: [{ type: "text", text: `Error: Property name and type cannot be empty.` }], isError: true };
             }
             try {
                 const escProjPath = absPath.replace(/\\/g, '\\\\');
-                // *** DEFINE script ***
                 let script = CREATE_PROPERTY_SCRIPT_TEMPLATE.replace("{PROJECT_FILE_PATH}", escProjPath);
                 script = script.replace("{PARENT_POU_FULL_PATH}", sanParentPath);
                 script = script.replace("{PROPERTY_NAME}", sanPropName);
                 script = script.replace("{PROPERTY_TYPE}", sanPropType);
-                // *** END DEFINE script ***
                 console.error(">>> create_property: PREPARED SCRIPT:", script.substring(0, 500) + "...");
                 const result = yield (0, codesys_interop_1.executeCodesysScript)(script, codesysExePath, codesysProfileName);
                 console.error(">>> create_property: EXECUTION RESULT:", JSON.stringify(result));
                 const success = result.success && result.output.includes("SCRIPT_SUCCESS");
-                // **** RETURN MCP STRUCTURE ****
                 return {
                     content: [{ type: "text", text: success ? `Property '${sanPropName}' created under '${sanParentPath}' in ${absPath}. Project saved.` : `Failed to create property '${sanPropName}'. Output:\n${result.output}` }],
                     isError: !success
@@ -1373,15 +1371,17 @@ except Exception as e:
             }
             catch (e) {
                 console.error(`Error create_property ${sanPropName} in ${absPath}: ${e}`);
-                // **** RETURN MCP STRUCTURE ****
                 return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
             }
         }));
-        server.tool("create_method", {
-            projectFilePath: zod_1.z.string().describe("Path to the project file."),
-            parentPouPath: zod_1.z.string().describe("Relative path to the parent POU (e.g., 'Application/MyFB')."),
-            methodName: zod_1.z.string().describe("Name of the new method."),
-            returnType: zod_1.z.string().optional().describe("Return type (e.g., 'BOOL', 'INT'). Leave empty or omit for no return value."),
+        server.tool("create_method", // Tool Name
+        "Creates a new Method within a specific Function Block POU.", // Tool Description
+        {
+            projectFilePath: zod_1.z.string().describe("Path to the project file (e.g., 'C:/Projects/MyPLC.project')."),
+            // Assuming methods can typically only be added to FBs in standard CODESYS scripting
+            parentPouPath: zod_1.z.string().describe("Relative path to the parent Function Block POU (e.g., 'Application/MyFB')."),
+            methodName: zod_1.z.string().describe("Name of the new method (must be a valid IEC identifier)."),
+            returnType: zod_1.z.string().optional().describe("Return type (e.g., 'BOOL', 'INT'). Leave empty or omit for no return value (PROCEDURE)."),
         }, (args) => __awaiter(this, void 0, void 0, function* () {
             const { projectFilePath, parentPouPath, methodName, returnType } = args;
             let absPath = path.normalize(path.isAbsolute(projectFilePath) ? projectFilePath : path.join(WORKSPACE_DIR, projectFilePath));
@@ -1390,22 +1390,18 @@ except Exception as e:
             const sanReturnType = (returnType !== null && returnType !== void 0 ? returnType : "").trim();
             console.error(`Tool call: create_method: Name='${sanMethName}', Return='${sanReturnType}', ParentPOU='${sanParentPath}', Project='${absPath}'`);
             if (!sanMethName) {
-                // **** RETURN MCP STRUCTURE ****
                 return { content: [{ type: "text", text: `Error: Method name cannot be empty.` }], isError: true };
             }
             try {
                 const escProjPath = absPath.replace(/\\/g, '\\\\');
-                // *** DEFINE script ***
                 let script = CREATE_METHOD_SCRIPT_TEMPLATE.replace("{PROJECT_FILE_PATH}", escProjPath);
                 script = script.replace("{PARENT_POU_FULL_PATH}", sanParentPath);
                 script = script.replace("{METHOD_NAME}", sanMethName);
                 script = script.replace("{RETURN_TYPE}", sanReturnType);
-                // *** END DEFINE script ***
                 console.error(">>> create_method: PREPARED SCRIPT:", script.substring(0, 500) + "...");
                 const result = yield (0, codesys_interop_1.executeCodesysScript)(script, codesysExePath, codesysProfileName);
                 console.error(">>> create_method: EXECUTION RESULT:", JSON.stringify(result));
                 const success = result.success && result.output.includes("SCRIPT_SUCCESS");
-                // **** RETURN MCP STRUCTURE ****
                 return {
                     content: [{ type: "text", text: success ? `Method '${sanMethName}' created under '${sanParentPath}' in ${absPath}. Project saved.` : `Failed to create method '${sanMethName}'. Output:\n${result.output}` }],
                     isError: !success
@@ -1413,36 +1409,36 @@ except Exception as e:
             }
             catch (e) {
                 console.error(`Error create_method ${sanMethName} in ${absPath}: ${e}`);
-                // **** RETURN MCP STRUCTURE ****
                 return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
             }
         }));
-        server.tool("compile_project", { projectFilePath: zod_1.z.string().describe("Path to project.") }, (args) => __awaiter(this, void 0, void 0, function* () {
+        server.tool("compile_project", // Tool Name
+        "Compiles (Builds) the primary application within a CODESYS project.", // Tool Description
+        {
+            projectFilePath: zod_1.z.string().describe("Path to the project file containing the application to compile (e.g., 'C:/Projects/MyPLC.project').")
+        }, (args) => __awaiter(this, void 0, void 0, function* () {
             const { projectFilePath } = args;
             let absPath = path.normalize(path.isAbsolute(projectFilePath) ? projectFilePath : path.join(WORKSPACE_DIR, projectFilePath));
             console.error(`Tool call: compile_project: ${absPath}`);
             try {
                 const escapedPath = absPath.replace(/\\/g, '\\\\');
-                // *** DEFINE script ***
                 const script = COMPILE_PROJECT_SCRIPT_TEMPLATE.replace("{PROJECT_FILE_PATH}", escapedPath);
-                // *** END DEFINE script ***
                 const result = yield (0, codesys_interop_1.executeCodesysScript)(script, codesysExePath, codesysProfileName);
                 const success = result.success && result.output.includes("SCRIPT_SUCCESS");
+                // Check for actual compile errors in the output log
                 const hasCompileErrors = result.output.includes("Compile complete --") && !/ 0 error\(s\),/.test(result.output);
                 let message = success ? `Compilation initiated for application in ${absPath}. Check CODESYS messages for results.` : `Failed initiating compilation for ${absPath}. Output:\n${result.output}`;
                 let isError = !success; // Base error status on script success
                 if (success && hasCompileErrors) {
                     message += " WARNING: Build command reported errors in the output log.";
                     console.warn("Compile project reported build errors in the output.");
-                    // Optionally set isError = true here if compile errors should fail the tool call
+                    // Report as error if compile fails, even if script technically succeeded
                     isError = true;
                 }
-                // **** RETURN MCP STRUCTURE ****
                 return { content: [{ type: "text", text: message }], isError: isError };
             }
             catch (e) {
                 console.error(`Error compile_project ${absPath}: ${e}`);
-                // **** RETURN MCP STRUCTURE ****
                 return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
             }
         }));

package/docs/configuration.md

@@ -1,119 +1,141 @@
-# 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
+# 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codesys/mcp-toolkit",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "Model Context Protocol (MCP) server for CODESYS automation platform",
   "main": "dist/server.js",
   "bin": {