@codesys/mcp-toolkit 1.1.0 → 1.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +6 -12
  2. package/dist/codesys_interop.js +82 -47
  3. package/dist/server.js +972 -112
  4. package/docs/configuration.md +141 -119
  5. package/package.json +48 -48
package/docs/configuration.md CHANGED
@@ -1,119 +1,141 @@
1
- # Configuration Guide
2
-
3
- This guide explains how to configure the CODESYS MCP Toolkit with MCP clients.
4
-
5
- ## Claude Desktop Configuration
6
-
7
- Claude Desktop is a popular MCP client that can use the CODESYS MCP Toolkit.
8
-
9
- ### Finding the Configuration File
10
-
11
- The configuration file is located at:
12
- - Windows: `C:\Users\<YourUsername>\AppData\Roaming\Claude\claude_desktop_config.json`
13
- - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
14
-
15
- ### Adding the CODESYS MCP Server Entry
16
-
17
- Edit the configuration file and add the CODESYS MCP server to the `mcpServers` object:
18
-
19
- ```json
20
- {
21
- "mcpServers": {
22
- "codesys_local": {
23
- "command": "npx",
24
- "args": [
25
- "-y",
26
- "@codesys/mcp-toolkit",
27
- "--codesys-path", "C:\\Program Files\\CODESYS 3.5.21.0\\CODESYS\\Common\\CODESYS.exe",
28
- "--codesys-profile", "CODESYS V3.5 SP21"
29
- ]
30
- }
31
- }
32
- }
33
- ```
34
-
35
- ### Configuration Parameters
36
-
37
- - `command`: Use `npx` to execute the package
38
- - `args`: Array of arguments
39
- - `-y`: Automatically accept npm install prompts
40
- - `@codesys/mcp-toolkit`: The package name
41
- - `--codesys-path`: Path to your CODESYS.exe
42
- - `--codesys-profile`: Your CODESYS profile name
43
-
44
- ### Customizing for Your Environment
45
-
46
- You must customize:
47
- 1. `--codesys-path`: Set to the actual path of your CODESYS executable
48
- 2. `--codesys-profile`: Set to the exact name of your CODESYS profile
49
-
50
- **Important Notes:**
51
- - Use double backslashes (`\\`) in Windows paths in JSON
52
- - The profile name must match exactly what appears in CODESYS
53
-
54
- ### Applying Changes
55
-
56
- After modifying the configuration:
57
- 1. Save the file
58
- 2. Restart Claude Desktop completely
59
- 3. Claude should now have access to the CODESYS MCP server
60
-
61
- ## Command-Line Options
62
-
63
- When using the toolkit directly, the following options are available:
64
-
65
- ```
66
- Usage: codesys-mcp-toolkit [options]
67
-
68
- Options:
69
- -V, --version output the version number
70
- -e, --codesys-path <path> Path to CODESYS executable
71
- -p, --codesys-profile <profile> CODESYS profile name
72
- -h, --help display help for command
73
- ```
74
-
75
- ## Verifying Configuration
76
-
77
- To verify your configuration:
78
-
79
- 1. In Claude Desktop, ask:
80
- ```
81
- Can you please check the status of the CODESYS Local server?
82
- ```
83
-
84
- 2. Claude should use the `project-status` resource and return information about the CODESYS server connection.
85
-
86
- ## Multiple CODESYS Installations
87
-
88
- If you have multiple CODESYS installations, you can create multiple server entries with different names:
89
-
90
- ```json
91
- {
92
- "mcpServers": {
93
- "codesys_3_5_21": {
94
- "command": "npx",
95
- "args": [
96
- "-y",
97
- "@codesys/mcp-toolkit",
98
- "--codesys-path", "C:\\Program Files\\CODESYS 3.5.21.0\\CODESYS\\Common\\CODESYS.exe",
99
- "--codesys-profile", "CODESYS V3.5 SP21"
100
- ]
101
- },
102
- "codesys_3_5_19": {
103
- "command": "npx",
104
- "args": [
105
- "-y",
106
- "@codesys/mcp-toolkit",
107
- "--codesys-path", "C:\\Program Files\\CODESYS 3.5.19.0\\CODESYS\\Common\\CODESYS.exe",
108
- "--codesys-profile", "CODESYS V3.5 SP19"
109
- ]
110
- }
111
- }
112
- }
113
- ```
114
-
115
- ## Next Steps
116
-
117
- - Try some [basic examples](examples.md)
118
- - Learn about the [available tools and resources](api.md)
119
- - Check the [troubleshooting guide](troubleshooting.md) if you encounter issues
1
+ # Configuration Guide
2
+
3
+ This guide explains how to configure the CODESYS MCP Toolkit for use with MCP clients, specifically focusing on Claude Desktop.
4
+
5
+ ## Claude Desktop Configuration
6
+
7
+ Claude Desktop is a popular MCP client that can use the CODESYS MCP Toolkit.
8
+
9
+ ### Finding the Configuration File
10
+
11
+ The configuration file is typically located at:
12
+ * **Windows:** `C:\Users\<YourUsername>\AppData\Roaming\Claude\settings.json` (or `claude_desktop_config.json` in older versions)
13
+ * **macOS:** `~/Library/Application Support/Claude/settings.json` (or `claude_desktop_config.json`)
14
+ * **Linux:** `~/.config/Claude/settings.json` (or `claude_desktop_config.json`)
15
+
16
+ *(If you can't find `settings.json`, look for `claude_desktop_config.json`)*
17
+
18
+ ### Recommended Configuration: Direct Command
19
+
20
+ 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**.
21
+
22
+ Edit the configuration file and add the CODESYS MCP server to the `mcpServers` object:
23
+
24
+ ```json
25
+ {
26
+ "mcpServers": {
27
+ // ... other servers ...
28
+ "codesys_local": {
29
+ "command": "codesys-mcp-tool", // <<< Use the direct command name
30
+ "args": [
31
+ // Pass arguments directly to the tool using flags
32
+ "--codesys-path", "C:\\Program Files\\Path\\To\\Your\\CODESYS\\Common\\CODESYS.exe", // Customize this path!
33
+ "--codesys-profile", "Your CODESYS Profile Name" // Customize this profile name!
34
+ // Optional: Add --workspace "/path/to/your/projects" if needed
35
+ ]
36
+ }
37
+ // ... other servers ...
38
+ }
39
+ }
40
+ ```
41
+
42
+ ### Why Direct Command is Recommended
43
+
44
+ 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.
45
+
46
+ ### Customizing for Your Environment
47
+
48
+ You **must** customize:
49
+ 1. `--codesys-path`: Set this value to the **full and correct path** of your specific `CODESYS.exe` executable file.
50
+ 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).
51
+
52
+ **Important Notes:**
53
+ * Use double backslashes (`\\`) for paths in the JSON file if you are on Windows.
54
+ * The profile name must match *exactly*, including capitalization and spacing.
55
+ * Ensure `codesys-mcp-tool` is accessible in the system PATH where Claude Desktop runs. Global installation via `npm install -g` usually handles this.
56
+
57
+ ### Applying Changes
58
+
59
+ After modifying the configuration:
60
+ 1. Save the `settings.json` file.
61
+ 2. **Restart Claude Desktop completely** (ensure it's fully closed and reopened).
62
+ 3. Claude should now attempt to connect to the CODESYS MCP server using the direct command.
63
+
64
+ ### Alternative (Not Recommended): Using `npx`
65
+
66
+ If you cannot use the direct command method for some reason, you can try `npx`, but be aware of the potential issues mentioned above.
67
+
68
+ ```json
69
+ // Example using npx (POTENTIALLY PROBLEMATIC - USE WITH CAUTION):
70
+ {
71
+ "mcpServers": {
72
+ "codesys_local": {
73
+ "command": "npx",
74
+ "args": [
75
+ "-y", // Tells npx to install temporarily if not found globally
76
+ "@codesys/mcp-toolkit",
77
+ // Arguments for the tool MUST come AFTER the package name
78
+ "--codesys-path", "C:\\Program Files\\Path\\To\\Your\\CODESYS\\Common\\CODESYS.exe",
79
+ "--codesys-profile", "Your CODESYS Profile Name"
80
+ // Optional: "--workspace", "/path/to/your/projects"
81
+ ]
82
+ }
83
+ }
84
+ }
85
+ ```
86
+ *If you encounter errors with `npx`, switch to the recommended Direct Command method.*
87
+
88
+ ## Command-Line Options (for `codesys-mcp-tool`)
89
+
90
+ When running `codesys-mcp-tool` directly or configuring it in your MCP client, you can use these arguments:
91
+
92
+ * `-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).
93
+ * `-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).
94
+ * `-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.
95
+ * `-V, --version`: Output the version number.
96
+ * `-h, --help`: Display help for command.
97
+
98
+ ## Verifying Configuration
99
+
100
+ To verify your configuration within Claude Desktop:
101
+
102
+ 1. After restarting Claude with the correct configuration, wait for the server to connect (check logs if needed).
103
+ 2. Ask Claude:
104
+ ```
105
+ Can you please check the status of the CODESYS Local server?
106
+ ```
107
+ (Replace `CODESYS Local` if you used a different key in `mcpServers`).
108
+
109
+ 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).
110
+
111
+ ## Multiple CODESYS Installations
112
+
113
+ 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:
114
+
115
+ ```json
116
+ {
117
+ "mcpServers": {
118
+ "codesys_sp21": { // Unique key for this server
119
+ "command": "codesys-mcp-tool", // Direct command
120
+ "args": [
121
+ "--codesys-path", "C:\\Program Files\\CODESYS 3.5.21.0\\CODESYS\\Common\\CODESYS.exe",
122
+ "--codesys-profile", "CODESYS V3.5 SP21"
123
+ ]
124
+ },
125
+ "codesys_sp19": { // Unique key for this server
126
+ "command": "codesys-mcp-tool", // Direct command
127
+ "args": [
128
+ "--codesys-path", "C:\\Program Files\\CODESYS 3.5.19.0\\CODESYS\\Common\\CODESYS.exe",
129
+ "--codesys-profile", "CODESYS V3.5 SP19"
130
+ ]
131
+ }
132
+ // ... other servers ...
133
+ }
134
+ }
135
+ ```
136
+
137
+ ## Next Steps
138
+
139
+ * Try some [basic examples](examples.md)
140
+ * Learn about the [available tools and resources](api.md)
141
+ * Check the [troubleshooting guide](troubleshooting.md) if you encounter issues
package/package.json CHANGED
@@ -1,48 +1,48 @@
1
- {
2
- "name": "@codesys/mcp-toolkit",
3
- "version": "1.1.0",
4
- "description": "Model Context Protocol (MCP) server for CODESYS automation platform",
5
- "main": "dist/server.js",
6
- "bin": {
7
- "codesys-mcp-tool": "./dist/bin.js"
8
- },
9
- "scripts": {
10
- "test": "echo \"Error: no test specified\" && exit 1",
11
- "build": "tsc",
12
- "prepare": "npm run build",
13
- "start": "node ./dist/server.js"
14
- },
15
- "keywords": [
16
- "codesys",
17
- "mcp",
18
- "modelcontextprotocol",
19
- "plc",
20
- "automation",
21
- "programming"
22
- ],
23
- "author": "Your Name <your.email@example.com>",
24
- "license": "MIT",
25
- "type": "commonjs",
26
- "repository": {
27
- "type": "git",
28
- "url": "git+https://github.com/johannesPettersson80/codesys-mcp-toolkit.git"
29
- },
30
- "homepage": "https://github.com/johannesPettersson80/codesys-mcp-toolkit#readme",
31
- "bugs": {
32
- "url": "https://github.com/johannesPettersson80/codesys-mcp-toolkit/issues"
33
- },
34
- "engines": {
35
- "node": ">=18.0.0"
36
- },
37
- "dependencies": {
38
- "@modelcontextprotocol/sdk": "^1.10.2",
39
- "axios": "^1.6.8",
40
- "yargs": "^17.7.2",
41
- "zod": "^3.24.3"
42
- },
43
- "devDependencies": {
44
- "@types/node": "^20.14.1",
45
- "@types/yargs": "^17.0.33",
46
- "typescript": "^5.5.3"
47
- }
48
- }
1
+ {
2
+ "name": "@codesys/mcp-toolkit",
3
+ "version": "1.1.3",
4
+ "description": "Model Context Protocol (MCP) server for CODESYS automation platform",
5
+ "main": "dist/server.js",
6
+ "bin": {
7
+ "codesys-mcp-tool": "./dist/bin.js"
8
+ },
9
+ "scripts": {
10
+ "test": "echo \"Error: no test specified\" && exit 1",
11
+ "build": "tsc",
12
+ "start": "node ./dist/server.js"
13
+ },
14
+ "keywords": [
15
+ "codesys",
16
+ "mcp",
17
+ "modelcontextprotocol",
18
+ "plc",
19
+ "automation",
20
+ "programming"
21
+ ],
22
+ "author": "Your Name <your.email@example.com>",
23
+ "license": "MIT",
24
+ "type": "commonjs",
25
+ "repository": {
26
+ "type": "git",
27
+ "url": "git+https://github.com/johannesPettersson80/codesys-mcp-toolkit.git"
28
+ },
29
+ "homepage": "https://github.com/johannesPettersson80/codesys-mcp-toolkit#readme",
30
+ "bugs": {
31
+ "url": "https://github.com/johannesPettersson80/codesys-mcp-toolkit/issues"
32
+ },
33
+ "engines": {
34
+ "node": ">=18.0.0"
35
+ },
36
+ "dependencies": {
37
+ "@modelcontextprotocol/sdk": "^1.10.2",
38
+ "axios": "^1.6.8",
39
+ "commander": "^11.1.0",
40
+ "yargs": "^17.7.2",
41
+ "zod": "^3.24.3"
42
+ },
43
+ "devDependencies": {
44
+ "@types/node": "^20.14.1",
45
+ "@types/yargs": "^17.0.33",
46
+ "typescript": "^5.5.3"
47
+ }
48
+ }