lasal-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Sven Jansen and Lasal-MCP 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

@@ -0,0 +1,198 @@
+# Sigmatek LASAL MCP Server
+
+[![CI](https://github.com/Svel26/Lasal-MCP/actions/workflows/ci.yml/badge.svg)](https://github.com/Svel26/Lasal-MCP/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/lasal-mcp.svg)](https://www.npmjs.com/package/lasal-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
+
+A Model Context Protocol (MCP) server for automating the **Sigmatek LASAL** software suite. It gives AI coding assistants (Claude, Gemini, Cursor, etc.) the ability to compile, deploy to hardware, control PLCs, read/write live values, run HMI simulations, and automate a headless browser — while the agent edits project files directly.
+
+> **Warning:** This is NOT an official Sigmatek product. This project is in active development — bugs and unpredictable behavior are likely. **Do not use on production projects** without backups or version control.
+
+## Design Philosophy
+
+The MCP only exposes tools for operations that **require an external engine or hardware** — compiling, deploying, PLC control, browser automation. For everything else (reading/editing `.st`, `.lcp`, `.lcn`, `.lss`, `.lvp`, dashboard JSON), the AI agent works with the files directly using its native file tools. This keeps the tool set small, reliable, and focused.
+
+## Features
+
+- **Build & Deploy**: Compile CLASS 2 projects, download to PLC, full deploy pipelines.
+- **PLC Control**: Start/stop PLC runtime, read/write live channel values, query state.
+- **Local Simulation (LARS)**: Run one LASAL program per LARS instance — one workspace per station (PLC + HMI) so both run simultaneously on separate ports. Point stations at the local runtime with a single call, compile/download/start/read values exactly like a real PLC, and browse the HMI via DataService. No hardware needed.
+- **CLASS 2 Batch Engine**: Create/delete networks, add/remove objects, manage connections, configure tasks — operations that require the CLASS 2 scripting engine.
+- **VISUDesigner Engine**: Sync datapoints, manage text lists/schemes/media, publish, download to HMI.
+- **HMI Simulation**: Local web runtime via LasalVISUDataService with headless Edge browser automation for visual verification.
+- **PLC Diagnostics**: Tracing, file transfer, static code analysis.
+- **Project Guide**: Built-in resource (`lasal://guide`) documenting all LASAL file formats so the agent can edit project files directly.
+
+## Prerequisites
+
+- **Windows OS** (Sigmatek LASAL suite runs exclusively on Windows).
+- **Node.js** v18 or higher.
+- **Sigmatek LASAL Suite**:
+  - **LASAL CLASS 2** (PLC engineering).
+  - **VISUDesigner** (HMI design).
+
+## Quick Start (with `npx`)
+
+No repository clone or build required — configure your favorite MCP client to run directly via `npx`:
+
+### Claude Desktop
+
+Add to `%APPDATA%\Claude\claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "lasal-mcp": {
+      "command": "npx",
+      "args": ["-y", "lasal-mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to your project's `.cursor/mcp.json` (or global Cursor MCP settings):
+
+```json
+{
+  "mcpServers": {
+    "lasal-mcp": {
+      "command": "npx",
+      "args": ["-y", "lasal-mcp"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+Run:
+
+```bash
+claude mcp add lasal-mcp npx -y lasal-mcp
+```
+
+---
+
+## Local Installation & Setup (for Developers)
+
+```bash
+git clone https://github.com/Svel26/Lasal-MCP.git
+cd Lasal-MCP
+npm install
+npm run build
+```
+
+When running from a local clone, point your MCP client to:
+
+```json
+{
+  "mcpServers": {
+    "lasal-mcp": {
+      "command": "node",
+      "args": ["C:/path/to/Lasal-MCP/dist/server.js"]
+    }
+  }
+}
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `LASAL_CLASS2_EXE` | `C:\Program Files (x86)\Sigmatek\Lasal\Class2\Bin\Lasal2.exe` | CLASS 2 IDE path |
+| `LASAL_VISUDESIGNER_EXE` | `C:\Program Files\Sigmatek\Lasal\VISUDesigner\VISUDesigner.exe` | VISUDesigner path |
+| `LASAL_DATASERVICE_EXE` | auto-discovered (latest version) | DataService path |
+| `LASAL_EDGE_EXE` | auto-discovered | Edge browser path |
+| `LASAL_MCP_TIMEOUT_COMPILE` | `600000` | Compile timeout (ms) |
+| `LASAL_MCP_TIMEOUT_DOWNLOAD` | `600000` | Download timeout (ms) |
+| `LASAL_MCP_TIMEOUT_VISU` | `300000` | Visu operation timeout (ms) |
+| `LASAL_MCP_TIMEOUT_SCRIPT` | `120000` | Script execution timeout (ms) |
+| `LASAL_LARS_EXE` | `C:\Program Files (x86)\Sigmatek\Lars\Lars.exe` | LARS runtime path |
+| `LASAL_LARS_CONFIG` | `%APPDATA%\lasalos2.xml` | LARS workspace config file |
+| `LASAL_MCP_HMI_DIR` | `C:\lslvisu` | Local HMI runtime directory |
+| `LASAL_MCP_SCRATCH_MAX_AGE_H` | `24` | Hours before temp files are cleaned |
+
+## Available Tools
+
+### Engine & Hardware Tools (MCP)
+
+| Tool | Description |
+|---|---|
+| `select_project` | Set the active project root directory. |
+| `lasal_status` | Check project, stations, engines, processes, HMI health. |
+| `manage_class2` | Open or close the CLASS 2 IDE. |
+| `manage_visudesigner` | Open or close VISUDesigner. |
+| `build_project` | Compile or download to PLC. |
+| `control_plc` | Start, stop, or query PLC runtime state. |
+| `plc_values` | Read/write live channel values on a running PLC. |
+| `lars_runtime` | Local LARS simulation: list/setup workspaces per station, start/stop, point stations at LARS (`set_station_target`), revert (`restore`), switch ARM projects to the PC target (`target_pc`). |
+| `apply_project_changes` | CLASS 2 batch engine operations (networks, objects, connections, tasks). |
+| `visu_project` | VISUDesigner engine operations (text lists, schemes, media, publish, download). |
+| `hmi_runtime` | Start/stop local HMI web simulation (DataService). |
+| `hmi_browser` | Headless Edge browser for HMI testing and screenshots. |
+| `plc_diagnostics` | Tracing, file transfer, static code analysis. |
+| `deploy_all` | Full pipeline: compile → download → start PLC → sync visu → start HMI. |
+
+### Direct File Editing (no MCP needed)
+
+The agent edits these files directly with its native file tools:
+
+| File | Format | Encoding | What it contains |
+|---|---|---|---|
+| `.lsm` | XML | latin1 | Solution — lists all stations |
+| `.lss` | XML | latin1 | Station settings — target IP, project references |
+| `.lcp` | XML | latin1 | CLASS 2 project manifest — class and network file paths |
+| `.st` | XML + ST | latin1 | Class source — XML header + Structured Text body |
+| `.lcn` | XML | latin1 | Network definitions — objects, connections, init values |
+| `.lvp` | Mixed | utf-8 | VISUDesigner project manifest |
+| Dashboard JSON | JSON | utf-8 | HMI dashboards, windows, controls, property bindings |
+
+See the built-in `lasal://guide` resource for detailed file format documentation.
+
+## Development
+
+```bash
+npm run dev          # Watch mode
+npm test             # Run tests (Vitest)
+npm run test:watch   # Tests in watch mode
+npm run lint         # ESLint
+npm run format       # Prettier
+npm run inspector    # MCP Inspector for interactive debugging
+```
+
+## Simulating without hardware (LARS)
+
+LARS (LASAL Runtime System) runs LASAL programs on a normal PC. Since each LARS
+instance runs one program, the MCP creates one workspace per station:
+
+1. `lars_runtime setup` — creates workspaces for every station in the selected solution (distinct ports per instance).
+2. `lars_runtime start <station>` — launches the LARS window for that station.
+3. `lars_runtime set_station_target <station>` — points the station's `.lss` at the LARS instance.
+4. Now `build_project`, `control_plc`, and `plc_values` work unchanged against the local runtime.
+5. `lars_runtime restore <station>` — reverts the `.lss` to the real hardware target.
+
+Notes:
+- Projects compiled for `Processor="ARM"` (most machine PLCs) need
+  `lars_runtime target_pc` first — LARS is an x86 runtime and rejects ARM images.
+- HMI panel / Local stations are already PC-targeted and work directly.
+- Downloads to LARS automatically include the PC loader (`addLoaderAnyway`).
+- `hmi_runtime` remaps published stations.json entries to running LARS instances,
+  so the web HMI talks to the local simulation.
+
+## Contributing
+
+Contributions are welcome! Please check out [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on code standards, adding tools, and submitting pull requests.
+
+## Releasing & CI/CD
+
+Automated releases and publishing to npm are powered by GitHub Actions. Releases can be triggered manually via workflow dispatch with automated version bumping or by pushing version tags (`v*.*.*`).
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).
+

package/dist/core/envelope.js

@@ -0,0 +1,8 @@
+export function truncateArray(arr, limit, label) {
+    if (arr.length <= limit)
+        return { items: arr };
+    return {
+        items: arr.slice(0, limit),
+        truncated: `Showing ${limit} of ${arr.length} ${label}. Use filters to narrow results.`,
+    };
+}

package/dist/core/errors.js

@@ -0,0 +1,12 @@
+export const ERROR_CODES = {
+    PLC_UNREACHABLE: "PLC_UNREACHABLE",
+    PROJECT_LOCKED: "PROJECT_LOCKED",
+    COMPILE_FAILED: "COMPILE_FAILED",
+    CHANNEL_NOT_FOUND: "CHANNEL_NOT_FOUND",
+    PROJECT_NOT_FOUND: "PROJECT_NOT_FOUND",
+    TRANSIENT: "TRANSIENT",
+};
+export function isTransientError(errors) {
+    const transientPatterns = [/connect/i, /timeout/i, /offline/i, /socket/i, /1954/i];
+    return errors.some((err) => transientPatterns.some((p) => p.test(err)));
+}

package/dist/core/http.js

@@ -0,0 +1,19 @@
+import * as http from "http";
+export function checkHttpHealth(url, timeoutMs = 1000, anyResponse = false) {
+    return new Promise((resolve) => {
+        try {
+            const req = http.get(url, { timeout: timeoutMs }, (res) => {
+                resolve(anyResponse || res.statusCode === 200 || res.statusCode === 302 || res.statusCode === 301);
+                res.resume();
+            });
+            req.on("error", () => resolve(false));
+            req.on("timeout", () => {
+                req.destroy();
+                resolve(false);
+            });
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}

package/dist/core/process.js

@@ -0,0 +1,30 @@
+import { execSync } from "child_process";
+export function isPidRunning(pid) {
+    try {
+        execSync(`tasklist /FI "PID eq ${pid}" | findstr ${pid}`, { stdio: "pipe" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function getPortForPid(pid) {
+    try {
+        const out = execSync(`powershell -Command "(Get-NetTCPConnection -OwningProcess ${pid} -State Listen).Port"`, {
+            encoding: "utf-8",
+        }).trim();
+        const ports = out
+            .split(/[\r\n]+/)
+            .map((p) => parseInt(p.trim()))
+            .filter((p) => !isNaN(p) && p > 0);
+        if (ports.length > 0) {
+            ports.sort((a, b) => a - b);
+            const port = ports[0];
+            if (port !== undefined) {
+                return port;
+            }
+        }
+    }
+    catch { }
+    return 9980;
+}

package/dist/core/response.js

@@ -0,0 +1,37 @@
+import { respond } from "../utils/respond.js";
+export function batchToStepResult(br) {
+    return {
+        ok: br.ok,
+        durationMs: br.durationMs,
+        ...(br.errors.length ? { errors: br.errors } : {}),
+        ...(br.warnings.length ? { warnings: br.warnings } : {}),
+        ...(br.logTail.length ? { logTail: br.logTail } : {}),
+        logPath: br.logPath,
+        hints: br.hints,
+        timedOut: br.timedOut,
+    };
+}
+export function visuToStepResult(vr) {
+    return {
+        ok: vr.ok,
+        durationMs: vr.durationMs,
+        ...(vr.errors.length ? { errors: vr.errors } : {}),
+        ...(vr.warnings.length ? { warnings: vr.warnings } : {}),
+        logPath: vr.logPath,
+        hints: vr.hints,
+        timedOut: vr.timedOut,
+    };
+}
+export function batchResultToResponse(br, extra) {
+    const body = {
+        ok: br.ok,
+        durationMs: br.durationMs,
+        ...(br.errors.length ? { errors: br.errors } : {}),
+        ...(br.warnings.length ? { warnings: br.warnings } : {}),
+        ...(br.logTail.length ? { logTail: br.logTail } : {}),
+        logPath: br.logPath,
+        ...(br.hints?.length ? { hints: br.hints } : {}),
+        ...extra,
+    };
+    return respond(body);
+}

package/dist/core/scratch.js

@@ -0,0 +1,6 @@
+import { existsSync, mkdirSync } from "fs";
+import { SCRATCH } from "../utils/engine.js";
+export function ensureScratch() {
+    if (!existsSync(SCRATCH))
+        mkdirSync(SCRATCH, { recursive: true });
+}

package/dist/core/staticServer.js

@@ -0,0 +1,88 @@
+import * as http from "http";
+import { createReadStream, existsSync, statSync } from "fs";
+import { join, normalize, extname } from "path";
+const MIME = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".mjs": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".svg": "image/svg+xml",
+    ".ico": "image/x-icon",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+    ".ttf": "font/ttf",
+    ".otf": "font/otf",
+    ".wasm": "application/wasm",
+    ".mp4": "video/mp4",
+    ".mp3": "audio/mpeg",
+    ".pdf": "application/pdf",
+    ".lang": "application/octet-stream",
+};
+let server = null;
+let servedRoot = null;
+export function getStaticServerPort() {
+    const addr = server?.address();
+    return addr && typeof addr === "object" ? addr.port : null;
+}
+/** Serve `rootDir` on 127.0.0.1. Reuses the running server if it already serves the same root. */
+export function startStaticServer(rootDir, preferredPort = 9982) {
+    if (server && servedRoot === rootDir) {
+        const port = getStaticServerPort();
+        if (port)
+            return Promise.resolve(port);
+    }
+    stopStaticServer();
+    server = http.createServer((req, res) => {
+        try {
+            const urlPath = decodeURIComponent((req.url ?? "/").split("?")[0] ?? "/");
+            let filePath = normalize(join(rootDir, urlPath));
+            if (!filePath.startsWith(normalize(rootDir))) {
+                res.writeHead(403).end();
+                return;
+            }
+            if (existsSync(filePath) && statSync(filePath).isDirectory()) {
+                filePath = join(filePath, "index.html");
+            }
+            if (!existsSync(filePath)) {
+                res.writeHead(404).end();
+                return;
+            }
+            res.writeHead(200, {
+                "Content-Type": MIME[extname(filePath).toLowerCase()] ?? "application/octet-stream",
+                "Cache-Control": "no-cache",
+            });
+            createReadStream(filePath).pipe(res);
+        }
+        catch {
+            res.writeHead(500).end();
+        }
+    });
+    servedRoot = rootDir;
+    return new Promise((resolve, reject) => {
+        server.once("error", (err) => {
+            if (err.code === "EADDRINUSE") {
+                // Preferred port taken — fall back to an ephemeral port
+                server.listen(0, "127.0.0.1", () => resolve(getStaticServerPort()));
+            }
+            else {
+                reject(err);
+            }
+        });
+        server.listen(preferredPort, "127.0.0.1", () => resolve(getStaticServerPort()));
+    });
+}
+export function stopStaticServer() {
+    if (server) {
+        try {
+            server.close();
+        }
+        catch { }
+        server = null;
+        servedRoot = null;
+    }
+}

package/dist/server.js

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { selectProjectSchema, selectProjectHandler } from "./tools/selectProject.js";
+import { lasalStatusSchema, lasalStatusHandler } from "./tools/status.js";
+import { manageVisuDesignerSchema, manageVisuDesignerHandler, manageClass2Schema, manageClass2Handler, } from "./tools/lasalApps.js";
+import { deployAllSchema, deployAllHandler } from "./tools/deployAll.js";
+import { applyProjectChangesSchema, applyProjectChangesHandler } from "./tools/applyProjectChanges.js";
+import { buildProjectSchema, buildProjectHandler, controlPlcSchema, controlPlcHandler, plcValuesSchema, plcValuesHandler, } from "./tools/plcControl.js";
+import { visuProjectSchema, visuProjectHandler } from "./tools/visuControl.js";
+import { hmiRuntimeSchema, hmiRuntimeHandler } from "./tools/hmiRuntime.js";
+import { hmiBrowserSchema, hmiBrowserHandler } from "./tools/hmiBrowser.js";
+import { plcDiagnosticsSchema, plcDiagnosticsHandler } from "./tools/plcDiagnostics.js";
+import { larsRuntimeSchema, larsRuntimeHandler } from "./tools/larsRuntime.js";
+import { cleanupScratch } from "./utils/engine.js";
+const server = new McpServer({
+    name: "lasal-mcp",
+    version: "0.1.0",
+});
+// ─── Project management ──────────────────────────────────────────────────────
+server.tool("select_project", "Set the active LASAL project by directory path. Call first — all other tools default to this project.", selectProjectSchema, selectProjectHandler);
+server.tool("lasal_status", "Check project selection, station discovery, PLC/HMI reachability, engine paths, running processes, and HMI runtime health. Call to orient or diagnose connection issues.", lasalStatusSchema, lasalStatusHandler);
+server.tool("manage_class2", "Open or close the LASAL CLASS 2 IDE GUI. Close before running batch operations.", manageClass2Schema, manageClass2Handler);
+server.tool("manage_visudesigner", "Open or close the VISUDesigner GUI. Close before running automated visu operations.", manageVisuDesignerSchema, manageVisuDesignerHandler);
+// ─── Build, deploy, PLC control ──────────────────────────────────────────────
+server.tool("build_project", "Compile the CLASS 2 project or download it to the PLC. Compilation kills CLASS 2 IDE. Download pings the PLC first.", buildProjectSchema, buildProjectHandler);
+server.tool("control_plc", "Start, stop, or query PLC runtime state. Pings the target PLC before start/stop.", controlPlcSchema, controlPlcHandler);
+server.tool("plc_values", "Read or write live channel values on a running PLC. Channels use 'ObjectName.ChannelName' format. Auto-coerces types based on ST declarations.", plcValuesSchema, plcValuesHandler);
+server.tool("apply_project_changes", "Run CLASS 2 batch engine operations that cannot be done by editing files directly: create/delete/rename networks, add/remove/rename objects, create/delete connections, set init values, configure tasks, compile, download. Kills CLASS 2 IDE before running.", applyProjectChangesSchema, applyProjectChangesHandler);
+server.tool("plc_diagnostics", "Run PLC diagnostics: trace recording, file upload/download/delete on PLC, or static code analysis.", plcDiagnosticsSchema, plcDiagnosticsHandler);
+// ─── LARS local runtime simulation ───────────────────────────────────────────
+server.tool("lars_runtime", "Manage local LARS (LASAL Runtime System) simulation instances. LARS runs one program per instance — " +
+    "use one workspace per station (PLC + HMI) so both run simultaneously on separate ports. " +
+    "Actions: list (auto-cleans stale workspaces), setup (create workspaces for all stations), start (auto-creates the workspace " +
+    "if the station is known but unconfigured), stop, remove, gc (lazy cleanup of unreferenced workspaces), " +
+    "set_station_target (point a station's .lss at its LARS instance), restore (revert .lss to the real target. " +
+    "After set_station_target, build_project/control_plc/plc_values/deploy_all operate on the LARS instance automatically.", larsRuntimeSchema, larsRuntimeHandler);
+// ─── VISUDesigner engine operations ──────────────────────────────────────────
+server.tool("visu_project", "Run VISUDesigner engine operations: update stations, publish, manage text lists/schemes/media/code modules, set datapoint properties, or download to HMI. These need the VISUDesigner engine — for direct dashboard JSON editing, edit the files in the project directly.", visuProjectSchema, visuProjectHandler);
+// ─── Deploy pipeline ─────────────────────────────────────────────────────────
+server.tool("deploy_all", "Full deploy pipeline: compile → download PLC → start PLC → verify state → update Visu stations → download Visu → start HMI runtime. Each step is optional via flags.", deployAllSchema, deployAllHandler);
+// ─── HMI runtime & browser ──────────────────────────────────────────────────
+server.tool("hmi_runtime", "Start, stop, or check the local HMI web simulation (LasalVISUDataService). Publishes the project, copies webroot, and spawns the DataService. Use hmi_browser to interact with it afterwards.", hmiRuntimeSchema, hmiRuntimeHandler);
+server.tool("hmi_browser", "Automate a headless Edge browser to test the HMI. Actions: open (navigate), screenshot (capture viewport or element), console (read logs/errors), eval (run JS), click, type, wait, close. ALWAYS use this after deploy to visually verify the HMI works.", hmiBrowserSchema, hmiBrowserHandler);
+// ─── Resource: LASAL file format guide ───────────────────────────────────────
+server.resource("LASAL Project Guide", "lasal://guide", {
+    description: "Complete guide to LASAL file formats, file editing, HMI debugging, and the runtime JS API",
+    mimeType: "text/markdown",
+}, async () => {
+    return {
+        contents: [
+            {
+                uri: "lasal://guide",
+                mimeType: "text/markdown",
+                text: LASAL_GUIDE,
+            },
+        ],
+    };
+});
+const LASAL_GUIDE = `# LASAL Project Guide
+
+## File Format Reference
+
+All LASAL project files use **ISO-8859-1 (latin1)** encoding unless otherwise noted.
+
+### Solution file (.lsm)
+XML file at the project root. Lists all stations in the project.
+
+\`\`\`xml
+<Solution>
+  <SlnStation Name="PLC">
+    <StationFile Path="PLC\\PLC.lss"/>
+  </SlnStation>
+  <SlnStation Name="HMI">
+    <StationFile Path="HMI\\HMI.lss"/>
+  </SlnStation>
+</Solution>
+\`\`\`
+
+### Station settings (.lss)
+XML file per station. Contains connection settings and project file references.
+
+Key elements:
+- \`<TCPIP IP="10.195.0.50" PORT="1954" SSLTLS="0"/>\` — target IP for downloads
+- \`<ClassProject Path="PLC.lcp"/>\` — link to the CLASS 2 project
+- \`<VisualProject Path="HMI.lvp"/>\` — link to the VISUDesigner project
+
+To change the target IP, surgically edit the \`IP\` attribute in the \`<TCPIP>\` element.
+Do NOT rewrite the entire .lss — it contains other settings that must be preserved.
+
+### CLASS 2 project (.lcp)
+XML project manifest. Lists all class files and network files in the project.
+
+\`\`\`xml
+<ClassProject Version="...">
+  <Header>...</Header>
+  <ClassFiles>
+    <File Path="Motor.st"/>
+    <File Path="Sensor.st"/>
+  </ClassFiles>
+  <NetworkFiles>
+    <File Path="Main.lcn"/>
+  </NetworkFiles>
+</ClassProject>
+\`\`\`
+
+Use it to discover which .st and .lcn files belong to the project.
+Paths are relative to the .lcp file's directory.
+
+### Class source (.st)
+Structured Text class files. Each .st file defines one class. The format has two parts:
+
+1. **XML header block** (between \`(* BEGIN_CLASS ... END_CLASS *)\` comment markers):
+   Contains class metadata — servers, clients, methods, inheritance.
+
+2. **ST body**: Variable declarations and method implementations in IEC 61131-3 Structured Text.
+
+Example structure:
+\`\`\`
+(* BEGIN_CLASS
+<ClassDef Name="Motor" SuperClass="UserDef0" ...>
+  <Servers>
+    <Server Name="s_Speed" ... />
+  </Servers>
+  <Clients>
+    <Client Name="c_Enable" ... />
+  </Clients>
+  <Methods>
+    <Method Name="CyWork" ... />
+  </Methods>
+</ClassDef>
+END_CLASS *)
+
+//Variables:
+  s_Speed : SvrCh_DINT;
+  c_Enable : CltCh_BOOL;
+  localVar : DINT;
+
+//Methods:
+FUNCTION Motor::CyWork
+  IF c_Enable THEN
+    s_Speed := 100;
+  END_IF;
+END_FUNCTION
+\`\`\`
+
+**Server channels** (outputs): Prefixed \`s_\` by convention. Types like \`SvrCh_DINT\`, \`SvrCh_BOOL\`, \`SvrCh_REAL\`.
+**Client channels** (inputs): Prefixed \`c_\` by convention. Types like \`CltCh_DINT\`, \`CltChCmd_General2\`.
+
+When adding a server/client:
+1. Add the XML element in the header block (\`<Server>\` or \`<Client>\`)
+2. Add the variable declaration in the \`//Variables:\` section
+3. Both must match in name
+
+When editing .st files, always use **latin1** encoding. Non-latin1 characters will corrupt the file.
+
+### Network files (.lcn)
+XML files defining object networks — instances of classes and their connections.
+
+\`\`\`xml
+<Network Name="Main">
+  <Objects>
+    <Object Name="Motor1" ClassName="Motor" ...>
+      <InitValues>
+        <InitValue Server="s_Speed" Value="50"/>
+      </InitValues>
+    </Object>
+  </Objects>
+  <Connections>
+    <Connection FromObject="Sensor1" FromClient="c_MotorSpeed" ToObject="Motor1" ToServer="s_Speed"/>
+  </Connections>
+</Network>
+\`\`\`
+
+Network operations (create/delete networks, add/remove objects, create connections) **require the CLASS 2 batch engine** — use \`apply_project_changes\` for these.
+Init values and connections reference object instances, not class definitions.
+
+### Class header (.h)
+Auto-generated companion to .st files. Contains C-like declarations. Usually read-only — changes are made to .st files.
+
+### VISUDesigner project (.lvp)
+Binary/text project manifest for the HMI side. References dashboard JSON files, datapoint configurations, text lists, schemes, and media.
+
+### Dashboard JSON files
+Located in subdirectories of the .lvp project folder. These are UTF-8 JSON files defining HMI dashboard layouts with controls, properties, and data bindings.
+
+Dashboard files can be edited directly — they are standard JSON. Each element has:
+- \`controlId\`: the control type (e.g. "sigTextField", "sigButton")
+- \`name\`: unique element name within the dashboard
+- Properties bound to datapoints, constants, schemes, or text references
+
+## Recommended Workflow
+
+1. **Orient**: Call \`lasal_status\` to check project state and connectivity.
+2. **Select**: Call \`select_project\` with your project path.
+3. **Edit code**: Read and edit .st files directly using file tools. Use latin1 encoding.
+4. **Structural changes**: Use \`apply_project_changes\` for network/object/connection operations that need the CLASS 2 engine.
+5. **Build & Deploy**: Call \`build_project\` to compile, then \`deploy_all\` to push everything.
+6. **Verify HMI**: Call \`hmi_runtime\` to start simulation, then \`hmi_browser\` to open, screenshot, and interact.
+7. **Live debug**: Use \`plc_values\` to read/write PLC channels in real time.
+
+## HMI Runtime JavaScript API
+
+Within the HMI web environment (via \`hmi_browser\` eval):
+\`\`\`javascript
+// Read a datapoint
+sig.datapoint.get('Motor1.s_Speed')
+
+// Write a datapoint
+sig.datapoint.set('Motor1.s_Speed', 150)
+
+// Get active alarms
+sig.alarm.getActiveAlarms()
+
+// Get current view
+document.querySelector('sig-app').activeView
+\`\`\`
+
+## Important Notes
+
+- All .st/.lcp/.lcn/.lss files are **latin1** encoded — always read/write with latin1
+- The CLASS 2 IDE must be **closed** before batch operations or .st file writes
+- VISUDesigner must be **closed** before visu engine operations
+- Network operations (create network, add object, create connection) **require the batch engine** — you cannot do these by editing files alone
+- Dashboard JSON files **can** be edited directly — no engine needed
+- After any code changes, **always compile** to check for errors before deploying
+`;
+cleanupScratch();
+const transport = new StdioServerTransport();
+await server.connect(transport);